How to Install Sphinx-Doc on Ubuntu 20.04

Sphinx is a powerful documentation generator tool that allows you to create intelligent and beautiful documentation. It is written in python and based on the jinja template. Sphinx has many features that make it easier to generate web pages, printable PDFs, and ePub documents.

In this post, we will show you how to install Sphinx-Doc on Ubuntu 20.04.

Step 1 – Install Required Dependencies

Sphinx-Doc is written in Python, so you will need to install Python modules and Apache server to your system. You can install all of them with the following command:

apt-get install python3-pip python3-dev python3-setuptools apache2 -y

Once all the packages are installed, update pip to the latest version with the following command:

pip3 install --upgrade pip

Step 2 – Install Sphinx-Doc

Next, you can install the Sphinx-Doc using the pip command as shown below:

pip3 install sphinx

Once the installation has been finished, you should get the following output:

Installing collected packages: MarkupSafe, Jinja2, sphinxcontrib-jsmath, Pygments, sphinxcontrib-devhelp, docutils, imagesize, snowballstemmer, alabaster, sphinxcontrib-serializinghtml, sphinxcontrib-htmlhelp, pytz, babel, sphinxcontrib-applehelp, pyparsing, packaging, sphinxcontrib-qthelp, sphinx
Successfully installed Jinja2-2.11.3 MarkupSafe-1.1.1 Pygments-2.8.1 alabaster-0.7.12 babel-2.9.0 docutils-0.16 imagesize-1.2.0 packaging-20.9 pyparsing-2.4.7 pytz-2021.1 snowballstemmer-2.1.0 sphinx-3.5.3 sphinxcontrib-applehelp-1.0.2 sphinxcontrib-devhelp-1.0.2 sphinxcontrib-htmlhelp-1.0.3 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-1.0.3 sphinxcontrib-serializinghtml-1.1.4

Step 3 – Configure Sphinx-Doc

Next, change the directory to Apache document root and run the Sphinx-Doc setup script.

cd /var/www/html/
sphinx-quickstart

You will be asked to provide your project name, author name, and project release as shown below:

Welcome to the Sphinx 3.5.3 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: n

The project name will occur in several places in the built documentation.
> Project name: myapp
> Author name(s): admin
> Project release []: 20.04

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: 

Creating file /var/www/html/conf.py.
Creating file /var/www/html/index.rst.
Creating file /var/www/html/Makefile.
Creating file /var/www/html/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /var/www/html/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

Next, run the following command to generate a static HTML file:

make html

You should get the following output:

Running Sphinx v3.5.3
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                                                
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                 
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

The above command will generate an HTML file at /var/www/html/_build/html/index.html.

Step 4 – Configure Apache for Sphinx-Doc

Next, you will need to edit the Apache default virtual host configuration file and define the path of your HTML file.

nano /etc/apache2/sites-available/000-default.conf

Find the following lien:

DocumentRoot /var/www/html/

And, replaced it with the following line:

DocumentRoot /var/www/html/_build/html/

Save and close the file, then restart the Apache service to apply the changes.

systemctl restart apache2

Step 5 – Access Sphinx-Doc

Now, open your web browser and access the Sphinx-Doc using the URL http://your-server-ip. You should see the following page:

Conclusion

Congratulations! You have successfully installed Sphinx-Doc on Ubuntu 20.04 server. You can now use Sphinx-Doc for any documentation project, including one on your dedicated server from Atlantic.Net.