4264be2b18
* orphans testing pages to avoid not-in-toctree errors * orphans various pages pending reorg * adds module_utils and special_vars to main TOC * uses a glob for scenario_guide TOC * normalize and Sentence-case headings on community pages, typos * re-orgs community TOC, adds all pages to toctree * removes scenario guides index page * adds style guide to community index * basic update to style guide * fix typo that created a new error * removes not-in-toctree from ignore errors list * leave removing files for future cleanup task
26 lines
1.3 KiB
ReStructuredText
26 lines
1.3 KiB
ReStructuredText
:orphan:
|
|
|
|
.. _testing_documentation:
|
|
|
|
*********************
|
|
Testing documentation
|
|
*********************
|
|
|
|
Before you submit a module for inclusion in the main Ansible repo, you must test your documentation for correct HTML rendering and to ensure that the argspec matches the documentation.
|
|
|
|
To check the HTML output of your module documentation:
|
|
|
|
#. Save your completed module file into the correct directory: ``lib/ansible/modules/$CATEGORY/my_code.py``.
|
|
#. Move to the docsite directory: ``cd /path/to/ansible/docs/docsite/``.
|
|
#. Run the command to build the docs for your module: ``MODULES=my_code make webdocs``.
|
|
#. View the HTML page at ``file:///path/to/ansible/docs/docsite/_build/html/my_code_module.html``.
|
|
|
|
To build the HTML documentation for multiple modules, use a comma-separated list of module names: ``MODULES=my_code,my_other_code make webdocs``.
|
|
|
|
To ensure that your documentation matches your ``argument_spec``, run the ``validate-modules`` test. Note that this option isn't currently enabled in Shippable due to the time it takes to run.
|
|
|
|
.. code-block:: bash
|
|
|
|
# If you don't already, ensure you are using your local checkout
|
|
source hacking/env-setup
|
|
./test/sanity/validate-modules/validate-modules --arg-spec --warnings lib/ansible/modules/$CATEGORY/my_code.py
|