Use Sphinx To Create Documentation In Multiple Formats On CentOS 7

Sphinx is a useful Python-based tool for technicians and writers that allows them to easily create elegant, fully-functional documentation in various formats. With Sphinx, you write documents using reStructuredText — a lightweight markup language — for starters, then you can get the output in multiple formats, including HTML, LaTeX, PDF, ePub, and others.

In this tutorial, we will be covering the process of installing and using Sphinx on a CentOS 7 x64 instance on Vult’s platform.

Prerequisites

• A CentOS 7 x64 instance.
• A sudo user.

Step 1: Update the system

sudo yum update
sudo shutdown -r now

Step 2: Install pip and Sphinx

sudo yum install -y python-devel python-setuptools python-pip
sudo pip install --upgrade pip
sudo pip install -U Sphinx

Step 3: Setup the basic configuration for your documentation

Before starting to use Sphinx, you need to specify your source directory in which Sphinx will run and save all your documentation. Once you have created the directory you intend to use, you can then run sphinx-quickstart which will initialize Sphinx and create the required basic configuration.

sphinx-quickstart is similar to a setup wizard which will prompt you with questions that determine the aspects of your project.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Step 4: Construct the hierarchy for your documentation

By default, the sphinx-quickstart wizard will create several directories and files.

_build           # The directory for containing Sphinx output
conf.py          # The file containing your project configurations
index.rst        # The master file containing the hierarchy of your documentation
make.bat         # A Windows command file
Makefile         # A file necessary for running the make command
_static          # The directory for static files, including custom stylesheets, pictures, etc.
_templates       # The directory for custom templates

Let’s have a look at the master file, index.rst, which contains the hierarchy of your documentation; namely, the table of contents tree or toctree.

Open it with a text editor:

vi index.rst

As you review the file, you will notice a section called toctree. If you have other source files (*.rst) for your documentation, you will need to specify them in the toctree section:
.. toctree::
:maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

It is imperative to:

• Leave a blank row above your input.
• Do not suffix your source files with .rst.
• Place your source files in their respective order.
• Use only one file name per row.
• Indent your file names with :maxdepth: 2.

Once you have completed your modifications, save your file and exit the text editor.

ESC
:!wq

Step 5: Create source files specified above

The source files must be created with names that match what was previously specified in index.rst, otherwise they will not be included in the final output.

All of the source files must be compatible with the reStructuredText markup language. For more information, please refer to reStructuredText Primer.

Step 6: Output the HTML version of your documentation

Once you have finished composing your documentation, you can output your work in HTML format by executing the below command:

make html

The output will be saved in the directory .//_build/html which includes everything necessary for viewing the file in a web browsing.

This concludes our tutorial.