Install Sphinx-Doc on OpenSUSE Linux

This guide will go through how to install Sphinx-Doc on OpenSUSE Linux. Sphinx is a documentation generator that makes it simple to create insightful and eye-catching documentation. It offers many features that are helpful for producing technical documentation, including output formats, thorough cross-references, a hierarchical structure, automatic indexing, code handling, extensions, and themes.

How to Install Sphinx-Doc on OpenSUSE Linux

  • Update OpenSUSE Linux packages using the command below.
sudo zypper update
  • Install dependencies for Sphinx-Doc.
sudo zypper install python3 python3-pip python3-virtualenv make gcc apache2 apache2-mod_wsgi 
  • Next, start the Apache server using the following command.
sudo systemctl start apache2
  • Then enable it to start on system boot.
sudo systemctl enable apache2
  • Install Sphinx-Doc on OpenSUSE using the command below.
pip3 install sphinx

Sample output

Defaulting to user installation because normal site-packages is not writeable
Collecting sphinx
  Downloading sphinx-5.3.0-py3-none-any.whl (3.2 MB)
     |████████████████████████████████| 3.2 MB 254 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 264 kB/s 
Collecting sphinxcontrib-devhelp
  Downloading sphinxcontrib_devhelp-1.0.2-py2.py3-none-any.whl (84 kB)
     |████████████████████████████████| 84 kB 289 kB/s 
Collecting babel>=2.9
  Downloading Babel-2.10.3-py3-none-any.whl (9.5 MB)
     |████████████████████████████████| 9.5 MB 418 kB/s 
Collecting alabaster=0.7
  Downloading alabaster-0.7.12-py2.py3-none-any.whl (14 kB)
Collecting imagesize>=1.3
  Downloading imagesize-1.4.1-py2.py3-none-any.whl (8.8 kB)
Collecting Pygments>=2.12
  Downloading Pygments-2.13.0-py3-none-any.whl (1.1 MB)
     |████████████████████████████████| 1.1 MB 187 kB/s 
Collecting docutils=0.14
  Downloading docutils-0.18.1-py2.py3-none-any.whl (570 kB)
     |████████████████████████████████| 570 kB 386 kB/s 
Collecting importlib-metadata>=4.8; python_version =1.1.5
  Downloading sphinxcontrib_serializinghtml-1.1.5-py2.py3-none-any.whl (94 kB)
     |████████████████████████████████| 94 kB 289 kB/s 
Collecting sphinxcontrib-htmlhelp>=2.0.0
  Downloading sphinxcontrib_htmlhelp-2.0.0-py2.py3-none-any.whl (100 kB)
     |████████████████████████████████| 100 kB 390 kB/s 
Requirement already satisfied: requests>=2.5.0 in /usr/lib/python3.6/site-packages (from sphinx) (2.24.0)
Collecting Jinja2>=3.0
  Downloading Jinja2-3.0.3-py3-none-any.whl (133 kB)
     |████████████████████████████████| 133 kB 277 kB/s 
Collecting snowballstemmer>=2.0
  Downloading snowballstemmer-2.2.0-py2.py3-none-any.whl (93 kB)
     |████████████████████████████████| 93 kB 392 kB/s 
Collecting sphinxcontrib-qthelp
  Downloading sphinxcontrib_qthelp-1.0.3-py2.py3-none-any.whl (90 kB)
     |████████████████████████████████| 90 kB 494 kB/s 
Collecting packaging>=21.0
  Downloading packaging-21.3-py3-none-any.whl (40 kB)
     |████████████████████████████████| 40 kB 377 kB/s 
Collecting pytz>=2015.7
  Downloading pytz-2022.5-py2.py3-none-any.whl (500 kB)
     |████████████████████████████████| 500 kB 293 kB/s 
Collecting typing-extensions>=3.6.4; python_version =0.5
  Downloading zipp-3.6.0-py3-none-any.whl (5.3 kB)
Requirement already satisfied: chardet>=3.0.2 in /usr/lib/python3.6/site-packages (from requests>=2.5.0->sphinx) (3.0.4)
Requirement already satisfied: idna>=2.5 in /usr/lib/python3.6/site-packages (from requests>=2.5.0->sphinx) (2.6)
Requirement already satisfied: urllib3!=1.25.0,!=1.25.1,=1.21.1 in /usr/lib/python3.6/site-packages (from requests>=2.5.0->sphinx) (1.25.10)
Requirement already satisfied: certifi>=2017.4.17 in /usr/lib/python3.6/site-packages (from requests>=2.5.0->sphinx) (2018.1.18)
Collecting MarkupSafe>=2.0
  Downloading MarkupSafe-2.0.1-cp36-cp36m-manylinux2010_x86_64.whl (30 kB)
Requirement already satisfied: pyparsing!=3.0.5,>=2.0.2 in /usr/lib/python3.6/site-packages (from packaging>=21.0->sphinx) (2.4.7)
Installing collected packages: sphinxcontrib-jsmath, sphinxcontrib-applehelp, sphinxcontrib-devhelp, pytz, babel, alabaster, imagesize, Pygments, docutils, typing-extensions, zipp, importlib-metadata, sphinxcontrib-serializinghtml, sphinxcontrib-htmlhelp, MarkupSafe, Jinja2, snowballstemmer, sphinxcontrib-qthelp, packaging, sphinx
  WARNING: The script pybabel is installed in '/home/itnixpro/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
  WARNING: The script pygmentize is installed in '/home/itnixpro/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
  WARNING: The scripts sphinx-apidoc, sphinx-autogen, sphinx-build and sphinx-quickstart are installed in '/home/itnixpro/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
Successfully installed Jinja2-3.0.3 MarkupSafe-2.0.1 Pygments-2.13.0 alabaster-0.7.12 babel-2.10.3 docutils-0.18.1 imagesize-1.4.1 importlib-metadata-4.8.3 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 typing-extensions-4.1.1 zipp-3.6.0

Configure Sphinx-Doc on OpenSUSE Linux

  • Navigate to the Apache document root directory on OpenSUSE Linux.
cd /srv/www/
  • Then start Sphinx-Doc.

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): nixpro
> Project release []: 15

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 /srv/www/
Creating file /srv/www/index.rst.
Creating file /srv/www/Makefile.
Creating file /srv/www/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /srv/www/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, generate a static HTML file using the following command.
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

  • Run the command below to create Apache virtual host for Sphinx-Doc.
sudo nano /etc/apache2/conf.d/sphinx.conf

Paste the configuration below.

            ServerAdmin [email protected]
            DocumentRoot /srv/www/_build/html/
            ErrorLog /var/log/apache2/error_log
            CustomLog /var/log/apache2/access_log common

  • Then change /srv/www/ directory ownership using the command below.
sudo chown -R wwwrun:wwwrun /srv/www/
  • Restart Apache using the following command to apply changes.
sudo systemctl restart apache2
  • Open your browser and enter your computer IP address or domain name to access Sphinx-Doc e.g.
Install Sphinx-Doc on OpenSUSE Linux
Install Sphinx-Doc on OpenSUSE Linux
  • You have made it to the end of our article, we have gone through how to Install Sphinx-Doc on OpenSUSE Linux.

Read more on Sphinx-Doc Documentation

Other Tutorials

Create Data Map Visualization in Kibana

How to find path to a command in Linux

How to kill a process in Linux

System administrator | Software Developer | DevOps

Leave a Comment