ansible-community / antsibull-docs Goto Github PK

View Code? Open in Web Editor NEW

20.0 4.0 15.0 2.43 MB

Tooling for building Ansible documentation

Home Page: https://ansible.readthedocs.io/projects/antsibull-docs/

License: GNU General Public License v3.0

Python 81.26% Shell 1.54% Jinja 15.84% SCSS 1.25% JavaScript 0.04% TeX 0.07%

css python ansible hacktoberfest collections

antsibull-docs's Introduction

antsibull-docs -- Ansible Documentation Build Scripts

Tooling for building Ansible documentation. This is mainly the antsibull-docs command and the Sphinx extension, sphinx_antsibull_ext. Please check out the documentation for more information.

You can find a list of changes in the antsibull-docs changelog.

antsibull-docs is covered by the Ansible Code of Conduct.

Versioning and compatibility

From version 1.0.0 on, antsibull-docs sticks to semantic versioning and aims at providing no backwards compatibility breaking changes to the command line API (antsibull-docs) during a major release cycle. We might make exceptions from this in case of security fixes for vulnerabilities that are severe enough.

The current major version is 2.x.y. Development for 2.x.y occurs on the main branch. 2.x.y mainly differs from 1.x.y by dropping support for Python 3.6, 3.7, and 3.8, and by dropping support for older Ansible/ansible-base/ansible-core versions. See the changelog for details. 1.x.y is still developed on the stable-1 branch, but only security fixes, major bugfixes, and other absolutely necessary changes will be backported.

We explicitly exclude code compatibility. antsibull-docs is not supposed to be used as a library. The only exception are potential dependencies with other antsibull projects (currently there are none). If you want to use a certain part of antsibull-docs as a library, please create an issue so we can discuss whether we add a stable interface for parts of the Python code. We do not promise that this will actually happen though.

If you are interested in library support for interpreting Ansible markup, please take a look at the antsibull-docs-parser project.

Development

Install and run nox to run all tests. That's it for simple contributions! nox will create virtual environments in .nox inside the checked out project and install the requirements needed to run the tests there.

antsibull-docs depends on the sister antsibull-core and antsibull-docs-parser projects. By default, nox will install a development version of these projects from Github. If you're hacking on antsibull-core and/or antsibull-docs-parser alongside antsibull-docs, nox will automatically install the projects from ../antsibull-core and ../antsibull-docs-parser when running tests if those paths exist. You can change this behavior through the OTHER_ANTSIBULL_MODE env var:

OTHER_ANTSIBULL_MODE=auto — the default behavior described above
OTHER_ANTSIBULL_MODE=local — install the projects from ../antsibull-core and ../antsibull-docs-parser. Fail if those paths don't exist.
OTHER_ANTSIBULL_MODE=git — install the projects from the Github main branch
OTHER_ANTSIBULL_MODE=pypi — install the latest versions from PyPI

To run specific tests:

nox -e test to only run unit tests;
nox -e lint to run all linters and formatter;
nox -e codeqa to run flake8, pylint, reuse lint, and antsibull-changelog lint;
nox -e formatters to run isort and black;
nox -e typing to run mypy and pyre.

To create a more complete local development env:

git clone https://github.com/ansible-community/antsibull-core.git
git clone https://github.com/ansible-community/antsibull-docs-parser.git
git clone https://github.com/ansible-community/antsibull-docs.git
cd antsibull-docs
python3 -m venv venv
. ./venv/bin/activate
pip install -e '.[dev]' -e ../antsibull-core -e ../antsibull-docs-parser
[...]
nox

Updating the CSS file for the Sphinx extension

The CSS file sphinx_antsibull_ext/antsibull-minimal.css is built from sphinx_antsibull_ext/css/antsibull-minimal.scss using SASS and postcss using autoprefixer and cssnano.

Use the script build.sh in sphinx_antsibull_ext/css/ to build the .css file from the .scss file:

cd sphinx_antsibull_ext/css/
./build-css.sh

For this to work, you need to install some Node.js dependencies:

npm clean-install

Creating a new release:

Run nox -e bump -- <version> <release_summary_message>. This:
- Bumps the package version in src/antsibull_docs/__init__.py.
- Creates changelogs/fragments/<version>.yml with a release_summary section.
- Runs antsibull-changelog release --version <version> and adds the changed files to git.
- Commits with message Release <version>. and runs git tag -a -m 'antsibull-docs <version>' <version>.
- Runs hatch build --clean.
Run git push to the appropriate remotes.
Once CI passes on GitHub, run nox -e publish. This:
- Runs hatch publish;
- Bumps the version to <version>.post0;
- Adds the changed file to git and run git commit -m 'Post-release version bump.';
Run git push --follow-tags to the appropriate remotes and create a GitHub release.

License

Unless otherwise noted in the code, it is licensed under the terms of the GNU General Public License v3 or, at your option, later. See LICENSES/GPL-3.0-or-later.txt for a copy of the license.

The repository follows the REUSE Specification for declaring copyright and licensing information. The only exception are changelog fragments in changelog/fragments/.

antsibull-docs's People

Contributors

Stargazers

Watchers

Forkers

felixfontein alvistack gotmax23 benjaminschubert andersson007 sserrata oranod jpodivin m-varasteh devon-mar cloudera-labs sivel bcoca sebastiangode russoz-ansible

antsibull-docs's Issues

Add deprecation marker to deprecated modules/plugins in indexes and plugin/module lists

Switch from libsass to Dart sass compiler

Docs builds are failing with Sphinx 5.2.0.post0

Sphinx 5.2.0 was just released today:

sphinx-doc/sphinx#10853

I haven't been able to figure out why yet, but at least in community.hashi_vault the docs build is failing with:

Reason: ValueError('too many values to unpack (expected 3)')

I first noticed it after making an innocuous change to a previously passing build (adding license header comments):
https://github.com/ansible-collections/community.hashi_vault/actions/runs/3119998619/jobs/5060610693#step:8:126

In CI it's coming up on my inclusion of changelog in the docsite:

Theme error:
An error happened in rendering the page collections/community/hashi_vault/docsite/CHANGELOG.
Reason: ValueError('too many values to unpack (expected 3)')

When I tried to reproduce it locally, I couldn't, until I upgraded the requirements (after having installed them fresh a few hours earlier) and saw that it upgraded sphinx from 5.1.1 to 5.2.0.post0, after thatI could repro, but it came up on a different file, so I don't think it's related to anything I'm doing:

Theme error:
An error happened in rendering the page collections/community/hashi_vault/docsite/about_hashi_vault_lookup.
Reason: ValueError('too many values to unpack (expected 3)')

There's at least one other report of a failing build with it:

sphinx-gallery/sphinx-gallery#1017

Use code formatting for all values (choice entries, defaults, samples)

Right now, while values in the description that are (correctly) formtated with C(...) have code / teletype formatting, other auto-generated values such as choice list entries, defaults, and samples, are formatted as regular text (only with different colors).

@briantist suggested (#36 (comment)) to format choice list entries also as code, and I extended that suggestion to format also defaults and samples values as code.

What do you think?

Errors when building multiple collections at once

If I try to build a documentation site for multiple (small) collections it takes long time and fails afterwards with the below error messages. Any idea about a possible root cause?

Versions in use

Ubuntu 20.04
Virtual python environment (based on virtualenv) with Python v3.11.4
antsibull-docs v2.3.1
ansible [core 2.15.2]
- config file = None
- configured module search path = ['/home/vagrant/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
- ansible python module location = /home/vagrant/venv/ans_py311/lib/python3.11/site-packages/ansible
- ansible collection location = /home/vagrant/.ansible/collections:/usr/share/ansible/collections
- executable location = /home/vagrant/venv/ans_py311/bin/ansible
- python version = 3.11.4 (main, Jun 7 2023, 12:45:49) [GCC 9.4.0] (/home/vagrant/venv/ans_py311/bin/python)
- jinja version = 3.1.2
- libyaml = True

Commands

source /home/vagrant/venv/ans_py311/bin/activate
antsibull-docs sphinx-init --use-current --dest-dir /home/vagrant/ans_test/DEST mynamespace.first_collection mynamespace.second_collection
cd /home/vagrant/ans_test/DEST
pip install -r requirements.txt 
./build.sh

Output

Skipping /home/vagrant/ans_test/DEST/.gitignore
Skipping /home/vagrant/ans_test/DEST/antsibull-docs.cfg
Skipping /home/vagrant/ans_test/DEST/build.sh
Skipping /home/vagrant/ans_test/DEST/conf.py
Skipping /home/vagrant/ans_test/DEST/requirements.txt
Skipping /home/vagrant/ans_test/DEST/rst/index.rst
To build the docsite, go into /home/vagrant/ans_test/DEST and run:
    pip install -r requirements.txt  # possibly use a venv
    ./build.sh
Requirement already satisfied: antsibull-docs<3.0.0,>=2.0.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from -r requirements.txt (line 5)) (2.3.1)
Requirement already satisfied: ansible-pygments in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from -r requirements.txt (line 6)) (0.1.1)
Requirement already satisfied: sphinx in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from -r requirements.txt (line 7)) (6.2.1)
Requirement already satisfied: sphinx-ansible-theme>=0.9.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from -r requirements.txt (line 8)) (0.10.2)
Requirement already satisfied: aiohttp>=3.0.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (3.8.5)
Requirement already satisfied: antsibull-core<3.0.0,>=2.0.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (2.0.0)
Requirement already satisfied: antsibull-docs-parser<2.0.0,>=1.0.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (1.0.0)
Requirement already satisfied: asyncio-pool in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (0.6.0)
Requirement already satisfied: docutils in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (0.18.1)
Requirement already satisfied: jinja2>=3.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (3.1.2)
Requirement already satisfied: packaging in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (23.1)
Requirement already satisfied: pydantic<2.0.0,>=1.0.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (1.10.12)
Requirement already satisfied: pyyaml in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (6.0.1)
Requirement already satisfied: rstcheck<7.0.0,>=3.0.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (6.1.2)
Requirement already satisfied: semantic-version in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (2.10.0)
Requirement already satisfied: twiggy in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (0.5.1)
Requirement already satisfied: pygments>=2.4.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from ansible-pygments->-r requirements.txt (line 6)) (2.15.1)
Requirement already satisfied: sphinxcontrib-applehelp in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from sphinx->-r requirements.txt (line 7)) (1.0.4)
Requirement already satisfied: sphinxcontrib-devhelp in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from sphinx->-r requirements.txt (line 7)) (1.0.2)
Requirement already satisfied: sphinxcontrib-jsmath in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from sphinx->-r requirements.txt (line 7)) (1.0.1)
Requirement already satisfied: sphinxcontrib-htmlhelp>=2.0.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from sphinx->-r requirements.txt (line 7)) (2.0.1)
Requirement already satisfied: sphinxcontrib-serializinghtml>=1.1.5 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from sphinx->-r requirements.txt (line 7)) (1.1.5)
Requirement already satisfied: sphinxcontrib-qthelp in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from sphinx->-r requirements.txt (line 7)) (1.0.3)
Requirement already satisfied: snowballstemmer>=2.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from sphinx->-r requirements.txt (line 7)) (2.2.0)
Requirement already satisfied: babel>=2.9 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from sphinx->-r requirements.txt (line 7)) (2.12.1)
Requirement already satisfied: alabaster<0.8,>=0.7 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from sphinx->-r requirements.txt (line 7)) (0.7.13)
Requirement already satisfied: imagesize>=1.3 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from sphinx->-r requirements.txt (line 7)) (1.4.1)
Requirement already satisfied: requests>=2.25.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from sphinx->-r requirements.txt (line 7)) (2.31.0)
Requirement already satisfied: sphinx-rtd-theme>=1.1.1 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from sphinx-ansible-theme>=0.9.0->-r requirements.txt (line 8)) (1.2.2)
Requirement already satisfied: attrs>=17.3.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from aiohttp>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (23.1.0)
Requirement already satisfied: charset-normalizer<4.0,>=2.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from aiohttp>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (3.2.0)
Requirement already satisfied: multidict<7.0,>=4.5 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from aiohttp>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (6.0.4)
Requirement already satisfied: async-timeout<5.0,>=4.0.0a3 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from aiohttp>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (4.0.2)
Requirement already satisfied: yarl<2.0,>=1.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from aiohttp>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (1.9.2)
Requirement already satisfied: frozenlist>=1.1.1 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from aiohttp>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (1.4.0)
Requirement already satisfied: aiosignal>=1.1.2 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from aiohttp>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (1.3.1)
Requirement already satisfied: aiofiles in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-core<3.0.0,>=2.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (23.1.0)
Requirement already satisfied: build in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-core<3.0.0,>=2.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (0.10.0)
Requirement already satisfied: perky in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-core<3.0.0,>=2.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (0.9.2)
Requirement already satisfied: sh<2.0.0,>=1.0.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from antsibull-core<3.0.0,>=2.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (1.14.3)
Requirement already satisfied: MarkupSafe>=2.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from jinja2>=3.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (2.1.3)
Requirement already satisfied: typing-extensions>=4.2.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from pydantic<2.0.0,>=1.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (4.7.1)
Requirement already satisfied: idna<4,>=2.5 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from requests>=2.25.0->sphinx->-r requirements.txt (line 7)) (3.4)
Requirement already satisfied: urllib3<3,>=1.21.1 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from requests>=2.25.0->sphinx->-r requirements.txt (line 7)) (2.0.4)
Requirement already satisfied: certifi>=2017.4.17 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from requests>=2.25.0->sphinx->-r requirements.txt (line 7)) (2023.7.22)
Requirement already satisfied: rstcheck-core<2.0.0,>=1.0.2 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from rstcheck<7.0.0,>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (1.0.3)
Requirement already satisfied: typer[all]<0.8,>=0.4.1 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from rstcheck<7.0.0,>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (0.7.0)
Requirement already satisfied: sphinxcontrib-jquery<5,>=4 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from sphinx-rtd-theme>=1.1.1->sphinx-ansible-theme>=0.9.0->-r requirements.txt (line 8)) (4.1)
Requirement already satisfied: six in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from twiggy->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (1.16.0)
Requirement already satisfied: types-docutils<0.20,>=0.18 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from rstcheck-core<2.0.0,>=1.0.2->rstcheck<7.0.0,>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (0.19.1.9)
Requirement already satisfied: click<9.0.0,>=7.1.1 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (8.1.6)
Requirement already satisfied: colorama<0.5.0,>=0.4.3 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (0.4.6)
Requirement already satisfied: shellingham<2.0.0,>=1.3.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (1.5.0.post1)
Requirement already satisfied: rich<13.0.0,>=10.11.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (12.6.0)
Requirement already satisfied: pyproject_hooks in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from build->antsibull-core<3.0.0,>=2.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (1.0.0)
Requirement already satisfied: commonmark<0.10.0,>=0.9.0 in /home/vagrant/venv/ans_py311/lib/python3.11/site-packages (from rich<13.0.0,>=10.11.0->typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<3.0.0,>=2.0.0->-r requirements.txt (line 5)) (0.9.1)
~/ans_test/DEST ~/ans_test/DEST
Traceback (most recent call last):
  File "/home/vagrant/venv/ans_py311/bin/antsibull-docs", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/home/vagrant/venv/ans_py311/lib/python3.11/site-packages/antsibull_docs/cli/antsibull_docs.py", line 797, in main
    return run(sys.argv)
           ^^^^^^^^^^^^^
  File "/home/vagrant/venv/ans_py311/lib/python3.11/site-packages/antsibull_docs/cli/antsibull_docs.py", line 778, in run
    return ARGS_MAP[parsed_args.command]()
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vagrant/venv/ans_py311/lib/python3.11/site-packages/antsibull_docs/cli/doc_commands/collection.py", line 125, in generate_docs
    return generate_collection_docs(None, output_format, squash_hierarchy)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vagrant/venv/ans_py311/lib/python3.11/site-packages/antsibull_docs/cli/doc_commands/collection.py", line 40, in generate_collection_docs
    return generate_docs_for_all_collections(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vagrant/venv/ans_py311/lib/python3.11/site-packages/antsibull_docs/cli/doc_commands/_build.py", line 112, in generate_docs_for_all_collections
    plugin_info, full_collection_metadata = asyncio.run(
                                            ^^^^^^^^^^^^
  File "/usr/lib/python3.11/asyncio/runners.py", line 190, in run
    return runner.run(main)
           ^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.11/asyncio/runners.py", line 118, in run
    return self._loop.run_until_complete(task)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.11/asyncio/base_events.py", line 653, in run_until_complete
    return future.result()
           ^^^^^^^^^^^^^^^
  File "/home/vagrant/venv/ans_py311/lib/python3.11/site-packages/antsibull_docs/docs_parsing/parsing.py", line 76, in get_ansible_plugin_info
    return await ansible_doc_core_213_get_ansible_plugin_info(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vagrant/venv/ans_py311/lib/python3.11/site-packages/antsibull_docs/docs_parsing/ansible_doc_core_213.py", line 113, in get_ansible_plugin_info
    ansible_doc_output = await _call_ansible_doc(venv, env)
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vagrant/venv/ans_py311/lib/python3.11/site-packages/antsibull_docs/docs_parsing/ansible_doc_core_213.py", line 35, in _call_ansible_doc
    p = await venv.async_log_run(
        ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vagrant/venv/ans_py311/lib/python3.11/site-packages/antsibull_core/venv.py", line 187, in async_log_run
    return await subprocess_util.async_log_run(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vagrant/venv/ans_py311/lib/python3.11/site-packages/antsibull_core/subprocess_util.py", line 132, in async_log_run
    completed.check_returncode()
  File "/usr/lib/python3.11/subprocess.py", line 502, in check_returncode
    raise CalledProcessError(self.returncode, self.args, self.stdout,
subprocess.CalledProcessError: Command '['ansible-doc', '-vvv', '--metadata-dump', '--no-fail-on-errors']' died with <Signals.SIGKILL: 9>.
~/ans_test/DEST

Collection note should indicate that further dependencies may be required.

Can't transfer the issue from ansible/ansible#74195 so doing the copy-pasta:

I am a contributor to the ansible.azcollection project. In order for those modules to execute, many azure specific packages must be installed via pip.
At the top of all of the online documentation for modules, there is a "Note" banner on installing the collection, example
https://docs.ansible.com/ansible/latest/collections/azure/azcollection/azure_rm_storageaccount_module.html
That banner is added to every module's doc in all of the collections in that doc site.

The problem we're running into is that newer users read that banner and believe that it satisfies all dependencies by doing the 'ansible-galaxy collection install ${collection} ' . Could some additional text be added to indicate that there may be further dependencies, and that they should click on the collection link to see the collection specific docs?

I would attempt a PR myself, but I have no idea how the docs are composed or where the banner message is being pulled from. If this is not the correct repo to report the issue against, let me know and I'll resubmit there.

Plan for 2.0.0

@gotmax23 what do you think about the following:

Get a 1.x.y version done for use in ansible-core 2.15.
Once that's done (basically once ansible-core 2.15 is in feature freeze), create a stable-1 branch and prepare 2.0.0 (drop Python < 3.9 etc.).
Release 2.0.0.

Adding more than one section in `extra-docs.yml` results in no sections included in output.

I have a docsite with extra-docs.yml like so:

---
sections:
  - title: Guides
    toctree:
      - filter_guide
      - user_guide
      - migration_hashi_vault_lookup
      - about_hashi_vault_lookup
      - lookup_guide
      - contributor_guide
      - localenv_developer_guide

If I try to add new page new_thing to the existing guides section, it works fine:

---
sections:
  - title: Guides
    toctree:
      - filter_guide
      - user_guide
      - new_thing
      - migration_hashi_vault_lookup
      - about_hashi_vault_lookup
      - lookup_guide
      - contributor_guide
      - localenv_developer_guide

If I try to add that page to a new, additional section, neither of the two sections are produced in the output:

---
sections:
  - title: New Things
    toctree:
      - new_thing
  - title: Guides
    toctree:
      - filter_guide
      - user_guide
      - migration_hashi_vault_lookup
      - about_hashi_vault_lookup
      - lookup_guide
      - contributor_guide
      - localenv_developer_guide

If I remove the original section, and just include the new one, then the new one shows up as expected:

---
sections:
  - title: New Things
    toctree:
      - new_thing

I've looked through the code a bit, but was not able to figure out where the issue might be.

I should add that there are no errors or warnings when this happens, not even WARNING: document isn't included in any toctree shows up.

[RFE] Add support for adding additional sphinx/intersphinx configuration

The current sphinx_init configuration file template doesn't support adding additional intersphinx links.

When moving modules between collections, this leaves a period of time where docs for a collection can't be validated/built because https://docs.ansible.com/ansible/devel/ hasn't been updated to include the new object.inv.

With the AWS collections, because we now have GitHub pages with the docs for 'main' automatically built and pushed, we would be able to inject something like 'amazon_aws': ('https://ansible-collections.github.io/amazon.aws/branch/main/', (None, '../amazon_aws.inv')) into intersphinx_mapping and as soon as the module has been moved, we'd be able to validate the links in our 'main' branches.

It would be helpful if we could either

Specify additional intersphinx links
Specify a file, the contents of which would be appended to conf.py
Have a standard location in the collection from which antsibull-docs would read and append to conf.py

Be able to override note on ansible-galaxy commands

I'm currently building a private ansible collection. It contains roles and modules.

Because of this private aspect, it will (probably) never be uploaded to ansible-galaxy.

Now, when I'm build my documentation, I'd like the links and command in the note to fit my context. For example, just by running the normal antsibull commands, I have the following output :

But :

the link behind itcorp_datalayer.deploy_app points to a link to https://galaxy.ansible.com which probably never exists.
The command to install my collection isn't correct : in fact, I don't (and probably never) have an ansible-galaxy server. So this command ansible-galaxy collection install itcorp_datalayer.deploy_app will never work. So I'd like to be able to override the full command to reflect my git dependency setup.

Just for the record, I'm currently using a tox environment to build my docs and, before any changes I have the following builds :

[testenv:docs]
description = "Environment to generate docs"
skip_install = true
allowlist_externals =
    bash
    git
    cp
    mkdir
    rm
## This is needed to be able to use custom PYPI configuration
passenv =
    PIP_*
    HOME
    ANSIBLE_COLLECTIONS_PATH
deps =
    ansible
    antsibull
commands =
    mkdir -p {env:HOME}/tmp/docs
    antsibull-docs sphinx-init --use-current --dest-dir {env:HOME}/tmp/docs itcorp_datalayer.deploy_app
    pip install -r {env:HOME}/tmp/docs/requirements.txt
    bash -c '{env:HOME}/tmp/docs/build.sh'
    git rm -rf {toxinidir}/docs
    cp -rf {env:HOME}/tmp/docs/build/html {toxinidir}/docs
    rm -rf {env:HOME}/tmp/docs
    git add {toxinidir}/docs
    bash -c 'git diff-index --quiet HEAD || git commit -m "[TOOLS] 📝 Generate docs"'

So I think this could be great to be able to customize more the output of the documentations.

Workaround

As suggested by @felixfontein in the Ansible chat, I have updated the provided build.sh file to fit my needs. For now, I have the following tox setup

[testenv:docs]
description = "Environment to generate docs"
skip_install = true
allowlist_externals =
    bash
    git
    cp
    mkdir
    rm
## This is needed to be able to use custom PYPI configuration
passenv =
    PIP_*
    HOME
    ANSIBLE_COLLECTIONS_PATH
deps =
    ansible
    antsibull
commands =
    mkdir -p {env:HOME}/tmp/docs
    antsibull-docs sphinx-init --use-current --dest-dir {env:HOME}/tmp/docs itcorp_datalayer.deploy_app
    pip install -r {env:HOME}/tmp/docs/requirements.txt
    bash -c '{toxinidir}/build-docs.sh {env:HOME}/tmp/docs' # Here are the changes.
    git rm -rf {toxinidir}/docs
    cp -rf {env:HOME}/tmp/docs/build/html {toxinidir}/docs
    rm -rf {env:HOME}/tmp/docs
    git add {toxinidir}/docs
    bash -c 'git diff-index --quiet HEAD || git commit -m "[TOOLS] 📝 Generate docs"'

And my build-docs.sh looks like this :

#!/usr/bin/env bash
## This file is mostly extracted

set -e
cd ${1:?Please define the repository to find the ansible documentation}

# Create collection documentation into temporary directory
rm -rf temp-rst
mkdir -p temp-rst
antsibull-docs collection \
    --use-current \
    --no-use-html-blobs \
    --breadcrumbs \
    --indexes \
    --dest-dir temp-rst \
    itcorp_datalayer.deploy_app

# Copy collection documentation into source directory
rsync -cprv --delete-after temp-rst/collections/ rst/collections/

# Fix documentation to fit our needs
## Change ansible-galaxy URL to my Git URL
grep -rl 'https://galaxy.ansible.com/itcorp_datalayer/deploy_app' rst | xargs sed -i 's/galaxy.ansible.com\/itcorp_datalayer\/deploy_app/gitprovider.com\/path\/to\/my\/repository/g'
## Change ansible-galaxy command line to a git one
grep -rl 'ansible-galaxy collection install itcorp_datalayer.deploy_app' rst | xargs sed -i 's/ansible-galaxy collection install itcorp_datalayer.deploy_app/ansible-galaxy collection install git+https:\/\/gitprovider.com\/path\/to\/my\/repo,main/g'

# Build Sphinx site
sphinx-build -M html rst build -c . -W --keep-going

With this setup, I have the following output :

With the link pointing to what I want and the command looks like a command runnable in my context.

Escape backticks that some collections use in module/plugin docs

In an effort to lower the number of warnings in the Ansible docs builds, we can add some code to antsibull-docs that escapes the backticks that some folks put into their module/plugin docs.

When squashing hierarchy, remove "List of collections with docs hosted here." link

As seen on https://ansible-collections.github.io/community.dns/branch/main/ at the bottom.

CC @briantist

How to handle environment variables?

With semantic markup, we have E(...) to reference environment variables. For RST output, the Sphinx :envvar: role is used (https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-envvar). antsibull-docs uses the .. envvar:: directive (https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-envvar) for all environment variables that appear in env: plugin configs (and the Ansible/ansible-core docsite generates .. envvar:: directives for all ansible-core config values, see https://github.com/ansible/ansible/blob/devel/docs/templates/config.rst.j2#L223-L248). But for all other environment variables mentioned in text, there is no such (auto-generated) target.

So either collections define their own targets, which can cause problems if multiple collections define targets that end up in the Ansible docsite, or they don't, and we end up with a list of WARNING: 'envvar' reference target not found: warnings. A good example is ansible-collections/community.docker#645 with its output https://github.com/ansible-collections/community.docker/actions/runs/5235637304/jobs/9452611330.

This makes using E(...) inattractive or even outright impossible (for example in community.docker, the docsite build must have no errors for CI to pass). Manually defining .. envvar:: directives is not a good idea either (except in special cases). #75 would improve the situation a bit, but it won't happen anytime soon (core doesn't like it).

I'm opening this issue so we can discuss what to do about this. Having a huge amount of new reference errors in the docsite build is something I'm pretty sure nobody wants. Just muting all these warnings (the one for env vars, not the general reference errors) isn't a good idea either IMO.

Improve support for Sphinx LaTeX builder

This issue is tracking what's needed to improve support for the Sphinx LaTeX builder:

Force long tables, improve column distribution: #195
Make nested options/return values work: #198
Make collection links section work: #200
Improve styling of all the roles used by antsibull-docs: #199

Ref: ansible/ansible-documentation#109 (comment)

Building the ansible documentation always times out

As described at ansible/ansible#78002.

Render changelogs in docsite build

Inspired by ansible-collections/community.hashi_vault#299

There are a couple of things to discuss/decide:

Should this be done for every collection that has a changelog in the correct format, or only for collections who opt-in?
Should it use changelogs/changelog.yaml as the source of truth, or some rendered CHANGELOG.rst file? The trouble with the former (which I would prefer) is that antsibull-docs then needs to depend on antsibull-changelog in some form, which potentially leads back to the trouble of "updating antsibull-docs forces an update of antsibull-changelog" in ansible-core's test containers (antsibull-docs is only needed in the ansible-core default test container, while antsibull-changelog is included in all default test containers and thus updates to it are potentially user noticeable).

seealso plugin/module refs should be checked by linter

Right now they aren't. The community.general.read_csv module was referencing a non-existing community.general.readcsv lookup (it should have been ansible.builtin.readcsv), and I only noticed due to Sphinx errors.

Allow to lint plugin docs in ansible-core

Our linter is more powerful than ansible-core's validate-modules' markup checker, since it verifies that options, return values, and plugin/modules referenced actually exist.

[v2] Use new typing syntax and remove Python 3.6 compat code

Linter: warn when docs/docsite/links.yml is present with default values

Values to check:

edit_on_github.repository is ansible-collections/community.REPO_NAME
extra_links == [{'description': 'Report an issue', 'url': 'https://github.com/ansible-collections/community.REPO_NAME/issues/new/choose'}]

See https://github.com/ansible-collections/collection_template/blob/main/docs/docsite/links.yml.

Clarification on "expanded collections" and support for collections on disk

When running antsibull-docs collection --help it says this about the collection list:

positional arguments:
  collections           One or more collections to document. If the names are directories on disk, they will be parsed as
                        expanded collections. Otherwise, if they could be collection names, they will be downloaded from galaxy.

I thought this might mean that you could give path names (where collections already exist) and that it would use those, retrieving the collection name from the galaxy.yml or MANIFEST.json in that path. But it does not seem to work that way, since it ends up trying to download the path as though it's a collection name.

antsibull_core.galaxy.NoSuchCollection: No collection found at: https://galaxy.ansible.com/api/v2/collections/tmp/adocs/ansible_collections/namespace/collection/versions/

When I look through the code, it doesn't seem like there is any code supporting reading such a collection from disk, so I'm wondering if that note about the names being "directories on disk" refers to old functionality, or maybe it means something else entirely?

If I try to do the same with --use-current, the command "succeeds" but doesn't actually build anything except an empty index.rst and environment_variables.rst, presumably because it couldn't find collections with those weird names (there's no console output at all in this case, and --fail-on-error also didn't change that).

Why I was interested in this

I'm going to build an internal docsite, and so I need some way to know which collections to include.
Some will be installed via git rather than through the galaxy API protocol.

To organize this, I thought it might be nice to simply use a requirements.yml with the git sources to serve as my canonical collection list. If I install them in a separate step, then I can use --use-current to avoid auto-install, but then I need to supply the collection names themselves to antsibull-docs again.

I thought I could avoid it altogether with a workflow that looks something like:

ansible-galaxy collection install -r requirements.yml -p /tmp/adocs
antsibull-docs collection /tmp/adocs/ansible_collections/namespace/*

I wasn't too keen on parsing the YAML myself just to pass the names, especially since for git sources the name: field is the git URL so I don't necessarily have a name to pass without storing it separately.

Suggestions

For now I will just have to keep a separate list of collection names probably, but I can imagine two possible enhancements:

You're already attempting to install collections from the list of names, maybe have a mode where it takes a requirements.yml file instead and can install using that config, and then no names need to be passed.
Implement/restore the ability to pass directories on disk that already refer to collections.

If you think either of those are a possibility I can split them out to separate issues, curious what you think.

Anchor links on module parameters, attributes and return values are broken on Safari

Summary

The possibility to have an anchor on parameters, attributes and return values of a module page seems broken on Safari.
The link does appear properly when hovering the corresponding table cell, though, but they still cannot be clicked and seems not recognised as links, for some reason.

Example of the issue:

As compared to an anchor on a title, that is working

On top of that, removing the visibility: hidden; in the class table.ansible-option-table .ansibleOptionLink makes all the links appear and clickable as they should.

I was not able to trace what is the underlying issue of this for the moment being, though.

This is definitely a Safari related bug, as the exact same page(s) on Chrome does offer the proper behaviour.

Issue Type

Documentation Report

Component Name

Any module page

OS / Environment

Safari Version 16.5 (18615.2.9.11.4) on Mac OS Ventura (13.4)

Code of Conduct

I agree to follow the Ansible Code of Conduct

Show callback type

Right now the type of a callback plugin isn't shown in the HTML docsite, while it is shown by ansible-doc (ref: ansible-collections/community.general#5734 (comment)).

fix some lost formatting

Between version 2.3 and 2.4, we lost some formatting on the parameters. Devel works fine:

But stable-2.15 and earlier look as follows:

Allow to declare collections as unmaintained, ... for Ansible docsite builds

That should use https://github.com/ansible-community/ansible-build-data/blob/main/8/collection-meta.yaml somehow.

Bad name for module in custom collection

With my team, we have a custom collection. In this collection we have custom modules.

In particular, we have these directory layout :

These modules must be called in our playbook with the entire directory names. For example, module plugins/modules/cde/job.py is called with namespace.collection_name.cde.job.

We're also building our documentation through antsibull-docs.

Doing so we have a website with all our module documentation. However the name if the module name on the docs is not correctly set : in particular, we miss the intermediate directory name. For example, module plugins/modules/cde/job.py is referenced under namespace.collection_name.job (so without the cde directory).

In conclusion, I think that there is an issue when the docs is created : it looks like it removes all intermediate directories in the module names.

RFE: Add supported Ansible versions to the collection "index.html"

See for example: https://ansible-collections.github.io/amazon.aws/branch/main/collections/amazon/aws/index.html

Since teams are now starting to build the docs independently, and module consumers are installing collections that don't match the big-tent "Ansible" version they have installed it would be good if the index page lists which versions of Ansible are supported.

I think this is generated from src/antsibull_docs/data/docsite/plugins_by_collection.rst.j2 but I don't know if/how this can be pulled from meta/runtime.yml

accessibility feedback on module tables

From a recent reddit post asking users to evaluate the new tables using the following two links:

https://docs.ansible.com/ansible/devel/collections/community/crypto/acme_certificate_module.html#parameters and https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/hashi_vault_lookup.html#parameters.

I sometimes need to use a screen reader and access these docs using lynx. Here are a few observations :-

When I browse to either link with lynx I get a "bad HTML" message.

It renders anyway but the warning possibly ought to be fixed. I suggest you validate here:- https://validator.w3.org/nu/?doc=https%3A%2F%2Fdocs.ansible.com%2Fansible%2Fdevel%2Fcollections%2Fcommunity%2Fcrypto%2Facme_certificate_module.html against the wc3 standards.

I also tried with links and that didn't display an error.

Next test was actually using the page with a screen reader. It was a bit of a problem because the text structure inside the tables is very confusing when read aloud.

Lastly and this one is really minor, the little 'permalink' symbol you use for linking doesn't have a character in the font on my terminal so it renders as a ? in a box.

When I bring the page up in Firefox and use the screen reader, for some reason the tables don't get read out at all. I get told which cell of the table I am in but not what the content is.

Make sure label casing is OK

When building my personal docsite, I get some undefined label errors:

rst/collections/community/general/ipmi_power_module.rst:209: WARNING: undefined label: 'ansible_collections.community.general.ipmi_power_module__parameter-machine/targetAddress'
rst/collections/community/general/ipmi_power_module.rst:780: WARNING: undefined label: 'ansible_collections.community.general.ipmi_power_module__return-status/targetAddress'
rst/collections/community/general/keycloak_client_module.rst:2329: WARNING: undefined label: 'ansible_collections.community.general.keycloak_client_module__parameter-protocol_mappers/protocolMapper'
rst/collections/community/general/keycloak_clientscope_module.rst:667: WARNING: undefined label: 'ansible_collections.community.general.keycloak_clientscope_module__parameter-protocol_mappers/protocolMapper'
rst/collections/community/general/keycloak_clienttemplate_module.rst:686: WARNING: undefined label: 'ansible_collections.community.general.keycloak_clienttemplate_module__parameter-protocol_mappers/protocolMapper'
rst/collections/community/general/keycloak_group_module.rst:908: WARNING: undefined label: 'ansible_collections.community.general.keycloak_group_module__return-end_state/realmRoles'
rst/collections/community/general/keycloak_group_module.rst:908: WARNING: undefined label: 'ansible_collections.community.general.keycloak_group_module__return-end_state/clientRoles'
rst/collections/community/general/keycloak_identity_provider_module.rst:1559: WARNING: undefined label: 'ansible_collections.community.general.keycloak_identity_provider_module__parameter-mappers/identityProviderMapper'
rst/collections/community/general/ocapi_info_module.rst:683: WARNING: undefined label: 'ansible_collections.community.general.ocapi_info_module__return-operationHealth'
rst/collections/community/general/packet_device_module.rst:795: WARNING: undefined label: 'ansible_collections.community.general.packet_device_module__parameter-wait_for_public_IPv'

I guess the casing is wrong?

Clarify the plugin 'configuration entries' hint in the docs

Currently we have the following note at https://github.com/ansible-community/antsibull-docs/blob/main/src/antsibull_docs/data/docsite/plugin.rst.j2#L461 which says:

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.

Some users are confused by that line so would be good to clarify and point to an area on docs.ansible.com that provides more detail.

Galaxy v3 API: update `collection_url` defaults

The current default is {"*": "https://galaxy.ansible.com/{namespace}/{name}"}, which will likely not work for arbitrary collections for the new Ansible Community Galaxy.

Update Versioning and compatibility section of the README

We should update the Versioning and compatibility of the README to mention the v1 and v2 maintenance statuses like we did for antsibull-core.

Relates: #104

Antsibull-docs not outputting any files or out putting anything in console

Well trying to get antsibull to generate a RST file for my collection, I have encountered an issue where nothing is getting output to the console or to a file in the build directory I specified in the command. There doesn't seem to be an option to enable debugging for the command, and I am unsure what the problem is. Does anyone know what I can do to get more information in the console or to find out why it's not making a file?

Docsite: See Also --> Lookup Module

Summary

(issue manually moved over from ansible/ansible#79735) created by https://github.com/djarbz)

I am attempting to create my first collection.
Part of doing so is creating and verifying my documentation.

I would like to populate the seealso section, but it appears to be throwing an error.

Issue Type

Bug Report

Component Name

docs/docsite/rst/plugins/lookup.rst

Ansible Version

$ ansible --version
ansible [core 2.13.7]
  config file = /ansible/ansible.cfg
  configured module search path = ['/ansible/local/library']
  ansible python module location = /home/coder/.local/lib/python3.9/site-packages/ansible
  ansible collection location = /ansible/.galaxy:/ansible/local
  executable location = /home/coder/.local/bin/ansible
  python version = 3.9.2 (default, Feb 28 2021, 17:03:44) [GCC 10.2.1 20210110]
  jinja version = 3.1.2
  libyaml = True

Configuration

# if using a version older than ansible-core 2.12 you should omit the '-t all'
$ ansible-config dump --only-changed -t all
CALLBACKS_ENABLED(/ansible/ansible.cfg) = ['ansible.posix.profile_tasks', 'ansible.posix.profile_roles']
COLLECTIONS_PATHS(/ansible/ansible.cfg) = ['/ansible/.galaxy', '/ansible/local']
DEFAULT_GATHERING(/ansible/ansible.cfg) = smart
DEFAULT_HOST_LIST(/ansible/ansible.cfg) = ['/ansible/inventory/hosts.yaml']
DEFAULT_LOOKUP_PLUGIN_PATH(/ansible/ansible.cfg) = ['/ansible/local/plugins/lookup']
DEFAULT_MODULE_PATH(/ansible/ansible.cfg) = ['/ansible/local/library']
DEFAULT_PRIVATE_KEY_FILE(/ansible/ansible.cfg) = /ansible/.ssh/id_ed25519
DEFAULT_REMOTE_USER(/ansible/ansible.cfg) = ansible
DEFAULT_ROLES_PATH(/ansible/ansible.cfg) = ['/ansible/.galaxy/roles', '/ansible/local']

CONNECTION:
==========

paramiko_ssh:
____________
remote_user(/ansible/ansible.cfg) = ansible

ssh:
___
private_key_file(/ansible/ansible.cfg) = /ansible/.ssh/id_ed25519
remote_user(/ansible/ansible.cfg) = ansible

OS / Environment

Debian 11 container on a Debian 11 host.
Container image is: docker.io/notmycloud/vsansible:v4-v6
Running on Podman.

Steps to Reproduce

Expected Results

Antsibull compiles the documentation without an error message.
See also creates actual links.

Actual Results

Skipping /ansible/docs/.gitignore
Skipping /ansible/docs/antsibull-docs.cfg
Skipping /ansible/docs/build.sh
Skipping /ansible/docs/conf.py
Skipping /ansible/docs/requirements.txt
Skipping /ansible/docs/rst/index.rst
To build the docsite, go into /ansible/docs and run:
    pip install -r requirements.txt  # possibly use a venv
    ./build.sh
Requirement already satisfied: antsibull-docs<2.0.0,>=1.0.0 in /home/coder/.local/lib/python3.9/site-packages (from -r requirements.txt (line 5)) (1.9.0)
Requirement already satisfied: ansible-pygments in /home/coder/.local/lib/python3.9/site-packages (from -r requirements.txt (line 6)) (0.1.1)
Requirement already satisfied: sphinx in /home/coder/.local/lib/python3.9/site-packages (from -r requirements.txt (line 7)) (6.1.3)
Requirement already satisfied: sphinx-ansible-theme>=0.9.0 in /home/coder/.local/lib/python3.9/site-packages (from -r requirements.txt (line 8)) (0.9.1)
Requirement already satisfied: packaging in /home/coder/.local/lib/python3.9/site-packages (from antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (22.0)
Requirement already satisfied: asyncio-pool in /home/coder/.local/lib/python3.9/site-packages (from antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.6.0)
Requirement already satisfied: rstcheck<7.0.0,>=3.0.0 in /home/coder/.local/lib/python3.9/site-packages (from antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (6.1.1)
Requirement already satisfied: antsibull-core<3.0.0,>=1.2.0 in /home/coder/.local/lib/python3.9/site-packages (from antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.5.0)
Requirement already satisfied: jinja2 in /home/coder/.local/lib/python3.9/site-packages (from antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (3.1.2)
Requirement already satisfied: docutils in /home/coder/.local/lib/python3.9/site-packages (from antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.19)
Requirement already satisfied: pygments>=2.4.0 in /home/coder/.local/lib/python3.9/site-packages (from ansible-pygments->-r requirements.txt (line 6)) (2.13.0)
Requirement already satisfied: imagesize>=1.3 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (1.4.1)
Requirement already satisfied: requests>=2.25.0 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (2.28.1)
Requirement already satisfied: alabaster<0.8,>=0.7 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (0.7.12)
Requirement already satisfied: sphinxcontrib-serializinghtml>=1.1.5 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (1.1.5)
Requirement already satisfied: sphinxcontrib-qthelp in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (1.0.3)
Requirement already satisfied: importlib-metadata>=4.8 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (6.0.0)
Requirement already satisfied: babel>=2.9 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (2.11.0)
Requirement already satisfied: sphinxcontrib-jsmath in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (1.0.1)
Requirement already satisfied: sphinxcontrib-devhelp in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (1.0.2)
Requirement already satisfied: sphinxcontrib-applehelp in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (1.0.3)
Requirement already satisfied: sphinxcontrib-htmlhelp>=2.0.0 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (2.0.0)
Requirement already satisfied: snowballstemmer>=2.0 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (2.2.0)
Requirement already satisfied: sphinx-rtd-theme in /home/coder/.local/lib/python3.9/site-packages (from sphinx-ansible-theme>=0.9.0->-r requirements.txt (line 8)) (0.5.1)
Requirement already satisfied: twiggy>=0.5.0 in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.5.1)
Requirement already satisfied: aiohttp>=3.0.0 in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (3.8.3)
Requirement already satisfied: aiofiles in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (22.1.0)
Requirement already satisfied: perky in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.5.5)
Requirement already satisfied: sh in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.14.3)
Requirement already satisfied: pydantic in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.10.4)
Requirement already satisfied: PyYAML in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (6.0)
Requirement already satisfied: semantic_version in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (2.10.0)
Requirement already satisfied: pytz>=2015.7 in /home/coder/.local/lib/python3.9/site-packages (from babel>=2.9->sphinx->-r requirements.txt (line 7)) (2022.7)
Requirement already satisfied: zipp>=0.5 in /home/coder/.local/lib/python3.9/site-packages (from importlib-metadata>=4.8->sphinx->-r requirements.txt (line 7)) (3.11.0)
Requirement already satisfied: MarkupSafe>=2.0 in /home/coder/.local/lib/python3.9/site-packages (from jinja2->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (2.1.1)
Requirement already satisfied: urllib3<1.27,>=1.21.1 in /home/coder/.local/lib/python3.9/site-packages (from requests>=2.25.0->sphinx->-r requirements.txt (line 7)) (1.26.13)
Requirement already satisfied: idna<4,>=2.5 in /home/coder/.local/lib/python3.9/site-packages (from requests>=2.25.0->sphinx->-r requirements.txt (line 7)) (3.4)
Requirement already satisfied: certifi>=2017.4.17 in /home/coder/.local/lib/python3.9/site-packages (from requests>=2.25.0->sphinx->-r requirements.txt (line 7)) (2022.12.7)
Requirement already satisfied: charset-normalizer<3,>=2 in /home/coder/.local/lib/python3.9/site-packages (from requests>=2.25.0->sphinx->-r requirements.txt (line 7)) (2.1.1)
Requirement already satisfied: rstcheck-core<2.0.0,>=1.0.2 in /home/coder/.local/lib/python3.9/site-packages (from rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.0.3)
Requirement already satisfied: typer[all]<0.8,>=0.4.1 in /home/coder/.local/lib/python3.9/site-packages (from rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.7.0)
Requirement already satisfied: async-timeout<5.0,>=4.0.0a3 in /home/coder/.local/lib/python3.9/site-packages (from aiohttp>=3.0.0->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (4.0.2)
Requirement already satisfied: yarl<2.0,>=1.0 in /home/coder/.local/lib/python3.9/site-packages (from aiohttp>=3.0.0->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.8.2)
Requirement already satisfied: attrs>=17.3.0 in /home/coder/.local/lib/python3.9/site-packages (from aiohttp>=3.0.0->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (22.1.0)
Requirement already satisfied: aiosignal>=1.1.2 in /home/coder/.local/lib/python3.9/site-packages (from aiohttp>=3.0.0->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.3.1)
Requirement already satisfied: frozenlist>=1.1.1 in /home/coder/.local/lib/python3.9/site-packages (from aiohttp>=3.0.0->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.3.3)
Requirement already satisfied: multidict<7.0,>=4.5 in /home/coder/.local/lib/python3.9/site-packages (from aiohttp>=3.0.0->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (6.0.4)
Requirement already satisfied: types-docutils<0.20,>=0.18 in /home/coder/.local/lib/python3.9/site-packages (from rstcheck-core<2.0.0,>=1.0.2->rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.19.1.1)
Requirement already satisfied: typing-extensions>=4.2.0 in /home/coder/.local/lib/python3.9/site-packages (from pydantic->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (4.4.0)
Requirement already satisfied: six in /home/coder/.local/lib/python3.9/site-packages (from twiggy>=0.5.0->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.16.0)
Requirement already satisfied: click<9.0.0,>=7.1.1 in /home/coder/.local/lib/python3.9/site-packages (from typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (8.1.3)
Requirement already satisfied: shellingham<2.0.0,>=1.3.0 in /home/coder/.local/lib/python3.9/site-packages (from typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.5.0.post1)
Requirement already satisfied: colorama<0.5.0,>=0.4.3 in /home/coder/.local/lib/python3.9/site-packages (from typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.4.6)
Requirement already satisfied: rich<13.0.0,>=10.11.0 in /home/coder/.local/lib/python3.9/site-packages (from typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (12.6.0)
Requirement already satisfied: commonmark<0.10.0,>=0.9.0 in /home/coder/.local/lib/python3.9/site-packages (from rich<13.0.0,>=10.11.0->typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.9.1)
building file list ... done
environment_variables.rst
index_lookup.rst
notmycloud/technitium_dns/index.rst
notmycloud/technitium_dns/login_lookup.rst

sent 80,601 bytes  received 87 bytes  161,376.00 bytes/sec
total size is 80,611  speedup is 1.00
Running Sphinx v6.1.3
loading pickled environment... done
loading intersphinx inventory from ../python2.inv...
encountered some issues with some of the inventories, but they had working alternatives:
intersphinx inventory '../python2.inv' not fetchable due to <class 'FileNotFoundError'>: [Errno 2] No such file or directory: '/ansible/docs/rst/../python2.inv'
loading intersphinx inventory from ../python3.inv...
encountered some issues with some of the inventories, but they had working alternatives:
intersphinx inventory '../python3.inv' not fetchable due to <class 'FileNotFoundError'>: [Errno 2] No such file or directory: '/ansible/docs/rst/../python3.inv'
loading intersphinx inventory from ../jinja2.inv...
loading intersphinx inventory from ../ansible_devel.inv...
encountered some issues with some of the inventories, but they had working alternatives:
encountered some issues with some of the inventories, but they had working alternatives:
intersphinx inventory '../jinja2.inv' not fetchable due to <class 'FileNotFoundError'>: [Errno 2] No such file or directory: '/ansible/docs/rst/../jinja2.inv'
intersphinx inventory '../ansible_devel.inv' not fetchable due to <class 'FileNotFoundError'>: [Errno 2] No such file or directory: '/ansible/docs/rst/../ansible_devel.inv'
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 4 source files that are out of date
updating environment: 0 added, 4 changed, 0 removed
reading sources... [100%] collections/notmycloud/technitium_dns/login_lookup                                                                                                                                             
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                                                                                           
/ansible/docs/rst/collections/notmycloud/technitium_dns/login_lookup.rst:436: WARNING: undefined label: 'ansible_collections.notmycloud.technitium_dns.login_module'
generating indices... done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 1 warning.

Code of Conduct

I agree to follow the Ansible Code of Conduct

Display shortdescription for plugins listed in See Also section

Currenty, the See Also lists related plugins on a plugin docs page, but it doesn't display the short description for that plugin:

Would be great if we could replace that boilerplate text with the actual plugin short description.

`sphinx-init` - paths in `build.sh` are not quoted, spaces lead to failures

When using antsibull-docs sphinx-init the generated build.sh is generated with a cd command into the full hardcoded directory name.

There are actually two issues with this I prefer to address:

If the path contains spaces, the script will fail because the paths are not quoted or escaped.
I would prefer the paths are not hardcoded, but relative.

For 1) we could quote or escape the path. Fixing 2) would fix 1) as well, but it can also be deceptively complicated.

One thing helping us with that maybe is the fact that the script is generated specifically to run in bash, so we don't really have to deal with all the edge cases for other shells.

FWIW, in my own uses, I replace that first line with this:

pushd "${BASH_SOURCE%/*}"

(and then I add popd to the end of the script)

We can use the above with cd as well, and optionally put a cd - at the end, though I don't think I've encountered a system where pushd/popd don't work, I think they are builtins.

At a minimum we should fix the quoting issue, not sure what the opinions are on the the relative path, but I like it for portability (I can move all the generated stuff around and have it still work).

The multibyte role `short_description` causes warning "Title underline too short."

The multibyte role short_description causes warning "Title underline too short."

argument_specs.yml:

---
argument_specs:
  main:
    short_description: short description of Main entry point for テストロール
    description:
      - description of Main entry point for テストロール
    author:
      - akira6592
    options:
      myapp_int:
        type: "int"
        required: false
        default: 42
        description:
          - "The integer value, defaulting to 42."

% dest/build.sh

...(omit)...
/Users/akira/ansible/dest/rst/collections/local/mycollection/myapp_role.rst:19: WARNING: Title underline too short.

local.mycollection.myapp role -- short description of Main entry point for テストロール
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
/Users/akira/ansible/dest/rst/collections/local/mycollection/myapp_role.rst:41: WARNING: Title underline too short.

Entry point ``main`` -- short description of Main entry point for テストロール
------------------------------------------------------------------------

...(omit)...

It is not only role short_description, but maybe also other short_description.

check_mode attribute description should reflect their support status

Right now the attribute description for check_mode always says

Can run in check_mode and return changed status prediction without modifying target

Even if the module explicitly doesn't support check mode (support none) like in the uri example. I can see this being confusing for people reading the docs who might skip over the Support side and read Description thinking this does support check mode when it does not.

I think the description for entries where check mode isn't supported should be updated to actually say something like "this module does not support check mode" in the field.

Related: ansible/ansible#82427

Improve logical information in Sphinx indexes

I tried creating a docset for a collection for use in Dash or Zeal with doc2dash, and noticed that while the process works pretty well (except that the default theme isn't really suitable for this; according to https://gist.github.com/danieltomasz/d6aae37a0ba5f5ba0f17ea68b590731f the epub theme is better suited), with one big exception - the 'Sections' list:

The n copies of "Requirements" isn't exactly helpful (these are the requirements for every plugin and module), and the raw (internal) labels for plugins/modules/roles and their parameters and return values are even less helpful.

The latter can be improved by not adding labels to texts, but instead using a custom directive which generates the label and adds a nice title to it.

These things could also be added to an index (if you generate a PDF, you see that right now only the environmen variables show up in the index, and it is otherwise empty).

Theme error: sphinx `html_js_files` configuration is not supported

Hi everybody!

It seems like antsibull-docs or sphinx-ansible-theme doesn't support the html_js_files configuration option.

  Theme error:
  An error happened in rendering the page environment_variables.
  Reason: IsADirectoryError(21, 'Is a directory')
  writing output... [ 25%] environment_variables

I get the error above when trying to use it. Let me explain.

I use antsibull-docs (thanks for this tool ❤️ ) to build an online documentation for a collection. To track the stats for that documentation, I need to place the following code in the <head>...</head> section of each HTML page generated by antsibull-docs:
<script defer src="https://eu.umami.is/script.js" data-website-id="xxxxxxxxxxxxxxxxxxxxxx"></script>

Based on sphinx documentation, the html_js_files configuration should do the trick. The code below should be placed in sphinx “build configuration file” (conf.py):
html_js_files=[('https://eu.umami.is/script.js', {'data-website-id': 'xxxxxxxxxxxx','defer': 'defer'})]

Since sphinx conf.py file is generated under the hood by antsibull-docs and extra configurations seem to be supported, then I added the code below to my workflow file:

init-extra-html-theme-options: |
   documentation_home_url=https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/branch/main/
init-extra-conf: "html_js_files=[('https://eu.umami.is/script.js', {'data-website-id': 'xxxxxxxxxxxxxxx','defer': 'defer'})]"

Unfortunately, it results in the error pasted at the beginning of this write-up. I'm not sure where's the root cause. Can someone tell me what's going on?

The full GitHub actions workflow file is available at: https://github.com/theko2fi/ansible-multipass-collection/blob/61fa660dddb171b2157db40494612137d432648e/.github/workflows/docs-push.yml
The full log is available at: https://github.com/theko2fi/ansible-multipass-collection/actions/runs/7562640828/job/20593503094

Antsibull-docs 1.2.0 builds all docs instead of just our collection

I'm building my collection doc with antsibull-docs.

Since today (03/08/2022) and the release of antsibull-docs 1.2.0, when building my collection docs all ansible collections docs are built (and so fails because I don't have all collections locally.)

How to reproduce

mkdir -p ~/tmp/docs
export ANSIBLE_COLLECTIONS_PATH=/path/to/your/collection
antsibull-docs sphinx-init --use-current --dest-dir ~/tmp/docs namespace.collection
cd ~/tmp/docs
pip install --upgrade -r requirements.txt
./build.sh

Here you should trying to build documentation for multiple collections and not only yours.

Workaround

As a temporary workaround you could :

Create a constraints file like

antsibull-docs<1.2.0

Then re-run the following commands :

mkdir -p ~/tmp/docs
export ANSIBLE_COLLECTIONS_PATH=/path/to/your/collection
antsibull-docs sphinx-init --use-current --dest-dir ~/tmp/docs namespace.collection
cd ~/tmp/docs
pip install --upgrade -r requirements.txt -c /path/to/your/constraints.txt ## Just use your constraint file here, to avoid installing antsibull-docs 1.2.0
./build.sh

Make RST output configurable

Chose between consumption by Sphinx and consumption by ... others? What exactly this others is needs to be defined, but a big use-case would be things like ansible-collections/community.vmware#1770.

`plugin` entries in `seealso` don't work in role argspecs

https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_documenting.html#documentation-fields

# Reference by plugin name
- plugin: ansible.builtin.file
  plugin_type: lookup

# Reference by plugin name, including description
- plugin: ansible.builtin.file
  plugin_type: lookup
  description: You can use the ansible.builtin.file lookup to read files on the control node.

In role argspecs, they are treated as invalid:

12 validation errors for RoleSchema
[2024-01-25T19:19:07.788Z]     entry_points -> main -> seealso -> 0 -> module
[2024-01-25T19:19:07.788Z]       field required (type=value_error.missing)
[2024-01-25T19:19:07.788Z]     entry_points -> main -> seealso -> 0 -> plugin
[2024-01-25T19:19:07.788Z]       extra fields not permitted (type=value_error.extra)
[2024-01-25T19:19:07.788Z]     entry_points -> main -> seealso -> 0 -> plugin_type
[2024-01-25T19:19:07.788Z]       extra fields not permitted (type=value_error.extra)
[2024-01-25T19:19:07.788Z]     entry_points -> main -> seealso -> 0 -> description
[2024-01-25T19:19:07.788Z]       field required (type=value_error.missing)
[2024-01-25T19:19:07.788Z]     entry_points -> main -> seealso -> 0 -> ref
[2024-01-25T19:19:07.788Z]       field required (type=value_error.missing)
[2024-01-25T19:19:07.788Z]     entry_points -> main -> seealso -> 0 -> plugin
[2024-01-25T19:19:07.788Z]       extra fields not permitted (type=value_error.extra)
[2024-01-25T19:19:07.788Z]     entry_points -> main -> seealso -> 0 -> plugin_type
[2024-01-25T19:19:07.788Z]       extra fields not permitted (type=value_error.extra)
[2024-01-25T19:19:07.788Z]     entry_points -> main -> seealso -> 0 -> description
[2024-01-25T19:19:07.788Z]       field required (type=value_error.missing)
[2024-01-25T19:19:07.788Z]     entry_points -> main -> seealso -> 0 -> link
[2024-01-25T19:19:07.788Z]       field required (type=value_error.missing)
[2024-01-25T19:19:07.788Z]     entry_points -> main -> seealso -> 0 -> name
[2024-01-25T19:19:07.788Z]       field required (type=value_error.missing)
[2024-01-25T19:19:07.788Z]     entry_points -> main -> seealso -> 0 -> plugin
[2024-01-25T19:19:07.788Z]       extra fields not permitted (type=value_error.extra)
[2024-01-25T19:19:07.788Z]     entry_points -> main -> seealso -> 0 -> plugin_type

@felixfontein has already found the problem:
https://github.com/ansible-community/antsibull-docs/blob/main/src/antsibull_docs/schemas/docs/base.py#L613
https://github.com/ansible-community/antsibull-docs/blob/main/src/antsibull_docs/schemas/docs/role.py#L63

ansible-community / antsibull-docs Goto Github PK

antsibull-docs's Introduction

antsibull-docs -- Ansible Documentation Build Scripts

Versioning and compatibility

Development

Updating the CSS file for the Sphinx extension

Creating a new release:

License

antsibull-docs's People

Contributors

Stargazers

Watchers

Forkers

antsibull-docs's Issues

Versions in use

Commands

Output

Workaround

Why I was interested in this

Suggestions

Summary

Issue Type

Component Name

OS / Environment

Code of Conduct

Summary

Issue Type

Component Name

Ansible Version

Configuration

OS / Environment

Steps to Reproduce

Expected Results

Actual Results

Code of Conduct

How to reproduce

Workaround

Recommend Projects

Recommend Topics

Recommend Org