This article is part of a series documenting the process of creating manuals using reStructuredText and Sphinx. See the whole list of articles.
Once you’ve done your planning and have your directory structure figured out, the next step is to start creating your project. You’ll need to create your base directory, use the sphinx-quickstart script to set up your basic project structure and configuration, and then – if needed – add some extra structure.
Create your base directory
You’ll need a base directory. You can name this whatever you want – for example docs, manuals, written-content. Set up your local code repository in this base directory.
Sphinx has a neat little bit of functionality that does all the initial setup work for you.
- Open a command prompt.
In Windows, press the Windows key and R (-R), enter
cmdand press Enter to open a command prompt window.
- Navigate to the base directory that you created.
The sphinx-quickstart script will start asking you questions about your project. I’ve listed the questions, with recommended answers (where appropriate):
Separate source and build directories (y/n) [n]:
I recommend separating the source and build directories because generally these will each belong to different phases of a project’s life cycle.
Name prefix for templates and static dir [_]:
Unless you have a pressing reason to avoid using an underscore to denote standard subdirectories, just use the default. This will give you _templates and _static directories.
<Your product's name>
The script adds this value to conf.py in the source directory. If you’ll only be creating a single user guide/knowledge base, you can enter the name that you want for your end document, for example
MySoftware Knowledge Base. If you’re going to be producing multiple documents, then what you enter here doesn’t really matter; you’ll be manually changing conf.py for each document anyway.
The script adds this value to conf.py in the source directory. What you enter here depends on your company documentation policy. Options might be the name of your company, your name, or the name of your team.
Project release :
<documentation release number>
The script adds this value to conf.py in the source directory. Generally you’ll be changing this every time you release documentation to your users. Often
0.0.1 is a good start.
Project language [en]:
If you’ll be writing documentation in English, then all you need to do is press Enter. Otherwise, check this list of language codes and enter the two-letter code that matches the language you’ll be using.
Source file suffix [.rst]:
The script adds this value to conf.py in the source directory. This is the file extension that Sphinx will use to identify RST documents. In theory, you can use any file extension that you want when creating your documents. In practice, unless you have pressing need to do otherwise, I recommend sticking with the default.
Name of your master document (without suffix) [index]:
The script adds this value to conf.py in the source directory. It’s the name of the file (without file extension – that comes from your answer to the previous question) that Sphinx will use as the backbone of your document. You could use the name of your user guide, especially if you’ll have multiple guides, but be aware that you’ll typically need a separate directory and conf.py file for each.
Do you want to use the epub builder (y/n) [n]:
If you want to build EPUB files – primarily used on ebook devices like Kobo’s Forma – then enter
y. Note: Kindle e-ink devices generally won’t display EPUBs; you’ll need MOBI files instead.
If you enter
y, EPUB build options will be added to the conf.py file in the base directory.
The sphinx-quickstart script will go through a list of standard extensions that you might want to enable. Many of these are the legacy of Sphinx’s origin as a Python code documentation tool; I’ve added an asterisk next to extensions that you’ll want to enable if you want to automatically include docstrings in your documentation. This could be useful for developer-level documentation and API docs.
The sphinx-quickstart script will add options you enter here to the conf.py file in the base directory.
*autodoc: automatically insert docstrings from modules (y/n) [n]:
Autodoc takes docstrings from Python code. If you’re not creating documentation from code comments, you won’t need this extension enabled. If you are, though, there’s a good walkthrough here: Getting Started with Sphinx / Autodoc.
*doctest: automatically test code snippets in doctest blocks (y/n) [n]:
The doctest extension checks the code snippets included in your docstrings. Again, if you’re not creating documentation from code comments, you won’t need this. If you are, check out this article: How to include test in your Python docstrings using doctest.
*intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
You’ll only need the intersphinx extension if you’re creating documentation from code comments AND want to easily link to existing code documentation. See: Link to other projects’ documentation.
todo: write “todo” entries that can be shown or hidden on build (y/n) [n]:
The todo extension lets you add behind-the-scenes notes on documentation; if you use this and don’t want your users seeing it, ensure that you include
todo_include_todos = False in your conf.py file.
*coverage: checks for documentation coverage (y/n) [n]:
Use the coverage extension if you want to check that your Python code is fully documented. If you’re not creating documentation from code comments, you don’t need this extension.
imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
If you’re including complex mathematical equations in your documentation AND want Sphinx to render it into images automatically, enable this extension (
mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
If you’re including complex mathematical equations in your documentation AND want Sphinx to include it in HTML pages in MathJax format, enable this extension (
*ifconfig: conditional inclusion of content based on config values (y/n) [n]:
I’m not a fan of this extension; I prefer to include or exclude documents and text using only statements and build parameters. It could be useful for some situations, though – see ifconfig documentation.
*viewcode: include links to the source code of documented Python objects (y/n) [n]:
Sphinx will automatically link back to the code that it’s retrieved docstrings from. If you’re not creating documentation from code comments, you won’t need this extension.
*githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
By default, GitHub ignores directories with names beginning with an underscore. Sphinx uses directories like _templates by default. You’ll generally want these directories included in your GitHub commits.
If you’re using GitHub, enter
y so that Sphinx includes a .nojekyll file in the project.
The sphinx-quickstart script will ask if you want to include some easy-build options. These are handy in the early stages of a project, and if you have a very simple project that won’t need parameters specified in the build command.
Create Makefile? (y/n) [y]:
Create Windows command file? (y/n) [y]:
The sphinx-quickstart script should have created the following directories and files for you:
source/index.rst(assuming you chose the default master document and file suffix options)
If you’ll be creating multiple guides from your source files, I recommend that you complete the following steps now:
- Create a
_childrensubdirectory in the
sourcedirectory. This is where you’ll save the vast majority of your documents.
- Create an
_mediasubdirectory in the
- Create a subdirectory in the
sourcedirectory for each guide you’ll be producing.
conf.pyfrom the source directory to the guide subdirectories.
- Change the name of each
index.rstfile to reflect which guide it is used for.
- Modify each conf.py file’s
master_docentry to its corresponding new guide filename.
I’ve created a sample RST/Sphinx project on GitHub, with branches that align to every tutorial article.
To see what your project should look like after running the sphinx-quickstart script, have a look at https://github.com/Nomesque/RST-Tutorial/tree/sphinx-quickstart.