Requirements

Installation requirements

Doxphinx is installed from the Python Package Index, PyPI, using the command pip. This command is included in all recent releases of Python. Thus just check for the presence of Python3 in the system and install if needed.

Python 3.5

Doxphinx relies on Sphinx as the documentation building engine, which in turn requires Python versions 3.5.x or newer.

Checking for Python 3

To check for a working installation of the Python language interpreter, open a terminal and run the command python --version:

$ python --version
Python 3.7.1

In the example above, the command shows that the version 3.7.1 of Python is installed. If the command responds, instead, with an older version of Python, like:

$ python --version
Python 2.7.15

try entering the python3 --version command:

$ python3 --version
Python 3.7.1

If it now responds correctly this could mean that both Python2 and Python3 are installed in the system. Ensure that Python 3 commands are used when building the documentation.

Installing Python 3

If Python is not installed in the system consult the Python 3 documentation to properly install Python3 and the pip command.

Runtime requirements

In order to use doxphinx for a documentation project you need to have the Sphinx documentation system installed. Also, to generate PDF documents you will need a LaTeX distribution.

Sphinx 7.0.0 or above

Doxphinx requires versions 7.0.0 or above of the Sphinx documentation system.

When installing doxphinx, using the command pip, Sphinx also will be automatically installed as well as other needed Python packages if they are not present in the system.

To install or update Sphinx, run:

$ pip install -U sphinx

To check for a working installation of the Sphinx documentation tool, open a terminal and run the command:

$ pip show sphinx

Name: sphinx
Version: 7.0.1
Summary: Python documentation generator
Home-page: None
Author: None
Author-email: Georg Brandl <georg@python.org>
License: None
Location: /home/angel/.local/lib/python3.9/site-packages
Requires: importlib-metadata, sphinxcontrib-qthelp, sphinxcontrib-htmlhelp, docutils,
  snowballstemmer, imagesize, sphinxcontrib-applehelp, sphinxcontrib-jsmath, Jinja2,
  sphinxcontrib-devhelp, Pygments, babel, alabaster, sphinxcontrib-serializinghtml,
  packaging, requests
Required-by: doxphinx

LaTeX

In order to build the documentation in PDF format doxphinx requires a running distribution of the LaTeX typesetting system.

Tip

If you do not have LaTeX installed in the system, doxphinx will not be able to build PDF books from the documentation files. However, it still will be able to build a HTML website. If you do not plan to release your documentation in PDF format, you do not need to install LaTex.

Checking for LaTeX

To check for a working installation of the LaTeX typesetting system, open a terminal and run the command latex -v:

$ latex -v

pdfTeX 3.14159265-2.6-1.40.18 (TeX Live 2017)
kpathsea version 6.2.3
Copyright 2017 Han The Thanh (pdfTeX) et al.
There is NO warranty.  Redistribution of this software is
covered by the terms of both the pdfTeX copyright and
the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the pdfTeX source.
Primary author of pdfTeX: Han The Thanh (pdfTeX) et al.
Compiled with libpng 1.6.29; using libpng 1.6.29
Compiled with zlib 1.2.11; using zlib 1.2.11
Compiled with xpdf version 3.04

In the example output above, the command shows that a version of pdfTeX, from the TeX Live 2017 distribution, is installed.

If the system responds instead with something like:

$ latex -v
bash: latex: command not found

you need to install a LaTeX distribution if you plan to generate PDF documentation.

Installing LaTeX

If no LaTeX distribution is installed in the system, see Getting LaTeX to get a copy and install LaTeX for your operating system.