From b7aa38c0d8507506903bc886e6d6cd30e646ff42 Mon Sep 17 00:00:00 2001 From: Sam Doran Date: Wed, 16 Aug 2017 20:56:53 -0400 Subject: [PATCH] Minor fixes to Developer Docs (#28302) * Grammar and formatting corrections Indent JSON code example. Double backticks for inline code examples. * Remove trailing spaces * CI fixes --- .../developing_modules_documenting.rst | 8 +++-- .../dev_guide/developing_modules_general.rst | 33 ++++++++++--------- 2 files changed, 22 insertions(+), 19 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index fb494a1887c..500f34cbaaa 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -96,7 +96,7 @@ Version 1.1 of the metadata +++++++++++++++++++++++++++ Structure -````````` +^^^^^^^^^ .. code-block:: python @@ -107,7 +107,7 @@ Structure } Fields -`````` +^^^^^^ :metadata_version: An “X.Y” formatted string. X and Y are integers which define the metadata format version. Modules shipped with Ansible are @@ -399,13 +399,15 @@ Put your completed module file into the ``lib/ansible/modules/$CATEGORY/`` direc run the command: ``make webdocs``. The new 'modules.html' file will be built in the ``docs/docsite/_build/html/$MODULENAME_module.html`` directory. -In order to speed up the build process, you can limit the documentation build to +In order to speed up the build process, you can limit the documentation build to only include modules you specify, or no modules at all. To do this, run the command: ``MODULES=$MODULENAME make webdocs``. The ``MODULES`` environment variable accepts a comma-separated list of module names. To skip building documentation for all modules, specify a non-existent module name, for example: ``MODULES=none make webdocs``. +You may also build a single page of the entire docsite. From ``ansible/docs/docsite`` run ``make htmlsingle rst=[relative path to the .rst file]``, for example: ``make htmlsingle rst=dev_guide/developing_modules_documenting.rst`` + To test your documentation against your ``argument_spec`` you can use ``validate-modules``. Note that this option isn't currently enabled in Shippable due to the time it takes to run. .. code-block:: bash diff --git a/docs/docsite/rst/dev_guide/developing_modules_general.rst b/docs/docsite/rst/dev_guide/developing_modules_general.rst index 1ddb6faee1c..1d5667776c3 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general.rst @@ -4,7 +4,7 @@ Ansible Module Development Walkthrough ====================================== -In this section, we will walk through developing, testing, and debugging an Ansible module. +In this section, we will walk through developing, testing, and debugging an Ansible module. What's covered in this section: @@ -51,7 +51,9 @@ working on a whole new file. Here is an example: - Navigate to the directory that you want to develop your new module in. E.g. ``$ cd lib/ansible/modules/cloud/azure/`` - Create your new module file: ``$ touch my_new_test_module.py`` -- Paste this simple into the new module file: (explanation in comments):: +- Paste this example code into the new module file: (explanation in comments) + +.. code:: python #!/usr/bin/python @@ -187,14 +189,14 @@ that can run locally. - Create an arguments file in ``/tmp/args.json`` with the following content: (explanation below) - .. code:: json +.. code:: json - { - "ANSIBLE_MODULE_ARGS": { - "name": "hello", - "new": true - } - } + { + "ANSIBLE_MODULE_ARGS": { + "name": "hello", + "new": true + } + } - If you are using a virtual environment (highly recommended for development) activate it: ``$ . venv/bin/activate`` @@ -205,7 +207,7 @@ that can run locally. This should be working output that resembles something like the following: -:: +.. code:: json {"changed": true, "state": {"original_message": "hello", "new_message": "goodbye"}, "invocation": {"module_args": {"name": "hello", "new": true}}} @@ -221,7 +223,6 @@ Ansible playbook. - Create a playbook in any directory: ``$ touch testmod.yml`` - Add the following to the new playbook file:: - --- - name: test my new module connection: local hosts: localhost @@ -238,11 +239,11 @@ Ansible playbook. - Run the playbook and analyze the output: ``$ ansible-playbook ./testmod.yml`` Debugging (local) -================= +================= If you want to break into a module and step through with the debugger, locally running the module you can do: -- Set a breakpoint in the module: `import pdb; pdb.set_trace()` +- Set a breakpoint in the module: ``import pdb; pdb.set_trace()`` - Run the module on the local machine: ``$ python -m pdb ./my_new_test_module.py ./args.json`` Debugging (remote) @@ -282,7 +283,7 @@ Going Further If you are starting new development or fixing a bug, create a new branch: -``$ git checkout -b my-new-branch``. +``$ git checkout -b my-new-branch``. If you are planning on contributing back to the main Ansible repository, fork the Ansible repository into @@ -293,7 +294,7 @@ submit a pull request to the Ansible repository. If you want to submit a new module to the upstream Ansible repo, be sure to run through sanity checks first. For example: -``$ ansible-test sanity -v --docker --python 2.7 MODULE_NAME`` +``$ ansible-test sanity -v --docker --python 2.7 MODULE_NAME`` Note that this example requires docker to be installed and running. If you'd rather not use a container for this, you can choose to use ``--tox`` instead of ``--docker``. @@ -311,5 +312,5 @@ use the ``#ansible`` channel. Credit ====== -Thank you to Thomas Stringer (`@tstring `_) for contributing source +Thank you to Thomas Stringer (`@tstring `_) for contributing source material for this topic.