Customizing Your Documentation With RST Markup
00:00 In the previous lesson, I got you started with Sphinx and showed you how to build your first document. In this lesson, I’ll be diving into RST, the default markup language used by Sphinx. RST is short for reStructuredText.
01:16 Next is bold, which is done by surrounding something in paired double stars. Code is shown with double backticks. This is the one I usually confuse, as it’s single backticks in Markdown and asciidoc, so when you’re switching back and forth, it’s hard to remember.
01:32 I should probably be more generic about this than code. The result is almost always rendered as a monospace font, and depending on your theme, you may also get a different color. Note that this is just for inline.
01:50 You can add a line separator between paragraphs by using any punctuation more than four times in a row. I’ve only ever seen people use dashes for this, so I don’t swear how well it’ll work if you use something besides a dash.
02:16 Headings are kind of weird in RST. The first heading marker you use is what determines it as the title style. That’s kind of nice and flexible and everything, but it makes things a little error-prone.
02:29 The style I’m using on the left is pretty common, and if you stick with it, you’ll be good. Remember though, if you end up using these in a different order, it won’t map to what I have on the left.
02:52 Stars are used for bullet lists. Note that RST gets really finicky about the spacing here. If your bullet item ends up needing multiple lines in your text file, you need to indent to indicate it is all part of the same bullet.
03:16 Numbered lists can either be explicit using numbers or automatic using the number sign. Note that a single blank line doesn’t create a new list, so the mess I have on the left creates a single numbered list from one to four on the right.
A link is written using single backticks and an underscore suffix. If you want a name to be displayed instead of the link itself, you put the name inside the backticks and surround the link in angle brackets (
Double colons are meaningful, and you don’t want to confuse the two ideas. Also note that it needs to have a blank line following it. If you have a reference defined, you can link to it using
:ref: then backticks followed by the reference name without the leading underscore.
:ref: is optional If the link you’re referencing is in the same document. I’ve had some trouble making that work in certain situations before, so I’ve just developed the habit of always using the
05:06 A directive is a block of instructions. These get used everywhere for all sorts of structure and styling. A directive is comprised of the directive name and then possibly some arguments, some options, and some content: code blocks, notes, warnings, and more are all done with directives.
Underneath the directive statement, you may find zero or more options. Options are between matched colons. The
linenos option to
code-block says that when output, this block should include line numbers.
07:08 The path is either relative to the document file the directive is in, or it can be fully qualified. Images can be a little tricky. What formats they support and how sizes are treated are dependent on what the output supports. For HTML, you can use the same kind of image formats you’d use on the Web.
07:28 Some output formats, like LaTeX, support embedding PDFs. PDFs can be tricky when it comes to sizes, so the options specifying width and height here may or may not be effective depending on the output format.
This is probably the directive I use the most, the
code-block. I showed you it earlier to explain what a directive was, so not much new to see here. The argument that specifies the language is optional, as is the
linenos option. If it can, Sphinx will apply Pygments syntax highlighting for your block.
Don’t forget the blank line between the directive and your code. Oh, and because indentation indicates belonging to the block, that
for statement isn’t actually indented from Python’s perspective.
09:15 I mentioned earlier GitHub supports RST format for your README, and the README from a project is often the same as you’d have in your index page, so I often use this directive to suck the README into the index page.
This is my
index.rst file. I’ve made a couple of small changes from the skeleton file. First, I added a comment at the top telling you what file this is. Second, I added some version information.
The paired pipe symbols (
|) here are a variable replacement mechanism. Any value in your
conf.py can be accessed this way, so the
0.0.1 release number I chose during
quickstart will show up on this line. Before showing you the next change, let me first talk a bit about the table of contents.
You probably don’t want your sub- and sub-subsection headers in your table of contents. The
caption option indicates what text will show in the table of contents’ caption line. Mine is the default,
movie here means it expects there to be a file called
movie.rst in the same directory. Assuming it finds such a thing, it will process it and include its headers in the table of contents.
11:42 I’ve actually been a bad boy here and used what I normally use for section and subsection header markup, those underlines of equals and hyphens. As these are the only two headers in file, they’ll be treated as header level one and two, title and subtitle.
Off-screen, I ran
make html again to rebuild my document, and this is the result. There’s the version number and the two levels of table of contents, coming from my two levels of headers in the
12:54 Okay, you’ve seen the basics of RRST and building Sphinx docs. Next up, I’ll show you how to take advantage of your pydoc comments. You do write comments in your code, right? I think I said that already.
Become a Member to join the conversation.