This article will go through how to install Sphinx-Doc on Ubuntu Linux. Sphinx is a documentation generator that makes it simple to build intelligent and appealing documentation. It has several valuable features for generating technical documentation, such as output formats, comprehensive cross-references, hierarchical structure, automatic indices, code handling, extensions, and themes.
How to Install Sphinx-Doc on Ubuntu Linux
- Update your system packages using the command below.
sudo apt update- Then install the required dependencies using the following command.
sudo apt install python3-pip python3-dev python3-setuptools apache2 -ySample output
Reading package lists... Done Building dependency tree... Done Reading state information... Done The following additional packages will be installed: apache2-bin apache2-data apache2-utils binutils binutils-common binutils-x86-64-linux-gnu build-essential dpkg-dev fakeroot g++ g++-11 gcc gcc-11 javascript-common libalgorithm-diff-perl libalgorithm-diff-xs-perl libalgorithm-merge-perl libapr1 libaprutil1 libaprutil1-dbd-sqlite3 libaprutil1-ldap libasan6 libatomic1 libbinutils libc-dev-bin libc-devtools libc6-dev libcc1-0 libcrypt-dev libctf-nobfd0 libctf0 libdpkg-perl libexpat1-dev libfakeroot libfile-fcntllock-perl libgcc-11-dev libitm1 libjs-jquery libjs-sphinxdoc libjs-underscore liblsan0 libnsl-dev libpython3-dev libpython3-stdlib libpython3.10 libpython3.10-dev libpython3.10-minimal libpython3.10-stdlib libquadmath0 libstdc++-11-dev libtirpc-dev libtsan0 libubsan1 linux-libc-dev lto-disabled-list make manpages-dev python3 python3-distutils python3-lib2to3 python3-minimal python3-wheel python3.10 python3.10-dev python3.10-minimal rpcsvc-proto zlib1g zlib1g-dev Suggested packages: apache2-doc apache2-suexec-pristine | apache2-suexec-custom www-browser binutils-doc debian-keyring g++-multilib g++-11-multilib gcc-11-doc gcc-multilib autoconf automake libtool flex bison gcc-doc gcc-11-multilib gcc-11-locales glibc-doc git bzr libstdc++-11-doc make-doc python3-doc python3-tk python3-venv python-setuptools-doc python3.10-venv python3.10-doc binfmt-support The following NEW packages will be installed: apache2 apache2-bin apache2-data apache2-utils binutils binutils-common binutils-x86-64-linux-gnu build-essential dpkg-dev fakeroot g++ g++-11 gcc gcc-11 javascript-common libalgorithm-diff-perl libalgorithm-diff-xs-perl libalgorithm-merge-perl libapr1 libaprutil1 libaprutil1-dbd-sqlite3 libaprutil1-ldap libasan6 libatomic1 libbinutils libc-dev-bin libc-devtools libc6-dev libcc1-0 libcrypt-dev libctf-nobfd0 libctf0 libdpkg-perl libexpat1-dev libfakeroot libfile-fcntllock-perl libgcc-11-dev libitm1 libjs-jquery libjs-sphinxdoc libjs-underscore liblsan0 libnsl-dev libpython3-dev libpython3.10-dev libquadmath0 libstdc++-11-dev libtirpc-dev libtsan0 libubsan1 linux-libc-dev lto-disabled-list make manpages-dev python3-dev python3-distutils python3-pip python3-setuptools python3-wheel python3.10-dev rpcsvc-proto zlib1g-dev The following packages will be upgraded: libpython3-stdlib libpython3.10 libpython3.10-minimal libpython3.10-stdlib python3 python3-lib2to3 python3-minimal python3.10 python3.10-minimal zlib1g 10 upgraded, 62 newly installed, 0 to remove and 101 not upgraded. Need to get 64.0 MB/71.6 MB of archives. After this operation, 228 MB of additional disk space will be used.
- Next, Install Sphinx-Doc on Ubuntu.
sudo apt install python3-sphinxSample output
Reading package lists... Done Building dependency tree... Done Reading state information... Done The following additional packages will be installed: docutils-common python-babel-localedata python3-alabaster python3-babel python3-docutils python3-imagesize python3-jinja2 python3-packaging python3-pygments python3-roman python3-snowballstemmer sphinx-common Suggested packages: docutils-doc fonts-linuxlibertine | ttf-linux-libertine texlive-lang-french texlive-latex-base texlive-latex-recommended python-jinja2-doc python-pygments-doc ttf-bitstream-vera python3-stemmer dvipng fonts-freefont-otf imagemagick-6.q16 latexmk libjs-mathjax python3-sphinx-rtd-theme sphinx-doc tex-gyre texlive-fonts-recommended texlive-latex-extra texlive-plain-generic The following NEW packages will be installed: docutils-common python-babel-localedata python3-alabaster python3-babel python3-docutils python3-imagesize python3-jinja2 python3-packaging python3-pygments python3-roman python3-snowballstemmer python3-sphinx sphinx-common 0 upgraded, 13 newly installed, 0 to remove and 101 not upgraded. Need to get 7,775 kB of archives. After this operation, 41.6 MB of additional disk space will be used. Do you want to continue? [Y/n] y
Configure Sphinx-Doc on Ubuntu Linux
- Navigate to the Apache document root directory.
cd /var/www/html/- Then start Sphinx-Doc using the command below.
sudo sphinx-quickstartSample output
Welcome to the Sphinx 4.3.2 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 []: 22.04 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, generate a static HTML file using the following command.
sudo make htmlSample output
Running Sphinx v4.3.2 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
- Open Apache configuration and point document root to
_build/htmldirectory.
sudo nano /etc/apache2/sites-available/000-default.conf- On the DocumentRoot option add
_build/htmlas shown below.
DocumentRoot /var/www/html/_build/html- Then restart the Apache server to apply changes.
sudo systemctl restart apache2- After restarting the Apache server, you can access Sphinx-Doc by entering your server IP or domain name on the browser. e.g.
http://127.0.0.1
- That marks the end of our article on how to Install Sphinx-Doc on Ubuntu Linux.
Read more on Sphinx-Doc Documentation
