Setting Up a Sphinx Example Project and Scaffolding

Documenting Python Projects With Sphinx and Read The Docs - Archived Mahdi Yusuf 04:28

This lesson covers setting up an example project in order to demonstrate how to create scaffolding for documentation. You will learn how to install Sphinx and how to configure it using its Quick Start Wizard. The Wizard allows you to set common options quickly such as author details, file format for the documentation files, and whether or not to create make files for each project.

Towards the end of the lesson, you’ll see how to build HTML documentation for your project using the make html command.

00:00 I’ve gone ahead and created a GitHub repository called doctut. This will serve as a scaffolding for our project. Mainly, it contains a LICENSE file, a README file, and a doctut/ code directory. That is empty right now and will likely be empty forever.

00:13 This is just a scaffolding just so you can understand where your code would be and where the documentation would be. The documentation should be encapsulated in its own folder, so we’re going to go ahead and create a docs/ directory now.

00:25 So, once we’ve created that docs/ directory, that’s where you’ll contain all your documentation. You want to group this together so outsiders can clearly understand “This is where all my documentation is stored.” It makes it easy for them to go in after the fact and update or add changes to your documentation. Next, we’re going to install Sphinx, so we’re just going to quickly activate the screencasts virtual env and we’re going to go pip install sphinx.

00:50 It looks like we’ve already installed it, but the install step is very straightforward. The next thing we want to do, we’re going to enter our docs/ directory, and we’re going to simply call sphinx-quickstart.

01:01 Now, this is a quick start guide wizard, basically a command-line wizard, that’ll guide you through on creating your documentation, your conf.py, and it’ll even generate a Makefile that allows you to easily generate local copies of your documentation quickly as you’re writing the documentation.

01:17 So, it’s going to ask us for the root path of the documentation. We want it in our docs/ directory. Since we just cd‘d in there, we’re just going to press Enter. Anything that’s contained in the squiggly brackets here will reflect the default value for that particular question.

01:30 I like to have my source/ and build/ directories separate so I can tell what was used in the build state and what’s actually the source.

01:36 So we’re going to say yes to this question.

01:39 I would like to have _templates/ and _static/ directories. This allows us to customize our Sphinx documentation with different themes and whatnot, but Read the Docs recently launched a new theme, which is quite awesome, so those of you who wish to use their own one can do this.

01:54 So I’m going to press no, in this particular one. We’re going to name the project, we’re going to call it doctut. The author is Mahdi Yusuf.

02:06 The project version is 0.0.1. That is the release. This is asking us whether we want our documentation files to be .txt files or .rst files. I recommend .rst, it allows you to have a bit more control of the source, although if you’re just writing text, .txt seems to be just as fine.

02:28 This is asking us what we’d like to name our very root folder. So when we build out documentation, it’s going to build everything against a main file. That main file is what you’re going to look at when you load your documentation. This is by standard called the index.rst, so we’re just going to press Enter again. No, we do not like an EPUB output, so we’re just going to press no here. Yes, I would like to use that. And then the rest of these, I’m just going to quickly click through no. This is just good defaults that Sphinx provides.

02:59 So if you just mainly just press Enter all the way through here, you could easily just get through and generate all the stuff you’d like. We would like a Makefile, yes. Yes, we’d like to create a BAT file for Windows users.

03:11 And we are done. So as you can see,

03:15 that whole process generated a conf.py, an index.rst, a Makefile, and a make.bat file for Windows users.

03:22 So if we’re just to ls and then go into our source/ directory, you’ll see that we have a conf.py. So if we’re to simply just go vim conf.py, you’ll see all the stuff we went and put in.

03:32 So we wanted that Autodoc extension, we wanted our templates_path to be the same as the defaults, our suffix for RST is that. And that’s what we just did—we generated this entire file plus a couple of Makefiles for quickly and easily generating documentation.

03:47 So, we’re going to step back out of here real fast and we’re going to go back up and we’re going to go make html.

03:56 What this should do is build our documentation. So as you can see, if we were to go to our build/html/ directory, you’ll see that we do have an index.html, which should correspond to the text that’s contained in our index.rst.

04:11 So we’re going to quickly just open this real fast, and as you can see, Welcome to doctut’s documentation! And then we have our indexes and our tables.

04:19 So now we have a scaffolding to start adding and injecting sections into our documentation, which we’ll cover next.

Anonymous on March 29, 2019

Any tutorial for doing the Sphinx Documentation for windows users?

Anonymous on March 29, 2019

I use windows system with pycharm as my editor. I’m git bash on pycharm as my terminal. I was able to execute all the commands till “make html”. “make html” gives me the following error: bash: make: command not found. Any help resolving this will be highly appreciated.

john09 on July 28, 2019

I’m using a Mac and PyCharm. I install sphinx and run sphinx-quickstart. The prompts I see are almost completely different. So, on lesson 2, I’m lost.

mthomp89 on May 12, 2020

On Windows 10. Prompts and output are very different. Is there work on a Windows tutorial?

Dan Bader RP Team on May 12, 2020

This course currently requires a Linux (or macOS) command-line environment for running the Sphinx make commands . We’re planning to update this course for Python 3 and Windows in the future.

Alexia on Sept. 2, 2021

Hi and thank you for this course :)

How can I add multiple authors using sphinx-quickstart?

Bartosz Zaczyński RP Team on Sept. 3, 2021

@Alexia It looks like sphinx-quickstart lets you type as many authors as you like, and they will appear on a single line in a <div> element in HTML.

Here’s the prompt I got when running the script:

$ sphinx-quickstart 
Welcome to the Sphinx 4.1.2 quickstart utility.

(...)

> Author name(s): Joe Doe, John Smith, Anna Brown

(...)

As you can see, I just typed multiple authors separated by a comma.

Alexia on Sept. 3, 2021

Thank you! :)

Become a Member to join the conversation.