Tips for writing ReST / ChangeLogs

Mike Hearn

Hey team,


Markup errors. 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.


  1. Code like `foo`_ 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.
  2. 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.
  3. 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.
  4. Headings. ReST uses magic underlines to determine nesting levels of headers. If you use the wrong level you get a warning.
  5. Double backticks don’t work if you add any suffix, so ``Party``s doesn’t work even though it looks natural.
  6. 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 such changes).
  • 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.

Join to automatically receive all group messages.