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.
- A fresh Ubuntu 20.04 server on the Atlantic.Net Cloud Platform
- A root password configured on your server
Step 1 – Create Atlantic.Net Cloud Server
First, log in to your Atlantic.Net Cloud Server. Create a new server, choosing Ubuntu 20.04 as the operating system with at least 2GB RAM. Connect to your Cloud Server via SSH and log in using the credentials highlighted at the top of the page.
Once you are logged in to your Ubuntu 20.04 server, run the following command to update your base system with the latest available packages.
apt-get update -y
Step 2 – 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 3 – 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 4 – 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:
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 5 – 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.
Find the following lien:
And, replaced it with the following line:
Save and close the file, then restart the Apache service to apply the changes.
systemctl restart apache2
Step 6 – 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:
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.