Install and Use Sphinx Documentation Generator on CentOS 7

Table of Contents

Introduction

Sphinx is a powerful, free, open source documentation generator. Although originally developed for use with Python code, Sphinx can be used to prepare and generate any type of documentation, including .rst files for use with services like ReadTheDocs. Sphinx includes an HTML generator which can create a simple, attractive HTML version of your documentation, including automatic organization and Table of Contents.

This article will cover installing Sphinx and the basics of Sphinx use and syntax.

Note: This article is in regards to the Sphinx documentation generator, not the open source search engine of the same name.

Requirements

  • A 1&1 Cloud Server running Linux (CentOS 7)
  • Optional: A web server installed and running (to view the generated documentation).

Install Sphinx

Update your system:

sudo yum update

The easiest way to install Sphinx is to use the Python installer Pip. Add the EPEL repository:

sudo yum install epel-release

Install Pip:

sudo yum install python-pip

Then use Pip to install Sphinx:

sudo pip install -U Sphinx

Use sudo sphinx-build --version to verify that Sphinx was installed correctly:

[user@localhost ~]$ sudo sphinx-build --version
Sphinx (sphinx-build) 1.5.2

Sphinx Quickstart

Sphinx includes a quickstart tool for beginners. This command automatically generates a basic file structure and configuration you will need to create documentation.

Before you run the quickstart command, switch to the user account that will be editing the Sphinx documents, for example:

su - jdoe

Do not use sudo for this command. If you use sudo, the files will be created with root ownership and you will not be able to edit them.

Run the quickstart command:

sphinx-quickstart

Answer the questions as appropriate for your project. Hit Enter to accept the default for a question. Be sure to answer "y" to the autodoc extension.

Sphinx uses a syntax called reStructuredText. The full documentation for reStructuredText can be found on the docutils SourceForge site. For now, we will stick with just the basics you need to create a simple test documentation project.

One important thing to know about reStructuredText is that it is "whitespace-sensitive." This means that it reads spaces as indents, and will organize your documents accordingly. Always use the correct number of spaces to indent each line in an .rst file.

Edit the Index File

The index.rst file is the cornerstone of your project. Open this file for editing:

sudo nano index.rst

The toctree block is what determines your main Table of Contents. You can read more about the toctree directive on the Sphinx site. The default toctree block will be:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

Let's add two files to the main Table of Contents, intro.rst and testfile.rst:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   intro.rst
   testfile.rst

Note that intro.rst and testfile.rst are at the same indent level (3 spaces) as the rest of the toctree block.

Save and exit the file.

Create the Documentation Files

In the previous section, we led Sphinx to expect the existence of two files, intro.rst and testfile.rst. We will create these files now.

intro.rst

Create the file intro.rst and open it for editing with the command:

nano intro.rst

Enter the following as the first three lines of the file:

======
Intro
======

The two lines of = signs tell Sphinx that this is a section header. These two lines must be the same length. In this case, both lines are six characters long. The specific number of characters doesn't matter, they just need to be the same number for each line.

Add a blank line, then enter:

Hello, world! This is the test introduction page.

The full file will read:

======
Intro
======

Hello world! This is the test introduction page.

Save and exit the file.

testfile.rst

Next, create the file testfile.rst and open it for editing with the command:

nano testfile.rst

Enter the following as the first three lines of text:

====================
Test Documentation
====================

As before, make sure that the first and third lines have the same number of characters.

Add a blank line, then enter:

This is a test documentation file. 

Next, we will add a sub-section. This will be indicated by using - characters for the first and third lines of the header.

Add another blank line, then enter:

-----------------------
Sub-Section 1
-----------------------

Add another blank line, then enter:

This is the first sub-section. 

The full file will read:


====================
Test Documentation
====================

This is a test documentation file.

-----------------------
Sub-Section 1
-----------------------

This is the first sub-section.

Save and exit the file.

Generate the HTML Version

Now that we have customized the index.rst file and added two documentation files, let's generate the HTML version for a website. First, create a directory to house the documentation:

sudo mkdir /var/www/html/testdocs

Change the ownership of this directory so that your Sphinx user can write to it. Replace jdoe with your username:

sudo chown jdoe:jdoe /var/www/html/testdocs

Use the sphinx-build command to generate the documentation:

sphinx-build -b html . /var/www/html/testdocs

If there are any errors in the build (like improperly indented lines, or mis-matching title lines), Sphinx will give you an error during this process.

For example, consider the following error:

/home/jdoe/testfile.rst:7: SEVERE: Title overline & underline mismatch.

-----------------------
Sub-Section 1
----------------------

This error tells you the file which has the error (testfile.rst), the line at which the error occurs (line 7), the type of error (title overline and underline mismatch), and even prints out the lines which are causing the problem. As you can see, there are a different number of - characters in the first line as compared to the third.

After correcting any errors, you will get the build succeeded. notice which means that your documentation is ready to view.

In a browser, go to the URL of the new documents folder. You will see your test documents:

Sphinx test docs

As you can see, Sphinx has automatically generated a Table of Contents, including the sub-section which we created in the testfile.rst file.

Content provided by 1&1

Comments

Tags: Sphinx