The .rst format is flexible but unusually nitpicky. I’ve been fixing markup errors in preparation for moving our design docs into the open docsite. Some mistakes crop up repeatedly so here’s a list.
- Code like
`foo https://bar.com`_ which creates a link with “foo” as the text for some reason insists that “foo” is unique in the page. This
means links that use the word “here” trigger warnings if there’s more than one of them.
The fix is to use double underscores instead of single underscores. Yep.
- Indent errors. Sphinx really cares. Watch out for
.. note:: where the other lines don’t align properly with the start. Also watch out for list items where the item body isn’t left
aligned. This breaks rendering.
- Not putting a blank line between a list item and a sub-list. The obvious way of doing it doesn’t work, Sphinx just gets confused. If you
want to change indent level there must be a blank line both before and after the level change.
- Headings. ReST uses magic underlines to determine nesting levels of headers. If you use the wrong level you get a warning.
- Double backticks don’t work if you add any suffix, so ``Party``s doesn’t work even though it looks natural.
- Sphinx really likes underscores. Writing “TRANSACTION_” with normal double quotes will trigger an error because the underscore is interpreted.
Using double backticks fixes it.
Please do test your docsite changes. On UNIX you can run “cd docs; source virtualenv/bin/activate” to enable your shell to generate the docsite, then run “make html” to get a list of errors and
warnings your changes have introduced. If it’s hard for you to run (Windows?) please file an issue in Jira and we can get it looked at, because these errors usually break rendering and look bad.
ChangeLog entries. The release notes are for advertising what’s new and interesting at a high level. Users will read release notes
before deciding to upgrade, to help them evaluate the benefits of doing it. The changelog will be read
after deciding to upgrade, as part of actually doing so.
Therefore the change log is for changes that might interest app developers, not for things like refactorings or bugfixes (usually). Examples:
- Changes that might require config file adjustments.
- Things that might affect behaviour in ways developers want to know about (but not in a backwards incompatible way, because we aren’t making
- Deprecations and what to do about them if it’s not obvious from the warnings.
- Bug fixes that are unusually likely to be hit or be unusually critical.
- New APIs that can replace app-specific code or workarounds.
An example of an unhelpful changelog
is this one (I do actually like Sphinx by the way), where figuring out “what do I actually need to know to upgrade from version X to version Y” is nearly impossible because the changelog is basically
an unordered bug tracker dump.