Project configuration

Configuring the project

A set of options can be defined in the conf.py file, located at the top directory of the documentation project, to control and customize the documentation output. Some options are global for the project and other are specific fot the HTML or the PDF outputs.

Tip

You can read The Sphinx configuration page to learn more about these options.

Configuring the global options

The global options for whole project can be set in the conf.py file.

Configuring the project’s name

The name of the project was set when running the command sphinx-quickstart but can be changed by editing the value of the variable project in the conf.py file:

project = 'doxphinx'

This value is shown in the navigation bar on the HTML output and the title page and the headers of the PDF pages.

Configuring the author’s name

The name or names of the author of the documentation can be defines in the author variable:

author = 'John & Mary Smith'

This value is shown in the footer on the HTML output and in the cover page of the PDF documentation.

Configuring the release numbers

You can configure the version and release numbers for the documentation in the conf.py file:

version = '1.1'
release = '1.1.0'

The release value is shown in the navigation bar on the HTML output and the title page and the headers of the PDF pages.

Configuring doxphinx for Sphinx

Edit the conf.py file in order to point to the doxphinx theme and extensions.

Linking the theme

To set the HTML theme used when building the documentation in HTML format, Sphinx reads the html_theme variable. In order to make doxphinx the theme to be used, edit the conf.py file, search for the html_theme variable, and set it to doxphinx:

html_theme = 'doxphinx'

Linking the extension

Doxphinx also includes a Sphinx extension to deal with the side bar contents. In order for Sphinx to find and use the included extension, edit the conf.py file and search for the extensions variable and add the entry doxphinx.ext.localtoc to the list:

extensions = [
    ...
    'doxphinx.ext.localtoc',
    ...
]

Tip

After changing these variables, run again the command make html to see how the built documentation changes when the doxphinx theme is applied. Congratulations! You are now using doxphinx.