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/ansiblerepository.
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.
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
noxusingpython3 -m pip install noxor your distribution's package manager. -
Execute
noxfrom 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 --listto view available sessions.
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/ansiblerepository.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
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
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
codespellsuggests more than one word as a correction.nox -s spelling -- -w -i 3
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.
Use the following nox session to update the dependency lock files in tests/.
nox -s pip-compileTo synchronize dependency lock files with base requirements files without changing transitive dependencies, use the --no-upgrade flag:
nox -s pip-compile -- --no-upgradeThis 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 -s pip-compile'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> tagSee nox -s tag -- --help for extended options.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent