Understanding the Basics of Sphinx

00:00 In the previous lesson, I gave an overview of the course. In this lesson, I’ll be covering the basics of Sphinx, what you need to know to build your first document.

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.

01:29 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:43 Once you’ve got the package installed, you’ll find the sphinx-quickstart command available on your path. This command creates the structure needed for your documentation directory.

01:55 Let’s go see how this works in practice.

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.

02:15 Now I’ll create a directory for our docs.

02:21 And inside the docs/ directory, I run the sphinx-quickstart command.

02:28 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 "source".

02:42 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.

02:57 The next question is what to call the project. This name shows up in the documentation a bunch of times. It’s case sensitive, so capitalize it the way you want the name to show up in the docs.

03:10 Next is who to blame, and that would be me. And then the version number. To be clear, I’ve gone with something indicating very premature, 0.0.1.

03:24 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.

03:44 Let’s take a look inside. You get a Makefile, some directories for building stuff, a make.bat file in case you’re on Windows, a configuration Python script, and an index page in the RST format.

03:59 Let’s start by taking a look at the configuration script.

04:05 This is conf.py, the configuration script for the documentation folder that I just generated. Sphinx imports this and uses the variables when it builds things.

04:15 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.

04:32 For now, let’s move on to index.rst.

04:40 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.

04:58 The chunk at the top indicated by the double dots (..) is a comment. There are also directives in here for inserting a table of contents and links to the automatically generated indexes.

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.

05:25 Back in my shell, in my documents/ folder. Remember that quickstart script generated a Makefile for you. If you’re on a Unix-based system, you run the make command.

05:34 If you’re on Windows, you’ll be using the batch file instead. make on its own spits out some help. You need to provide a target indicating what you want made.

05:46 You can see from this list that there are a bunch of different output formats. I mostly just use HTML personally. Scrolling down … and let’s build an HTML doc.

05:58 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.

06:14 And now inside the _build/html/ directory …

06:20 All those files were created as part of the build process. It’s more than just a single file because of things like the ability to search and the indices.

06:30 Let me go open up a browser, and I’ll show you what this looks like.

06:36 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.

06:52 This will all become more interesting in the next lesson when I show you how to add some content. Next up, I show you how to add some more content. Get ready to get your markup on.