What gotchas are you thinking about?
> Using Sphinx also requires you to setup and configure Sphinx for your project - even more friction early on.
You can perfectly well RST without Sphinx, it depends what you want to use it for. Obviously, if you want to use for Sphinx, you need Sphinx. But otherwise, you can perfectly well use rst2pdf or rst2html with a standard RST document.
The format for RST/Sphinx code blocks is to type two periods, a space, the word "code-block", then two colons, then exactly two new lines, and at last you can write your code. Indented with four spaces. Also, you have to make sure there is a blank line between that "code-block" magic line and your preceding text. In practice, I usually manage to screw some part of this up.
The extra complexity and cognitive load makes it much harder for a developer to just write thoughts.
You can make your own directives which can optionally accept key/value parameters. This is technically superior to slapping blobs of HTML inside your Markdown, though I will concede that writing your own directives can be a bit tricky initially.
[1]: http://docutils.sourceforge.net/docs/ref/rst/directives.html
like this
:)You can do anything you need to in RST, but there's just more friction involved.
The reason it's a double colon is because a single colon acts like a normal single colon (i.e., it's not interpreted in any way), which is sometimes what you want (i.e., not every indented block is a code block).
RST, used by Sphinx, isn't quite as easy to write or to read. There are plenty of gotchas. RST adds friction.
Using Sphinx also requires you to setup and configure Sphinx for your project - even more friction early on.
The world is far better for having Markdown, and it's the right choice for most projects.
However, there is indeed a place for more complicated projects to take on the workload of a more complicated documentation system so that they can help user and developers better. Django's amazing documentation is an example of this, and a major reason for the success of the project.