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 the nox configuration significantly simplifies this process.

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 to automate setting up a docs build environment and running the Makefile.

Clone required parts of the ansible/ansible repository.
```
nox -s clone-core
```
See Periodically cloning Ansible core for more information.
Run a minimal Ansible Core docs build.
```
nox -s make
```

Run a specific Makefile target with options

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.
```
nox -s lint
```

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 -e pip-compile

This session requires Python 3.10.

If you do not have Python 3.10 installed, you can use root-less podman with a Python 3.10 image as follows:

podman run --rm --tty --volume "$(pwd):/mnt:z" --workdir /mnt docker.io/library/python:3.10 bash -c 'pip install nox ; nox -e pip-compile'

4.9 KiB Raw Blame History