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:
- Different formatting for headers, sections, and paragraphs (unlike different number of hashes or equals in Asciidoc or Markdown)
- Internal and external references (links) with weird syntax of two backticks followed by underscore
- Double backticks for inline code formatting
- Tips, code-blocks and similar blocks indented
- …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:
- Asciidoc (or at the very least Markdown)
- GitHub integration
- GitBook theme
- 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).
