4 ms·

The format for code blocks in Markdown is to indent by four or more spaces. The format for RST/Sphinx code blocks is to type two periods, a space, the word "co

The format for code blocks in Markdown is to indent by four or more spaces. 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.

forsaken 11y ago
You can do code blocks:: like this :)
- danielvf 11y ago
  Yeah - this always trips me up too, since it's two colons, not the holy Python single colon, and it's "magic" on the preceding paragraph, not the code itself. Django docs written in RST avoid doing this style. You can do anything you need to in RST, but there's just more friction involved.
  - cname 11y ago
    It's not a Python thing, though. It's a reStructuredText thing. I don't see how this syntax is more "magic" than, say, using # in Markdown to indicate a heading. 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).
shabbyrobe 11y ago
You've actually touched on one of the benefits of RST with your complaint: there's no "magic" about Sphinx's "code-block", it's just a "directive" [1]. 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 http://docutils.sourceforge.net/docs/ref/rst/directives.html

forsaken 11y ago

You can do code blocks:: like this :)

danielvf 11y ago
Yeah - this always trips me up too, since it's two colons, not the holy Python single colon, and it's "magic" on the preceding paragraph, not the code itself. Django docs written in RST avoid doing this style. You can do anything you need to in RST, but there's just more friction involved.
- cname 11y ago
  It's not a Python thing, though. It's a reStructuredText thing. I don't see how this syntax is more "magic" than, say, using # in Markdown to indicate a heading. 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).

shabbyrobe 11y ago

You've actually touched on one of the benefits of RST with your complaint: there's no "magic" about Sphinx's "code-block", it's just a "directive" [1]. 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 http://docutils.sourceforge.net/docs/ref/rst/directives.html