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.
A CentOS 7 x64 instance.
A sudo user.
sudo yum update sudo shutdown -r now
sudo yum install -y python-devel python-setuptools python-pip sudo pip install --upgrade pip sudo pip install -U Sphinx
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
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
Open it with a text editor:
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:: :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
Place your source files in their respective order.
Use only one file name per row.
Indent your file names with
Once you have completed your modifications, save your file and exit the text editor.
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.
Once you have finished composing your documentation, you can output your work in
HTML format by executing the below command:
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.