Understanding Ansible conf.py files - ansible/community GitHub Wiki

Ansible builds three documentation sites out of a similar set of files. We make heavy use of the options within the Sphinx conf.py file. Specifically, we have four conf.py files in the sphinx_conf directory. (Note: the 2.10_conf.py file is used in the 2.10 docs build but that release has EOL'd). The docs/docsite/makefile selects the correct conf.py file and simlinks it appropriately based on the docs build selected.

Important sections in the conf.py files

Each release requires some changes to these conf.py files, typically in the following areas:

VERSION - this sets the version displayed at the top left of the documentation.
exclude_patterns - this is where we exclude RST files or directories that we do not want as part of a specific documentation set. For example, collection contributor documentation is not included in the ansible-core documentation.
html_context: latest_version and available_versions - control the version switcher in the upper left side of the docsite.
intersphinx_mapping - supporst the intersphinx extension and allows us to link between other docsites, just as python. We update this list withe the new ansible release shortly after the release is published.

Note: the conf.py files have not been cleaned up in ages so there is some old crud there that is never used.

all_conf.py

This file includes all of the rst files and is used for translation (I think??)

ansible_conf.py

This file includes the rst files used for the Ansible package documentation.

core_conf.py

This file includes only the core rst files and excludes files related only to the Ansible package (such as the old scenario guides etc).

core_lang_conf.py

This file is similar to the core_conf.py but contains elements to support the version switcher on the Japanese translation docset. Versions for Japanese include the version number appended with _ja.