a-c-m
/
community.general
mirror of https://github.com/ansible-collections/community.general.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docsite: correct path, list requirements for testing module docs, etc. (#52008) 

* dev_guide: correct path, list requirements, etc.; module HTML docs are in '_build/html/module' subdir
pull/4420/head
Mark Zhitomirski 2019-05-01 23:19:03 +03:00 committed by Alicia Cozine
parent 3161a91d7e
commit b14f477bee
1 changed files with 20 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/docsite/rst/dev_guide/testing_documentation.rst
View File

@ -10,17 +10,27 @@ Before you submit a module for inclusion in the main Ansible repo, you must test
To check the HTML output of your module 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``. #. Ensure working :ref:`development environment <environment_setup>`.
#. Move to the docsite directory: ``cd /path/to/ansible/docs/docsite/``. #. Install required Python packages (drop '--user' in venv/virtualenv):
#. 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``. .. code-block:: bash
To ensure that your documentation matches your ``argument_spec``, run the ``validate-modules`` test. pip install --user -r requirements.txt
pip install --user -r docs/docsite/requirements.txt
.. code-block:: bash #. Ensure your module is in the correct directory: ``lib/ansible/modules/$CATEGORY/mymodule.py``.
#. Build HTML from your module documentation: ``MODULES=mymodule make webdocs``.
#. To build the HTML documentation for multiple modules, use a comma-separated list of module names: ``MODULES=mymodule,mymodule2 make webdocs``.
#. View the HTML page at ``file:///path/to/docs/docsite/_build/html/modules/mymodule_module.html``.
# If you don't already, ensure you are using your local checkout To ensure that your module documentation matches your ``argument_spec``:
source hacking/env-setup
./test/sanity/validate-modules/validate-modules --arg-spec --warnings lib/ansible/modules/$CATEGORY/my_code.py #. Install required Python packages (drop '--user' in venv/virtualenv):
.. code-block:: bash
pip install --user -r test/runner/requirements/sanity.txt
#. run the ``validate-modules`` test::
./test/sanity/validate-modules/validate-modules --arg-spec --warnings lib/ansible/modules/$CATEGORY/mymodule.py