###### tags: `Documentation` # Ansible community docs 2023: RTD Sphinx build of Ansible Core As part of the effort to [decouple from the package docs](https://hackmd.io/Ejh1G6hjSO2DFiJXyUpUsw), Ansible Core docs were tested with the RTD Sphinx build using the following configuration: ``` python: install: - requirements: ./requirements.txt - requirements: ./test/sanity/code-smell/docs-build.requirements.txt sphinx: builder: dirhtml configuration: docs/docsite/rst/conf.py ``` Here are details from the RTD run: ``` python -m pip install --upgrade --no-cache-dir pip setuptools python -m pip install --upgrade --no-cache-dir pillow mock==1.0.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.9.1 recommonmark==0.5.0 sphinx sphinx-rtd-theme readthedocs-sphinx-ext<2.3 python -m pip install --exists-action=w --no-cache-dir -r requirements.txt python -m pip install --exists-action=w --no-cache-dir -r test/sanity/code-smell/docs-build.requirements.txt python -m sphinx -T -E -b dirhtml -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/html .... Running Sphinx v5.3.0 making output directory... done building [mo]: targets for 0 po files that are out of date building [dirhtml]: targets for 460 source files that are out of date ``` The RTD run fails with the following: ``` reading sources... [ 46%] network/user_guide/platform_ce /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/2.10_index.rst:42: WARNING: toctree contains reference to nonexisting document 'dev_guide/index' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/2.10_index.rst:73: WARNING: toctree contains reference to nonexisting document 'collections/index' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/2.10_index.rst:73: WARNING: toctree contains reference to nonexisting document 'reference_appendices/playbooks_keywords' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/2.10_index.rst:73: WARNING: toctree contains reference to nonexisting document 'reference_appendices/config' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/2.10_index.rst:73: WARNING: toctree contains reference to nonexisting document 'dev_guide/testing/sanity/index' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/ansible_index.rst:63: WARNING: toctree contains reference to nonexisting document 'dev_guide/index' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/ansible_index.rst:94: WARNING: toctree contains reference to nonexisting document 'collections/index' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/ansible_index.rst:94: WARNING: toctree contains reference to nonexisting document 'reference_appendices/playbooks_keywords' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/ansible_index.rst:94: WARNING: toctree contains reference to nonexisting document 'reference_appendices/config' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/ansible_index.rst:94: WARNING: toctree contains reference to nonexisting document 'dev_guide/testing/sanity/index' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/ansible_index.rst:1: WARNING: duplicate label ansible_documentation, other instance in /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/2.10_index.rst /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/collections/all_plugins.rst:6: WARNING: toctree glob pattern 'index_*' didn't match any documents /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/command_guide/command_line_tools.rst:12: WARNING: toctree contains reference to nonexisting document 'cli/ansible' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/command_guide/command_line_tools.rst:12: WARNING: toctree contains reference to nonexisting document 'cli/ansible-config' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/command_guide/command_line_tools.rst:12: WARNING: toctree contains reference to nonexisting document 'cli/ansible-console' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/command_guide/command_line_tools.rst:12: WARNING: toctree contains reference to nonexisting document 'cli/ansible-doc' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/command_guide/command_line_tools.rst:12: WARNING: toctree contains reference to nonexisting document 'cli/ansible-galaxy' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/command_guide/command_line_tools.rst:12: WARNING: toctree contains reference to nonexisting document 'cli/ansible-inventory' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/command_guide/command_line_tools.rst:12: WARNING: toctree contains reference to nonexisting document 'cli/ansible-playbook' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/command_guide/command_line_tools.rst:12: WARNING: toctree contains reference to nonexisting document 'cli/ansible-pull' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/command_guide/command_line_tools.rst:12: WARNING: toctree contains reference to nonexisting document 'cli/ansible-vault' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/core_index.rst:69: WARNING: toctree contains reference to nonexisting document 'dev_guide/index' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/core_index.rst:82: WARNING: toctree contains reference to nonexisting document 'collections/index' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/core_index.rst:82: WARNING: toctree contains reference to nonexisting document 'reference_appendices/playbooks_keywords' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/core_index.rst:82: WARNING: toctree contains reference to nonexisting document 'reference_appendices/config' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/core_index.rst:82: WARNING: toctree contains reference to nonexisting document 'dev_guide/testing/sanity/index' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/dev_guide/ansible_index.rst:66: WARNING: toctree contains reference to nonexisting document 'dev_guide/collections_galaxy_meta' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/dev_guide/core_index.rst:63: WARNING: toctree contains reference to nonexisting document 'dev_guide/collections_galaxy_meta' /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/dev_guide/core_index.rst:5: WARNING: duplicate label developer_guide, other instance in /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/dev_guide/ansible_index.rst /home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/checkouts/latest/docs/docsite/rst/dev_guide/developing_collections.rst:29: WARNING: toctree contains reference to nonexisting document 'dev_guide/collections_galaxy_meta' Traceback (most recent call last): File "/home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/envs/latest/lib/python3.11/site-packages/sphinx/cmd/build.py", line 281, in build_main app.build(args.force_all, args.filenames) File "/home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/envs/latest/lib/python3.11/site-packages/sphinx/application.py", line 347, in build self.builder.build_update() File "/home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/envs/latest/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 310, in build_update self.build(to_build, File "/home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/envs/latest/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 326, in build updated_docnames = set(self.read()) ^^^^^^^^^^^ File "/home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/envs/latest/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 433, in read self._read_serial(docnames) File "/home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/envs/latest/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 454, in _read_serial self.read_doc(docname) File "/home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/envs/latest/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 510, in read_doc publisher.publish() File "/home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/envs/latest/lib/python3.11/site-packages/docutils/core.py", line 219, in publish self.apply_transforms() File "/home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/envs/latest/lib/python3.11/site-packages/docutils/core.py", line 200, in apply_transforms self.document.transformer.apply_transforms() File "/home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/envs/latest/lib/python3.11/site-packages/sphinx/transforms/__init__.py", line 80, in apply_transforms super().apply_transforms() File "/home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/envs/latest/lib/python3.11/site-packages/docutils/transforms/__init__.py", line 171, in apply_transforms transform.apply(**kwargs) File "/home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/envs/latest/lib/python3.11/site-packages/docutils/transforms/references.py", line 719, in apply nested_name = normed[nested_ref['refname'].lower()] ~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ KeyError: 'br' Exception occurred: File "/home/docs/checkouts/readthedocs.org/user_builds/oranod-ansible/envs/latest/lib/python3.11/site-packages/docutils/transforms/references.py", line 719, in apply nested_name = normed[nested_ref['refname'].lower()] ~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``` Attempting to reproduce that locally is successful: ``` python -m pip install --upgrade --no-cache-dir pip setuptools six wheel python -m pip install --upgrade --no-cache-dir pillow mock==1.0.1 alabaster==0.7.13 commonmark==0.9.1 recommonmark==0.5.0 sphinx sphinx-rtd-theme readthedocs-sphinx-ext==2.2.0 python -m pip install --exists-action=w --no-cache-dir -r ./requirements.txt python -m pip install --exists-action=w --no-cache-dir -r ./test/sanity/code-smell/docs-build.requirements.txt python -m sphinx -T -E -b dirhtml -d _build/doctrees -D language=en . _rtd/html .... Running Sphinx v5.3.0 loading intersphinx inventory from https://docs.python.org/2/objects.inv... loading intersphinx inventory from https://docs.python.org/3/objects.inv... loading intersphinx inventory from http://jinja.palletsprojects.com/objects.inv... loading intersphinx inventory from https://docs.ansible.com/ansible/7/objects.inv... loading intersphinx inventory from https://docs.ansible.com/ansible/6/objects.inv... loading intersphinx inventory from https://docs.ansible.com/ansible/2.9/objects.inv... intersphinx inventory has moved: http://jinja.palletsprojects.com/objects.inv -> https://jinja.palletsprojects.com/en/3.1.x/objects.inv building [mo]: targets for 0 po files that are out of date building [dirhtml]: targets for 10650 source files that are out of date .... build succeeded, 163 warnings. The HTML pages are in _rtd/html. ``` It appears that the structure of the `ansible/docs/docsite` directory means that the RTD Sphinx build cannot resolve all the targets to generate the complete source. A clue to this is given in the line `building [dirhtml]: targets for x source files that are out of date`.
Last changed by  
 
Ansible Community
Support Ansible Community working groups and related initiatives
56

Read more

Bullhorn #134

This week in Ansible CommunityIssue #134, 2024-03-29 (Past Issues)

3/29/2024
Creating AWX CLI Guide

Proble

3/25/2024
Bullhorn #133

This week in Ansible CommunityIssue #13, 2024-03-25 (Past Issues)

3/25/2024
Bullhorn #132

This week in Ansible CommunityIssue #11, 2024-03-15 (Past Issues)

3/16/2024
Read more from Ansible Community
Published on HackMD