How to Install Sphinx-Doc on Oracle Linux 8

Sphinx is a powerful documentation generator that makes it easy to create intelligent and beautiful documentation. It is written in Python and supports several Output formats such as PDF, plain text, EPUB, TeX, manual pages, and more. Sphinx uses the reStructuredText markup language by default and can read MyST markdown via third-party extensions. It supports many languages, including Python, C, C++, JavaScript, mathematics, and many more.

In this post, we will show you how to install Sphinx-Doc on Oracle Linux 8.

Step 1 – Install Python

First, you will need to install Python and other required dependencies on your server. You can install all of them by running the following command:

dnf install python39 httpd make gcc -y

Once all the packages are installed, verify the Python version with the following command:

python3.9 --version

You will get the following output:

Python 3.9.7

Next, install the PIP package with the following command:

dnf install python39-pip -y

Next, verify the PIP version using the following command:

pip3 --version

You will get the following output:

pip 20.2.4 from /usr/lib/python3.9/site-packages/pip (python 3.9)

Step 2 – Install Sphinx-Doc on Oracle Linux 8

You can now use the PIP command line utility to install Sphinx-Doc:

pip3 install sphinx

Once the installation has been completed, navigate to the Apache web root directory and configure Sphinx with the following command:

cd /var/www/html/
sphinx-quickstart

Answer all the questions as shown below to configure Sphinx-Doc:

Welcome to the Sphinx 5.1.1 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): hitesh jethva
> Project release []: 8.05

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, build all configuration files using the following command:

make html

You will get the following output:

Running Sphinx v5.1.1
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.

Step 3 – Create an Apache Virtual Host for Sphinx-Doc

Next, you will need to create an Apache virtual host configuration file to host Sphinx-Doc on the web.

nano /etc/httpd/conf.d/sphinx.conf

Add the following configurations:

<VirtualHost *:80>
        ServerAdmin [email protected]
        ServerName sphinx.exampledomain.com
        DocumentRoot /var/www/html/_build/html/
        ErrorLog /var/log/httpd/error.log
        CustomLog /var/log/httpd/access.log combined
</VirtualHost>

Save and close the file, then change the ownership of the Apache web root directory:

chown -R apache:apache /var/www/html/

Next, start and enable the Apache service with the following command:

systemctl start httpd
systemctl enable httpd

Next, verify the status of Apache with the following command:

systemctl status httpd

You will get the following output:

● httpd.service - The Apache HTTP Server
   Loaded: loaded (/usr/lib/systemd/system/httpd.service; disabled; vendor preset: disabled)
   Active: active (running) since Thu 2022-09-01 02:03:13 EDT; 7s ago
     Docs: man:httpd.service(8)
 Main PID: 2748 (httpd)
   Status: "Started, listening on: port 80"
    Tasks: 213 (limit: 11409)
   Memory: 25.0M
   CGroup: /system.slice/httpd.service
           ├─2748 /usr/sbin/httpd -DFOREGROUND
           ├─2750 /usr/sbin/httpd -DFOREGROUND
           ├─2751 /usr/sbin/httpd -DFOREGROUND
           ├─2752 /usr/sbin/httpd -DFOREGROUND
           └─2753 /usr/sbin/httpd -DFOREGROUND

Sep 01 02:03:12 oraclelinux8 systemd[1]: Starting The Apache HTTP Server...

Step 4 – Access Sphinx-Doc Web Interface

You can now access the Sphinx-Doc web interface using the URL http://sphinx.exampledomain.com. You should see Sphinx-Doc on the following screen:

Conclusion

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