Since we are using rst now, let's convert the README to rst as well. I
also removed some obsolete Jekyll instructions and replaced them with
the proper Sphinx ones.
This patch enables the previously created manpages in the sphinx
configuration file. It also enables "man_show_urls" because the
manpages include several external links.
Sphinx uses .. code-block:: directives to enable highlighting:
http://sphinx-doc.org/markup/code.html#directive-code-block
Use
for i in *.rst; do
sed -i 's/code::/code-block::/g' $i
done
to update these strings to enable proper highlighting.
Note: A have disabled the windows "bash" one, because the highlighting
is broken anyway...
This extension enables the usage of .. todo:: blocks. This is quite
useful because we can encourage people to work on particular sections
of the documentation.
Increasing the font size is *not* useful due to a couple of reasons:
- It breaks the visual seperation between the headlines. It is very
hard to determine the headline levels when the font size is that big.
- It breaks the definition lists which are useful for manpages.
- It extends the line width to an unnatural value. It is not narrow
any more, but it is also not big. It just looks a bit odd.
- The regular font (on linux) renders as almost a light bold type. It
generates a "Comic Sans" experience. That does not look
professional.
Since I am not a designer and I don't know how to fix these problems in
the right way, I think the best solution is switching back to the very
sane defaults.
- Move the configuration values to the appropriate position in the file.
- Setting "html_theme_path" is not needed.
- Enable "html_last_updated_fmt". It is quite useful to determine the
last documentation update. IMO it does not harm at all.
Stefan Tatschner