ansible-docs/README.md

ansible-documentation

This repository holds the ReStructuredText (RST) source, and other files, for user documentation related to the Ansible package and Ansible Core.

Documentation for modules and plugins that are officially supported by the Ansible Core engineering team is available in the ansible/ansible repository.

Verifying your pull request

We welcome all contributions to Ansible community documentation. If you plan to submit a pull request with changes, you should verify your PR to ensure it conforms with style guidelines and can build successfully.

Setting up nox

This project includes a nox configuration to automate tests, checks, and other functions. You can use these automated tests to help you verify changes before you submit a PR. You can manually set up your environment if you prefer, but nox is more straightforward and create an isolated environment for you.

• Install nox using python3 -m pip install nox or your distribution's package manager.

• Execute nox from the repository root with no arguments to run all docs checkers, Python code checkers, and a minimal HTML docs build.

• Alternatively, you can run only certain tasks as outlined in the following sections. Run nox --list to view available sessions.

Building docs

The different Makefile targets used to build the documentation are outlined in Building the documentation locally. The nox configuration has a make session that creates a build environment and uses the Makefile to generate HTML.

• Clone required parts of the ansible/ansible repository.

  nox -s clone-core
  

  See Periodically cloning Ansible core for more information.

• Build minimal Ansible Core docs.

  nox -s make
  

• Run a specific Makefile target:

  nox -s make -- clean htmlsingle rst=community/documentation_contributions.rst
  

Running automated tests

The nox configuration also contains session to run automated docs checkers.

• Ensure there are no syntax errors in the reStructuredText source files.

  nox -s "checkers(rstcheck)"
  

  See Running the final tests for more information.

• Verify the docs build.

  nox -s "checkers(docs-build)"
  

  This session cleans the generated docs after it runs. If you want to view the generated HTML in your browser, you should build the documentation locally. See Building the documentation locally for more information.

• Lint, type check, and format Python scripts in this repository and lint the Github Actions workflows for syntax and security issues:

  nox -s lint
  

  The actionlint linter that is run as part of the lint session requires podman or docker to be installed. If both container engines are installed, podman is preferred. Set CONTAINER_ENGINE=docker to change this behavior.

Checking spelling

Use codespell to check for common spelling mistakes in the documentation source.

• Check spelling.

  nox -s spelling
  

• Correct any detected spelling errors.

  nox -s spelling -- -w
  

• Select an option when codespell suggests more than one word as a correction.

  nox -s spelling -- -w -i 3
  

Dependency files

nox sessions use dependencies from requirements files in the tests/ directory. Each session has a tests/{name}.in file with direct dependencies and a lock file in tests/{name}.txt that pins exact versions for both direct and transitive dependencies. The lock files contain tested dependencies that are automatically updated on a weekly basis.

If you'd like to use untested dependencies, set PINNED=false as in the following example:

PINNED=false nox -s "checkers(docs-build)"

For more details about using unpinned and tested dependencies for doc builds, see Setting up your environment to build documentation locally.

Updating dependencies

Use the following nox session to update the dependency lock files in tests/.

nox -s pip-compile

To synchronize dependency lock files with base requirements files without changing transitive dependencies, use the --no-upgrade flag:

nox -s pip-compile -- --no-upgrade

To upgrade a single dependency, for instance when adjusting constraints on a package, use the --upgrade-package flag followed by the package name:

nox -s pip-compile -- --upgrade-package <package_name>

Creating release tags

When a tag is created in the ansible/ansible repository for a release or release candidate, a corresponding tag should be created in this ansible-documentation repository.

First, ensure that you have the ansible/ansible and ansible/ansible-documentation repositories checked out. The tool assumes that both checkouts have the same parent directory. You can set different paths to your checkouts with the --docs and --core options if you have them set up another way.

Next, run the tag nox session.

This will determine any missing ansible-core tags and create them in ansible-documentation if needed, exiting normally otherwise:

# The tagger scripts assumes "origin" as the upstream remote.
nox -s tag

# If you use a different upstream remote, specify the name.
nox -s tag -- --remote <name> tag

# If your core repo is not in the same filesystem location, specify the path.
nox -s tag -- --core <path> tag

See nox -s tag -- --help for extended options.