We have already put a great deal of work into documenting our module, as we discussed earlier in this chapter. However, how can we see it, and how can we check that it compiles correctly into the HTML that would go on the Ansible website if it were accepted as part of the Ansible source code?
Before we get into actually viewing our documentation, we should make use of a tool called ansible-test, which was newly added in the 2.9 release. This tool can perform a sanity check on our module code to ensure that our documentation meets all the standards required by the Ansible project team and that the code is structured correctly (for example, the Python import statements should always come after the documentation blocks). Let's get started:
- To run the sanity tests, assuming you have cloned the official repository, change into this directory and set up your environment. Note that if your standard Python binary isn't Python 3, the ansible-test tool will not run, so you should ensure Python 3 is installed and, if necessary, set up a virtual environment to ensure you are using Python 3. This can be done as follows:
$ cd ansible$ python 3 -m venv venv
$ . venv/bin/activate
(venv) $ source hacking/env-setup
running egg_info
creating lib/ansible.egg-info
writing lib/ansible.egg-info/PKG-INFO
writing dependency_links to lib/ansible.egg-info/dependency_links.txt
writing requirements to lib/ansible.egg-info/requires.txt
writing top-level names to lib/ansible.egg-info/top_level.txt
writing manifest file 'lib/ansible.egg-info/SOURCES.txt'
reading manifest file 'lib/ansible.egg-info/SOURCES.txt'
reading manifest template 'MANIFEST.in'
warning: no files found matching 'SYMLINK_CACHE.json'
writing manifest file 'lib/ansible.egg-info/SOURCES.txt'
Setting up Ansible to run out of checkout...
PATH=/home/james/ansible/bin:/home/james/ansible/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/home/james/bin
PYTHONPATH=/home/james/ansible/lib
MANPATH=/home/james/ansible/docs/man:/usr/local/share/man:/usr/share/man
Remember, you may wish to specify your host file with -i
Done!
- Next, use pip to install the Python requirements so that you can run the ansible-test tool:
(venv) $ pip install -r test/runner/requirements/sanity.txt
- Now, provided you have copied your module code into the appropriate location in the source tree (an example copy command is shown here), you can run the sanity tests as follows:
(venv) $ cp ~/moduledev/remote_filecopy.py ./lib/ansible/modules/files/
(venv) $ ansible-test sanity --test validate-modules remote_filecopy
Sanity check using validate-modules
WARNING: Cannot perform module comparison against the base branch. Base branch not detected when running locally.
WARNING: Reviewing previous 1 warning(s):
WARNING: Cannot perform module comparison against the base branch. Base branch not detected when running locally.
From the preceding output, you can see that apart from one warning related to us not having a base branch to compare against, the module code that we developed earlier in this chapter has passed all the tests. If you had an issue with the documentation (for example, the author name format was incorrect), this would be given as an error.
Now that we have passed the sanity checks with ansible-test, let's see whether the documentation looks right by using the ansible-doc command. This is very easy to do. First of all, exit your virtual environment, if you are still in it, and change to the Ansible source code directory you cloned from GitHub earlier. Now, you can manually tell ansible-doc where to look for modules instead of the default path. This means that you could run the following:
$ cd ~/ansible
$ ansible-doc -M moduledev/ remote_filecopy
You should be presented with the textual rendering of the documentation we created earlier – an example of the first page is shown here to give you an idea of how it should look:
> REMOTE_FILECOPY (/home/james/ansible/moduledev/remote_filecopy.py)
The remote_copy module copies a file on the remote host from a
given source to a provided destination.
* This module is maintained by The Ansible Community
OPTIONS (= is mandatory):
= dest
Path to the destination on the remote host for the copy
= source
Path to a file on the source file on the remote host
Excellent! So, we can already access our module documentation using ansible-doc and indeed confirm that it renders correctly in text mode. However, how do we go about building the HTML version? Fortunately, there is a well-defined process for this, which we shall outline here:
- Under lib/ansible/modules/, you will find a series of categorized directories that modules are placed under – ours fits best under the files category, so copy it to this location in preparation for the build process to come:
$ cp moduledev/remote_filecopy.py lib/ansible/modules/files/
- Change to the docs/docsite/ directory as the next step in the documentation creation process:
$ cd docs/docsite/
- Build a documentation-based Python file. Use the following command to do so:
$ MODULES=hello_module make webdocs
Now, in theory, making the Ansible documentation should be this simple; however, unfortunately, at the time of writing, the source code for Ansible v2.9.6 refuses to build webdocs. This will no doubt be fixed in due course as, at the time of writing, the documentation build scripts are being ported to Python 3. To get the make webdocs command to run at all, I had to clone the source code for Ansible v2.8.10 as a starting point.
Even in this environment, on CentOS 7, the make webdocs command fails unless you have some very specific Python 3 requirements in place. These are not well-documented, but from testing, I can tell you that Sphinx v2.4.4 works. The version supplied with CentOS 7 is too old and fails, while the newest version available from the Python module repositories (v3.0.1, at the time of writing) is not compatible with the build process and fails.
Once I'd started working from the Ansible v2.8.10 source tree, I had to make sure I had removed any preexisting sphinx modules from my Python 3 environment (you need Python 3.5 or above to build the documentation locally – if you don't have this installed on your node, please do this before proceeding) and then ran the following commands:
$ pip3 uninstall sphinx
$ pip3 install sphinx==2.4.4
$ pip3 install sphinx-notfound-page
With this in place, you will be able to successfully run make webdocs to build your documentation. You will see pages of output. A successful run should end with something like the output shown here:
generating indices... genindex py-modindexdone
writing additional pages... search/home/james/ansible/docs/docsite/_themes/sphinx_rtd_theme/search.html:21: RemovedInSphinx30Warning: To modify script_files in the theme is deprecated. Please insert a <script> tag directly in your theme instead.
{% endblock %}
opensearchdone
copying images... [100%] dev_guide/style_guide/images/thenvsthan.jpg
copying downloadable files... [ 50%] network/getting_started/sample_files/first_copying downloadable files... [100%] network/getting_started/sample_files/first_playbook_ext.yml
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 35 warnings.
The HTML pages are in _build/html.
make[1]: Leaving directory `/home/james/ansible/docs/docsite'Now, notice how, at the end of this process, the make command tells us where to look for the compiled documentation. If you look in here, you will find the following:
$ find /home/james/ansible/docs/docsite -name remote_filecopy*
/home/james/ansible/docs/docsite/rst/modules/remote_filecopy_module.rst
/home/james/ansible/docs/docsite/_build/html/modules/remote_filecopy_module.html
/home/james/ansible/docs/docsite/_build/doctrees/modules/remote_filecopy_module.doctree
Try opening up the HTML file in your web browser – you should see that the page renders just like one of the documentation pages from the official Ansible project documentation! This enables you to check that your documentation builds correctly and looks and reads well in the context that it will be viewed in. It also gives you confidence that, when you submit your code to the Ansible project (if you are doing so), you are submitting something consistent with Ansible's documentation quality standards.
The current process of building the documentation is currently a little fussy around the environments that are supported; however, hopefully, this is something that will be resolved in due course. In the meantime, the process outlined in this section has given you a tested and working process to start from.