Install Sphinx-Doc on Oracle Linux

This guide will go through how to install Sphinx-Doc on Oracle Linux. Sphinx is a documentation generator that makes it simple to create insightful and eye-catching documentation. It has numerous features that are beneficial for creating technical documentation, such as output formats, comprehensive cross-references, a hierarchical structure, automatic indexing, code handling, extensions, and themes.

How to Install Sphinx-Doc on Oracle Linux

  • Update Oracle Linux packages.
sudo dnf update
  • Next, install dependencies.
sudo dnf install python3 python3-pip make gcc httpd -y
  • Then start Apache using the command below.
sudo service httpd start
  • Enable Apache using the following command.
sudo systemctl enable httpd
  • Install Sphinx-Doc.
pip3 install sphinx

Sample output

Collecting sphinx
  Downloading sphinx-5.3.0-py3-none-any.whl (3.2 MB)
     |████████████████████████████████| 3.2 MB 33 kB/s 
Collecting sphinxcontrib-qthelp
  Downloading sphinxcontrib_qthelp-1.0.3-py2.py3-none-any.whl (90 kB)
     |████████████████████████████████| 90 kB 95 kB/s 
Collecting sphinxcontrib-serializinghtml>=1.1.5
  Downloading sphinxcontrib_serializinghtml-1.1.5-py2.py3-none-any.whl (94 kB)
     |████████████████████████████████| 94 kB 89 kB/s 
Collecting Pygments>=2.12
  Downloading Pygments-2.13.0-py3-none-any.whl (1.1 MB)
     |████████████████████████████████| 1.1 MB 25 kB/s 
Collecting alabaster=0.7
  Downloading alabaster-0.7.12-py2.py3-none-any.whl (14 kB)
Collecting sphinxcontrib-devhelp
  Downloading sphinxcontrib_devhelp-1.0.2-py2.py3-none-any.whl (84 kB)
     |████████████████████████████████| 84 kB 87 kB/s 
Collecting sphinxcontrib-htmlhelp>=2.0.0
  Downloading sphinxcontrib_htmlhelp-2.0.0-py2.py3-none-any.whl (100 kB)
     |████████████████████████████████| 100 kB 180 kB/s 
Collecting imagesize>=1.3
  Downloading imagesize-1.4.1-py2.py3-none-any.whl (8.8 kB)
Collecting Jinja2>=3.0
  Downloading Jinja2-3.1.2-py3-none-any.whl (133 kB)
     |████████████████████████████████| 133 kB 244 kB/s 
Collecting importlib-metadata>=4.8
  Downloading importlib_metadata-5.0.0-py3-none-any.whl (21 kB)
Requirement already satisfied: requests>=2.5.0 in /usr/lib/python3.9/site-packages (from sphinx) (2.25.1)
Collecting docutils=0.14
  Downloading docutils-0.19-py3-none-any.whl (570 kB)
     |████████████████████████████████| 570 kB 30 kB/s 
Collecting sphinxcontrib-jsmath
  Downloading sphinxcontrib_jsmath-1.0.1-py2.py3-none-any.whl (5.1 kB)
Collecting sphinxcontrib-applehelp
  Downloading sphinxcontrib_applehelp-1.0.2-py2.py3-none-any.whl (121 kB)
     |████████████████████████████████| 121 kB 24 kB/s 
Collecting packaging>=21.0
  Downloading packaging-21.3-py3-none-any.whl (40 kB)
     |████████████████████████████████| 40 kB 63 kB/s 
Collecting babel>=2.9
  Downloading Babel-2.10.3-py3-none-any.whl (9.5 MB)
     |████████████████████████████████| 9.5 MB 371 kB/s 
Collecting snowballstemmer>=2.0
  Downloading snowballstemmer-2.2.0-py2.py3-none-any.whl (93 kB)
     |████████████████████████████████| 93 kB 696 kB/s 
Collecting pytz>=2015.7
  Downloading pytz-2022.5-py2.py3-none-any.whl (500 kB)
     |████████████████████████████████| 500 kB 704 kB/s 
Collecting zipp>=0.5
  Downloading zipp-3.9.0-py3-none-any.whl (5.8 kB)
Collecting MarkupSafe>=2.0
  Downloading MarkupSafe-2.1.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (25 kB)
Requirement already satisfied: pyparsing!=3.0.5,>=2.0.2 in /usr/lib/python3.9/site-packages (from packaging>=21.0->sphinx) (2.4.7)
Requirement already satisfied: idna=2.5 in /usr/lib/python3.9/site-packages (from requests>=2.5.0->sphinx) (2.10)
Requirement already satisfied: urllib3=1.21.1 in /usr/lib/python3.9/site-packages (from requests>=2.5.0->sphinx) (1.26.5)
Requirement already satisfied: chardet=3.0.2 in /usr/lib/python3.9/site-packages (from requests>=2.5.0->sphinx) (4.0.0)
Installing collected packages: zipp, pytz, MarkupSafe, sphinxcontrib-serializinghtml, sphinxcontrib-qthelp, sphinxcontrib-jsmath, sphinxcontrib-htmlhelp, sphinxcontrib-devhelp, sphinxcontrib-applehelp, snowballstemmer, Pygments, packaging, Jinja2, importlib-metadata, imagesize, docutils, babel, alabaster, sphinx
  WARNING: Value for scheme.platlib does not match. Please report this to 
  distutils: /home/itnixpro/.local/lib/python3.9/site-packages
  sysconfig: /home/itnixpro/.local/lib64/python3.9/site-packages
  WARNING: Additional context:
  user = True
  home = None
  root = None
  prefix = None
Successfully installed Jinja2-3.1.2 MarkupSafe-2.1.1 Pygments-2.13.0 alabaster-0.7.12 babel-2.10.3 docutils-0.19 imagesize-1.4.1 importlib-metadata-5.0.0 packaging-21.3 pytz-2022.5 snowballstemmer-2.2.0 sphinx-5.3.0 sphinxcontrib-applehelp-1.0.2 sphinxcontrib-devhelp-1.0.2 sphinxcontrib-htmlhelp-2.0.0 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-1.0.3 sphinxcontrib-serializinghtml-1.1.5 zipp-3.9.0

Configure Sphinx-Doc on Debian Linux

  • Navigate to the Apache document root directory using the command below.
cd /var/www/html/
  • Start Sphinx-Doc using the command below.

Sample output

Welcome to the Sphinx 5.3.0 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: itnixpro
> Author name(s): nix
> Project release []: 9.0

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
> Project language [en]: 

Creating file /var/www/html/
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.
  • Run the command below to generate a static HTML file.
make html

Sample output

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

Configure Apache

  • Create Apache virtual host for Sphinx-Doc using the following command.
sudo nano /etc/httpd/conf.d/sphinx.conf
  • Then add the config below.
        ServerAdmin [email protected]
        DocumentRoot /var/www/html/_build/html/
        ErrorLog /var/log/httpd/error.log
        CustomLog /var/log/httpd/access.log combined

  • Next, change /var/www/html/ directory ownership.
sudo chown -R apache:apache /var/www/html/
  • Restart Apache to apply changes.
sudo systemctl restart httpd
  • Fire up your browser and enter your computer IP address or domain name to access Sphinx-Doc e.g.
Install Sphinx-Doc on Oracle Linux
Install Sphinx-Doc on Oracle Linux
  • That marks the end of our tutorial, we have gone through how to Install Sphinx-Doc on Oracle Linux.

Read more on Sphinx-Doc Documentation

Other Tutorials

Install Cockpit on Ubuntu 22.04/20.04

Install OpenSCAP on OpenSUSE

Install PostgreSQL on FreeBSD 13

System administrator | Software Developer | DevOps

Leave a Comment