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.
PeridexisErrant