Step 1: Getting started with RST¶
Now that we have our basic skeleton, let’s document the project. As you might have guessed from the name, we’ll be documenting a basic web crawler.
For this project, we’ll have the following pages:
- Index Page
- Command Line Options
Let’s go over the concepts we’ll cover, and then we can talk more about the pages to create.
A lot of these RST syntax examples are covered in the Sphinx reStructuredText Primer.
Title ===== Section ------- Subsection ~~~~~~~~~~
Every Sphinx document has multiple level of headings. Section headers are created by underlining the section title with a punctuation character, at least as long as the text.
They give structure to the document, which is used in navigation and in the display in all output formats.
You can use ``backticks`` for showing ``highlighted`` code.
If you want to make sure that text is shown in monospaced fonts for code examples or concepts,
use double backticks arond it.
like this on output.
Code Example Syntax¶
A cool bit of code:: Some cool Code .. code-block:: rst A bit of **rst** which should be *highlighted* properly.
The syntax for displaying code is
When it is used at the end of a sentence,
Sphinx is smart and displays one
: in the output,
and knows there is a code example in the following indented block.
uses meaningful whitespace.
Blocks of content are structured based on the indention level they are on.
You can see this concept with our
code-block directive later.
Table of Contents Tree¶
.. toctree:: :maxdepth: 2 install support
Now would be a good time to introduce the
One of the main concepts in Sphinx is that it allows multiple pages to be combined into a cohesive hierarchy.
toctree directive is a fundamental part of this structure.
The above example will output a Table of Contents in the page where it occurs.
maxdepth argument tells Sphinx to include 2 levels of headers in it’s output.
It will output the 2 top-level headers of the pages listed.
This also tells Sphinx that the other pages are sub-pages of the current page,
creating a “tree” structure of the pages:
index ├── install ├── support
The TOC Tree is also used for generating the navigation elements inside Sphinx. It is quite important, and one of the most powerful concepts in Sphinx.
Create Installation page¶
Installation documentation is really important. Anyone who is coming to the project will need to install it. For our example, we are installing a basic Python script, so it will be pretty easy.
Include the following in your
on the same level as
index.rst, properly marked up:
1 2 3 4 5 6 7 8 9
Installation At the command line: easy_install crawler Or, if you have pip installed: pip install crawler
Live Preview: Installation
You can now open the
support.html file directly,
but it isn’t showing on the navigation..
Create Support page¶
It’s always important that users can ask questions when they get stuck. There are many ways to handle this, but normal approaches are to have an IRC channel and mailing list.
Go ahead and put this in your
support.rst, but add the proper RST markup:
1 2 3 4 5 6 7 8 9 10 11 12
Support The easiest way to get help with the project is to join the #crawler channel on Freenode. We hang out there and you can get real-time help with your projects. The other good way is to open an issue on Github. The mailing list at https://groups.google.com/forum/#!forum/crawler is also available for support. Freenode: irc://freenode.net Github: http://github.com/example/crawler/issues
Live Preview: Support
Now you need to tie all these files together.
As we mentioned above,
the Table of Contents Tree is the best way to do this.
Go ahead and complete the
toctree directive in your
adding the new
Your filesystem should now look something like this:
crawler ├── src └── docs ├── index.rst ├── support.rst ├── install.rst ├── Makefile ├── conf.py
Now that you have a few pages of content, go ahead and build your docs again:
If you open up your
you should see the basic structure of your docs from the included
Have some extra time left? Check out these other cool things you can do with Sphinx.
Make a manpage¶
The beauty of Sphinx is that it can output in multiple formats, not just HTML. All of those formats share the same base format though, so you only have to change things in one place. So you can generate a manpage for your docs:
This will place a manpage in
You can then view it with:
Create a single page document¶
Some people prefer one large HTML document, instead of having to look through multiple pages. This is another area where Sphinx shines. You can write your documentation in multiple files to make editing and updating easier. Then if you want to distribute a single page HTML version:
This will combine all of your HTML pages into a single page. Check it out by opening it in your browser:
You’ll notice that it included the documents in the order that your TOC Tree was defined.
Play with RST¶
RST takes a bit of practice to wrap your head around. Go over to http://rst.ninjs.org, which is a live preview.
Use the Cheat Sheet for lots more ideas!
Looking for some ideas of what the syntax contains? The reStructuredText Primer in the Sphinx docs is a great place to start.