mirror of https://github.com/ansible/ansible-documentation.git synced 2026-03-27 13:28:51 +07:00

Files

Don Naro 5a74e2f0eb README: document new nox sessions

Co-authored-by: Maxwell G <maxwell@gtmx.me>

2023-10-26 02:12:35 +00:00

3.7 KiB

Raw Blame History

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.

Building Ansible community documentation

Follow the documentation to set up your environment and then build Ansible community documentation locally

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.

Running automated tests

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.

Install nox using python3 -m pip install nox or your distribution's package manager.
Run nox --list from the repository root to view available sessions.

Each nox session creates a temporary environment that installs all requirements and runs the test or check. This means you only need to run one command to perform the test accurately and consistently. The following are some of the nox sessions you can run:

Run all available sessions.
```
nox
```
Clone required parts of the ansible/ansible repository.
```
nox -s clone-core
```
See Periodically cloning Ansible core for more information.
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
```

Updating dependencies

Use the following nox session to update project dependency versions.

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'

3.7 KiB Raw Blame History