Understanding the Basics of Sphinx
00:10 Sphinx is a document generation tool. It supports multiple formats, including HTML, PDF, man pages, and more. Within a Sphinx document, you can make references to other parts of the document. In HTML output, these end up as links. When combined with the autodoc extension, this allows you to write text about code and link to extracted pydoc comments incorporated into your documents.
00:36 One of my favorite uses of this is to document my unit tests. Management often wants to know what is being tested, especially if they’re coming from the old school everything-has-a-test-case world. By including some pydoc in your tests, you can extract it all and produce a PDF highlighting the current test suite without having to maintain a separate testing doc. Sphinx uses the structure of your text to automatically create a table of contents and an index for your doc, and you can change the look and feel by specifying a theme. By default, Sphinx uses reStructuredText—that’s RST for short.
01:13 This is a text markup language. If you’re familiar with Markdown, it’s conceptually similar. This course doesn’t cover it, but there are also extensions that allow the use of MyST Markdown if you really want to use a Markdown flavor instead.
Sphinx is available as a PyPI package, and you install it using the usual
pip command. I believe this is the part in the script where I always recommend virtual environments for your projects. There, you’ve been recommended.
01:59 I’m at the regular old command line here. Throughout this course, I’m going to be documenting a mini-project named Serenity, so the first thing I need to do is create a directory for my project.
This asks me a series of questions to configure my doc structure. The first question is whether to use separate build and source directories. If you say yes, you will get a directory named
"build" and another named
If you say no, the default, you get a directory named
"_build", and your source files go in the same local folder. As the build files still end up in their own location, I don’t find the separation to be an advantage, so I go with the default here.
Sphinx supports multiple languages. This is the spot where you can change the language for your docs. I don’t know if they support Klingon, so I’ll be sticking with English. And with all that out of the way, it creates your skeleton files. That list of stuff there, starting with
Creating, shows the files it’s writing to your folder.
Notice the first block of variables are the answers to the questions asked in the
quickstart script. Because this is a Python script, you can do some fancy things that you couldn’t otherwise accomplish with a text format. Later, I’ll write some code to automatically update the copyright date.
This is the index file for your documentation. It’s the equivalent of a home page in HTML. As the name implies, it’s in RST format. In the next lesson, I’ll go over RST in detail. For now, just notice the equal signs (
=) as underlines indicating section titles.
05:09 If all you’re generating is a single-page document, you can start writing in here. Once I’ve covered RST, I’ll be adding some content in this document. All right, you’ve seen the files. Let’s go create some output.
And there you go. All that output says is it got made. If there was a problem with your files, it would show up in this output. Let’s peek inside the
_build/ directory now that I’ve built something.
Not much to see here since my
index.rst file was almost empty, but you can see the title, the list of indices, and an area on the left-hand side where you’ll get some more information when your document becomes more complicated.
Become a Member to join the conversation.