Ansible has a lot of documentation and a small team of writers. Community support helps us keep up with new features, fixes, and changes.
Improving the documentation is an easy way to make your first contribution to the Ansible project. You don’t have to be a programmer, since our documentation is written in YAML (module documentation) or reStructuredText (rST). If you’re using Ansible, you already use YAML in your playbooks. And rST is mostly just text. You don’t even need git experience, if you use the
Edit on GitHub option.
If you find a typo, a broken example, a missing topic, or any other error or omission on this documentation website, let us know. Here are some ways to support Ansible documentation:
For typos and other quick fixes, you can edit the documentation right from the site. Look at the top right corner of this page. That
Edit on GitHub link is available on every page in the documentation. If you have a GitHub account, you can submit a quick and easy pull request this way.
To submit a documentation PR from docs.ansible.com with
Edit on GitHub:
Edit on GitHub.
Propose file changeat the bottom of the GitHub page. The more specific, the better. For example, “fixes typo in my_module description”. You can put more detail in the second rectangle if you like. Leave the
Create pull requestto open the PR template.
Issue Typesection, delete all lines except the
Docs Pull Requestline.
Create pull requestbutton.
If the problem you’ve noticed is too complex to fix with the
Edit on GitHub option, and no open issue or PR already documents the problem, please open an issue and/or a PR on the
A great documentation GitHub issue or PR includes:
If you make multiple changes to the documentation, or add more than a line to it, before you open a pull request, please:
To work with documentation on your local machine, you need to have python-3.5 or greater and the following packages installed:
On macOS with Xcode, you may need to install
--ignore-installed to get versions that work wth
To test an individual file for rST errors:
Building the documentation is the best way to check for errors and review your changes. Once rstcheck runs with no errors, navigate to
ansible/docs/docsite and then build the page(s) you want to review.
To build a single rST file with the make utility:
make htmlsingle rst=path/to/your_file.rst
make htmlsingle rst=community/documentation_contributions.rst
This process compiles all the links but provides minimal log output. If you’re writing a new page or want more detailed log output, refer to the instructions on Building rST files with sphinx-build
make htmlsingle adds
rst/ to the beginning of the path you provide in
rst=, so you can’t type the filename with autocomplete. Here are the error messages you will see if you get this wrong:
- If you run
make htmlsinglefrom the
make: *** No rule to make target `htmlsingle'. Stop.
- If you run
make htmlsinglefrom the
docs/docsite/directory with the full path to your rST document:
sphinx-build: error: cannot find files ['rst/rst/community/documentation_contributions.rst'].
To build all the rST files without any module documentation:
MODULES=none make webdocs
To build documentation for a few modules plus all the rST files, use a comma-separated list:
MODULES=one_module,another_module make webdocs
To build all the module documentation plus all the rST files:
Advanced users can build one or more rST files with the sphinx utility directly.
sphinx-build returns misleading
undefined label warnings if you only build a single page, because it does not create internal links. However,
sphinx-build returns more extensive syntax feedback, including warnings about indentation errors and
x-string without end-string warnings. This can be useful, especially if you’re creating a new page from scratch. To build a page or pages with
sphinx-build [options] sourcedir outdir [filenames...]
You can specify filenames, or
–a for all files, or omit both to compile only new/changed files.
sphinx-build -b html -c rst/ rst/dev_guide/ _build/html/dev_guide/ rst/dev_guide/developing_modules_documenting.rst
When you submit a documentation pull request, automated tests are run. Those same tests can be run locally. To do so, navigate to the repository’s top directory and run:
make clean && bin/ansible-test sanity --test docs-build && bin/ansible-test sanity --test rstcheck
Unfortunately, leftover rST-files from previous document-generating can occasionally confuse these tests. It is therefore safest to run them on a clean copy of the repository, which is the purpose of
make clean. If you type these three lines one at a time and manually check the success of each, you do not need the