Giving up on Read the Docs, reStructuredText and Sphinx

tl;dr Stay away from Sphinx and RST.

I’m coming from Markdown and Asciidoc markup languages and can’t think of any reasons why I should keep writing documentation using reStructuredText (RST) markup language. After just a couple of days I felt as if I was going backwards.

I’m quite surprised how quickly I came to this conclusion. It took me a mere couple of days, and could attribute to the markup alternatives I tried so far.

A few of the reasons I’m leaving Sphinx and RST are as follows:

1. Different formatting for headers, sections, and paragraphs (unlike different number of hashes or equals in Asciidoc or Markdown)
2. Internal and external references (links) with weird syntax of two backticks followed by underscore
3. Double backticks for inline code formatting
4. Tips, code-blocks and similar blocks indented
5. …and few others I’m hoping to forget pretty soon

Just a heads-up if you’re into documentation writing business.

Once GitBook decided they drop support for Asciidoc and GitHub integration I’ve been looking around for a viable replacement. After over a year I haven’t found anything as pleasant as GitBook. I simply need a service that’d be like Medium or Leanpub for writing and publishing with GitBook look and feel.

I’d be very happy to have the following for writing technical documentation:

1. Asciidoc (or at the very least Markdown)
2. GitHub integration
3. GitBook theme
4. Writing experience similar to Medium (or Leanpub)

Long live Asciidoc. For now. Giving Antora a go again as I do love “writing in AsciiDoc”. The only concern with Antora is that the default theme does not look very pretty (I seem to have got used to GitBooks and Medium looks).