We choose Sphinx as our documentation tool.

Sphinx is written in Python and supports Python 3.6+. It builds upon the shoulders of many third-party libraries such as Docutils and Jinja, which are installed when Sphinx is installed.

Install either python3-sphinx using apt-get:

apt-get install python3-sphinx

If it is not already present, this will install Python for you.

Install python-sphinx using yum:

yum install python-sphinx

If it is not already present, this will install Python for you.

Most Linux distributions have Sphinx in their package repositories. Usually, the package is called python3-sphinx, python-sphinx, or sphinx. Be aware that there are at least two packages with a sphinx in their name: a speech recognition toolkit (CMU Sphinx) and a full-text search database (Sphinx search).

Sphinx can be installed using Homebrew, MacPorts, or as part of a Python distribution such as Anaconda.

brew install sphinx-doc

For more information, refer to the package overview.

Install either python3x-sphinx using port:

sudo port install py38-sphinx

To set up the executable paths, use the port select command:

sudo port select --set python python38
sudo port select --set sphinx py38-sphinx

For more information, refer to the package overview.

conda install sphinx

Sphinx can be installed using Chocolatey or installed manually.

choco install sphinx

You would need to install Chocolatey before running this. For more information, refer to the chocolatey page.

On Linux or macOS, or Windows, you should open your terminal and run the following command.

pip install -U sphinx

After installation, type sphinx-build --version on the command prompt. If everything worked fine, you would see the version number for the Sphinx package you just installed.

When installing Sphinx using pip, it is highly recommended to use virtual environments, isolating the installed packages from the system packages, thus removing the need to use administrator privileges. To create a virtual environment in the .venv directory, use the following command.

python -m venv .venv

You can install Sphinx directly from a clone of the Git repository. This can be done by cloning the repo and installing it from the local clone on simply installing directly via git.

git clone https://github.com/sphinx-doc/sphinx
cd sphinx
pip install

or

pip install git+https://github.com/sphinx-doc/sphinx

You can also download a snapshot of the Git repo in either tar.gz or zip format. Once downloaded and extracted, these can be installed with pip as above.

Markdown is a lightweight markup language with a simple plain text formatting syntax. It exists in many syntactically different flavors.

To configure your Sphinx project for Markdown support, proceed as follows:

1. Install the Markdown parser MyST-Parser:

   pip install --upgrade myst-parser

2. Add myst_parser to the list of configured extensions:

   extensions = ['myst_parser']

3. If you want to use Markdown files with extensions other than .md, adjust the source_suffix variable. The following example configures Sphinx to parse all files with the extensions .md and .txt as Markdown:

   source_suffix = {
       '.rst': 'restructuredtext',
       '.txt': 'markdown',
       '.md': 'markdown',
       }

4. You can further configure MyST-Parser to allow custom syntax that standard CommonMark doesn’t support. Read more in the MyST-Parser documentation.

The configuration directory must contain a file named conf.py. This file (containing Python code) is called the “build configuration file” and contains (almost) all configurations needed to customize Sphinx input and output behavior.

Important points to note:

• If not otherwise documented, values must be strings, and their default is the empty string.

• The term “fully-qualified name” refers to a string that names an importable Python object inside a module; for example, the FQN "sphinx.builders.Builder" means the Builder class in the sphinx. Builders module.

• Remember that document names use / as the path separator and don’t contain the file name extension.

• Since conf.py is read as a Python file, the usual rules apply for encodings and Unicode support.

• The contents of the config namespace are pickled (so that Sphinx can find out when configuration changes), so it may not contain unpickable values – delete them from the namespace with del if appropriate. Modules are removed automatically, so you don’t need to del your imports after use.

• There is a special object named tags available in the config file. It can be used to query and change the tags (see Including content based on tags). Use tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to change. Only tags set via the -t command-line option or via tags.add('tag') can be queried using tags.has('tag'). Note that the current builder tag is not available in conf.py, as it is created after the builder is initialized.

A list of strings that are module names of extensions. These can be extensions coming with Sphinx (named sphinx.ext.*) or custom ones.

import sys, os
sys.path.append(os.path.abspath('sphinxext'))
extensions = ['extname']

The file extensions of source files. Sphinx considers the files with this suffix as sources. The value can be a dictionary mapping file extensions to file types. For example:

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'restructuredtext',
    '.md': 'markdown',
}

A dictionary that maps language names to options for the lexer modules of Pygments. These are lexer-specific; for the options understood by each, see the Pygments documentation.

Example:

highlight_options = {
  'default': {'stripall': True},
  'php': {'startinline': True},
}

Sphinx provides several builders for HTML and HTML-based formats.

Sphinx supports changing the appearance of its HTML output via themes. A theme is a collection of HTML templates, stylesheet(s), and other static files. Additionally, it has a configuration file that specifies which theme to inherit, which highlighting style to use, and what options exist for customizing the theme’s look and feel.

Using a theme provided with Sphinx is easy. Since these do not need to be installed, you only need to set the html_theme config value. For example, to enable the classic theme, add the following to conf.py:

html_theme = "classic"

You can also set theme-specific options using the html_theme_options config value.

html_theme_options = {
    "rightsidebar": "true",
    "relbarbgcolor": "black"
}

The directory or zip file must be put where Sphinx can find it; for this, the config value is html_theme_path.

html_theme = "blue"
html_theme_path = ["."]

The third form is a Python package. If a theme you want to use is distributed as a Python package, you can use it after installing.

pip install sphinxjp.themes.dotted

Once installed, this can be used in the same manner as a directory or zipfile-based theme:

html_theme = "dotted"

Sphinx supports integration with setuptools and distutils through a custom command - BuildDoc.

The Sphinx build can then be triggered from distutils, and some Sphinx options can be set in setup.py or setup.cfg instead of Sphinx’s own configuration file.

For instance, from setup.py:

# this is only necessary when not using setuptools/distribute
from sphinx.setup_command import BuildDoc
cmdclass = {'build_sphinx': BuildDoc}

name = 'My project'
version = '1.2'
release = '1.2.0'
setup(
    name=name,
    author='Bernard Montgomery',
    version=release,
    cmdclass=cmdclass,
    # these are optional and override conf.py settings
    command_options={
        'build_sphinx': {
            'project': ('setup.py', name),
            'version': ('setup.py', version),
            'release': ('setup.py', release),
            'source_dir': ('setup.py', 'doc')}},
)

Or add this section in setup.cfg:

[build_sphinx]
project = 'My project'
version = 1.2
release = 1.2.0
source-dir = 'doc'

Once configured, call this by calling the relevant command on setup.py:

python setup.py build_sphinx

A boolean that determines whether the saved environment should be discarded on the build. Default is false.

This can also be set by passing the -E flag to setup.py:

python setup.py build_sphinx -E

A boolean that determines whether all files should be built from scratch. Default is false.

This can also be set by passing the -a flag to setup.py:

python setup.py build_sphinx -a

The target source directory. This can be relative to the setup.py or setup.cfg file or it can be absolute. It defaults to ./doc or ./docs if either contains a file named conf.py (checking ./doc first); otherwise it defaults to the current directory.

This can also be set by passing the -s flag to setup.py:

python setup.py build_sphinx -s $SOURCE_DIR

Location of the configuration directory. This can be relative to the setup.py or setup.cfg file or it can be absolute. Default is to use source-dir.

This can also be set by passing the -c flag to setup.py:

$ python setup.py build_sphinx -c $CONFIG_DIR

The builder or list of builders to use. Default is HTML.

This can also be set by passing the -b flag to setup.py:

python setup.py build_sphinx -b $BUILDER

Changed in version 1.6: This can now be a comma- or space-separated list of builders.

A boolean that ensures Sphinx warnings will result in a failed build. Default is false.

This can also be set by passing the -W flag to setup.py:

python setup.py build_sphinx -W

A boolean that ensures index.html will be linked to the root doc. Default is false.

This can also be set by passing the -i flag to setup.py:

python setup.py build_sphinx -i