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 sphinxSample 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.
sphinx-quickstartSample 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 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.
- Run the command below to generate a static HTML file.
make htmlSample 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] ServerName sphinx.exampledomain.com 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.
http://127.0.0.1
- 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
