Having the docs index in the repo root was a holdover from when it was
the README file. Now that it's not much use without being built, it's
better to leave the root to README, NEWS, and LICENSE - especially when
one is a html shortcut to the docs index.
- script-syntax.py now exits with 1 instead of silently catching the
error if lua or ruby are missing
- index paths are absolute (from the repo root)
- less strong suggestion for third-party packs
- re-added lua-example and test-perlin doc
- corrected and clarified Compile some more
- Fix formatting of (c) in license
- Avoid possible issues with script linting
- Move plugin docs out of Core.rst
- Fix some builtin docs, tweak other bits
The Introduction is the first page to read, and thus explains what
DFHack is, installation, basic use, and troubleshooting.
This frees up Core.rst for a detailed list of builtin commands (meant to
be complete, but I might have missed some), some other key commands, and
a discussion of init files. I also put the random notes that don't fit
anywhere at the bottom of this file.
* Remove email addresses, following a discussion on IRC (these can be
found in git logs anyway, and having them publicly-visible invites
spam)
* Remove a couple duplicate authors
* Add a few aliases
- Minor updates and clarifying edits
- Better use of markup throughout the document
- linked references to bugs and other things
- moved gui/siege-engine docs to the script
The root of the documentation tree has a different function to the short
readme we want to display on GitHub, which now links to the main docs
(or Bay12 thread, or IRC). It also renders properly on GitHub, and can
use live-updating status badges because we don't expect it to work
offline.
Building the docs now works the same way, no matter when it happens - in
a cloned repo or distributed version.
This means all the relative links keep working; and that users or
downstream distributors can rebuild the docs with extra scripts or .rst
files in place.
Finally, it eliminates a large number of potential bugs which only occur
in one build environment and are difficult to reproduce.
Also add headings and this work to future news.
Because it's a lot easier to link to bug reports this way.
The migration is mostly just a copy-paste job, but I'm using keybinding
styles where appropriate too.
Automatically generating the link target for each script saves a lot of
time and potential for errors.
Each kind-of-script page now includes a link target for that page, and
also a table of contents.
In-script markers to delimit text for Sphinx extraction now use native
docstring markers from Ruby, which is a lot more elegant in .rb scripts
- and robust, as long as the fisrt docstring is valid .rst!
Creates a single file for each kind of script (base, gui, fix...). This
includes and correctly sorts content from any .lua or .rb file under the
scripts directory. It's more robust and more readable than the old
style, and doesn't write anything in the submodules. User-added scripts
will be seamlessly added, if they have a docs section and Sphinx is run.
This mainly involved tweaking a few filenames and configuration paths to
allow consistency in all scenarios. It cleared up a few errors in the
process too!
I also clarified the placement of the LICENSE file, and finished
configuring the Alabaster style. This required moving some stuff out of
the CMake system to conf.py to avoid later breakage.
Because it's not actually that important to the user how a command is
implemented, and the docs should reflect that. This also makes them
easier to write!
This document is shown when creating pull requests and referenced
from a number of other code-related discussions, so putting the
"contributing code" section first probably makes more sense
(particularly with a TOC).
Binpatches aren't used much at the moment, so this has two purposes:
collate information so it's easier to write them again, and remove it
from other sections where it's useless.
Note that if the standalone binpatch.exe is removed, the 'patching on
disk' section can be cleanly removed from 'Using a patch' by deleting
lines 44-47 & 61-90.
Checked with a throwaway script, and added the missing entries. NEWS
now has a comment on how to use the file, which is only visible in the
raw text version. Added the documentation changes to NEWS.
No changes whatsoever are made to the licenses. Formatting is
consistent. Comments are cleaned up a little. Some quotation marks are
consistent. Added link target and links.
* Enabled internal links; a phrase in backticks is linked to the
corresponding link target and turns into the corresponding title.
* Linked all existing references in Scripts.rst
* Created corresponding link targets
* Fixed formatting of some tables of arguments.
Some very light markup is all that's needed. The underline with ====
makes each version into a linkable title and allows a table of contents
to be generated, while the `::` and blank line denotes that the rest is
a literal block.
I also shortened some very long lines, for readability.
We may want to use .rst formatting for these eventually, and maybe move
the NEWS file to docs/News.rst and docs/History.rst - but for now
including the raw text works well enough.
PeridexisErrant
Lethosor
lethosor
orthographic-pedant
expwnent