Install Sphinx-Doc on Debian Linux

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

How to Install Sphinx-Doc on Debian Linux

• Update Debian packages using the command below.

sudo apt update

• Install dependencies using the following command.

sudo apt install python3-pip python3-dev python3-setuptools apache2 -y

• Then Install Sphinx-Doc on Debian Linux.

sudo apt install python3-sphinx

Sample output

Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following package was automatically installed and is no longer required:
  linux-image-5.10.0-9-amd64
Use 'sudo apt autoremove' to remove it.
The following additional packages will be installed:
  docutils-common libimagequant0 python-babel-localedata
  python3-alabaster python3-babel python3-docutils python3-imagesize
  python3-jinja2 python3-olefile python3-packaging python3-pil
  python3-pygments python3-pyparsing python3-roman
  python3-snowballstemmer python3-tz sphinx-common
Suggested packages:
  docutils-doc fonts-linuxlibertine | ttf-linux-libertine
  texlive-lang-french texlive-latex-base texlive-latex-recommended
  python-jinja2-doc python-pil-doc python3-pil-dbg
  python-pygments-doc ttf-bitstream-vera python-pyparsing-doc
  python3-stemmer dvipng fonts-freefont-otf imagemagick-6.q16 latexmk
  libjs-mathjax python3-sphinx-rtd-theme sphinx-doc
  texlive-fonts-recommended texlive-latex-extra texlive-plain-generic
The following NEW packages will be installed:
  docutils-common libimagequant0 python-babel-localedata
  python3-alabaster python3-babel python3-docutils python3-imagesize
  python3-jinja2 python3-olefile python3-packaging python3-pil
  python3-pygments python3-pyparsing python3-roman
  python3-snowballstemmer python3-sphinx python3-tz sphinx-common
0 upgraded, 18 newly installed, 0 to remove and 87 not upgraded.
Need to get 8,288 kB of archives.
After this operation, 43.9 MB of additional disk space will be used.
Do you want to continue? [Y/n] y

Configure Sphinx-Doc on Debian Linux

• Go to the Apache document root directory.

cd /var/www/html/

• Start Sphinx-Doc using the command below.

sudo sphinx-quickstart

Sample output

Welcome to the Sphinx 3.4.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: itnixpro
> Author name(s): debian
> Project release []: 11

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.

• Generate static HTML file.

sudo make html

Sample output

Running Sphinx v3.4.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.

Configure Apache

• To configure Apache, open its configuration file and point the document root to _build/html directory.

sudo nano /etc/apache2/sites-available/000-default.conf

• Next, on the DocumentRoot option add _build/html as shown below.

DocumentRoot /var/www/html/_build/html

• Restart the Apache server using the following command to apply changes.

sudo systemctl restart apache2

• Access Sphinx-Doc by entering your server IP or domain name on the browser. e.g. http://127.0.0.1

• You have made it to the end of our article, we have gone through how to Install Sphinx-Doc on Debian Linux.

Read more on Sphinx-Doc Documentation

Other Tutorials

Install OpenSCAP on Ubuntu 22.04

Install pgAdmin on Rocky Linux

Install PostgreSQL on Rocky Linux