Re: Tips for writing ReST / ChangeLogs

Mike Hearn

I mostly put spaces before the ‘s’ but that isn’t great and was only to save time. If someone can find a better solution that isn’t “avoid plurals” that’d be great.


Here’s another one – you don’t have to use .. sourcecode to delimit a code block. That’s only when we want highlighting. I’ve fixed a few issues where people used non-existent script names like “powershell” or tagged stuff as json when it’s actually HOCON. You can just end the preceding paragraph with :: and then indent to make it render as a code block. The IntelliJ RST plugin will highlight this.


Unfortunately the Kotlin highlighter in Pygments is really old and can’t process the latest version of the language. I tried upgrading Pygments but that didn’t help. Hopefully at some point someone will resync it with the 1.2 grammar and our inconsistent syntax highlighting will get fixed. Until then we’ll have lots of warnings about un-lexable code snippets, but we can ignore those. We also have a few pages that aren’t in the toctree, which it doesn’t like, but that is something we can sort out as part of a bigger re-org of the docs.

Join to automatically receive all group messages.