From 4f7a0925fda2d9ea9b0e9f41b21420055468622d Mon Sep 17 00:00:00 2001 From: Toshio Kuratomi Date: Wed, 4 May 2016 12:17:42 -0700 Subject: [PATCH] Corrections to documentation formatting --- docsite/rst/developing_core.rst | 24 +++++++++++++++++++ docsite/rst/developing_modules.rst | 14 +++++------ .../rst/developing_program_flow_modules.rst | 6 ++--- docsite/rst/faq.rst | 2 +- docsite/rst/guide_azure.rst | 1 + 5 files changed, 36 insertions(+), 11 deletions(-) create mode 100644 docsite/rst/developing_core.rst diff --git a/docsite/rst/developing_core.rst b/docsite/rst/developing_core.rst new file mode 100644 index 00000000000..c0067d74f86 --- /dev/null +++ b/docsite/rst/developing_core.rst @@ -0,0 +1,24 @@ +Developing the Ansible Core Engine +================================== + +Although many of the pieces of the Ansible Core Engine are plugins that can be +swapped out via playbook directives or configuration, there are still pieces +of the Engine that are not modular. The documents here give insight into how +those pieces work together. + +.. toctree:: + :maxdepth: 1 + + developing_program_flow_modules + +.. seealso:: + + :doc:`developing_api` + Learn about the Python API for task execution + :doc:`developing_plugins` + Learn about developing plugins + `Mailing List `_ + The development mailing list + `irc.freenode.net `_ + #ansible-devel IRC chat channel + diff --git a/docsite/rst/developing_modules.rst b/docsite/rst/developing_modules.rst index 89ca9b978e9..d1a2cdf44ca 100644 --- a/docsite/rst/developing_modules.rst +++ b/docsite/rst/developing_modules.rst @@ -48,8 +48,8 @@ the 'command' module could already be used to do this. Reading the modules that come with Ansible (linked above) is a great way to learn how to write modules. Keep in mind, though, that some modules in Ansible's source tree are internalisms, -so look at :ref:`service` or :ref:`yum`, and don't stare too close into things like :ref:`async_wrapper` or -you'll turn to stone. Nobody ever executes :ref:`async_wrapper` directly. +so look at :ref:`service` or :ref:`yum`, and don't stare too close into things like ``async_wrapper`` or +you'll turn to stone. Nobody ever executes ``async_wrapper`` directly. Ok, let's get going with an example. We'll use Python. For starters, save this as a file named :file:`timetest.py`:: @@ -538,11 +538,11 @@ When you look into the debug_dir you'll see a directory structure like this:: that are passed to the module, this is the file to do it in. * The :file:`ansible` directory contains code from - :module:`ansible.module_utils` that is used by the module. Ansible includes + :mod:`ansible.module_utils` that is used by the module. Ansible includes files for any :`module:`ansible.module_utils` imports in the module but not no files from any other module. So if your module uses - :module:`ansible.module_utils.url` Ansible will include it for you, but if - your module includes :module:`requests` then you'll have to make sure that + :mod:`ansible.module_utils.url` Ansible will include it for you, but if + your module includes :mod:`requests` then you'll have to make sure that the python requests library is installed on the system before running the module. You can modify files in this directory if you suspect that the module is having a problem in some of this boilerplate code rather than in @@ -566,7 +566,7 @@ module file and test that the real module works via :command:`ansible` or The wrapper provides one more subcommand, ``excommunicate``. This subcommand is very similar to ``execute`` in that it invokes the exploded module on the arguments in the :file:`args`. The way it does this is - different, however. ``excommunicate`` imports the :function:`main` + different, however. ``excommunicate`` imports the :func:`main` function from the module and then calls that. This makes excommunicate execute the module in the wrapper's process. This may be useful for running the module under some graphical debuggers but it is very different @@ -575,7 +575,7 @@ module file and test that the real module works via :command:`ansible` or with Ansible normally. Those are not bugs in the module; they're limitations of ``excommunicate``. Use at your own risk. -.. _module_paths +.. _module_paths: Module Paths ```````````` diff --git a/docsite/rst/developing_program_flow_modules.rst b/docsite/rst/developing_program_flow_modules.rst index c4f821231e4..3bedeaf122f 100644 --- a/docsite/rst/developing_program_flow_modules.rst +++ b/docsite/rst/developing_program_flow_modules.rst @@ -79,7 +79,7 @@ New-style powershell modules use the :ref:`module_replacer` framework for constructing modules. These modules get a library of powershell code embedded in them before being sent to the managed node. -.. _flow_josnargs_modules: +.. _flow_jsonargs_modules: JSONARGS ^^^^^^^^ @@ -325,7 +325,7 @@ string and substituted into the combined module file. In :ref:`ziploader`, the JSON-ified string is passed into the module via stdin. When a :class:`ansible.module_utils.basic.AnsibleModule` is instantiated, it parses this string and places the args into -:attribute:`AnsibleModule.params` where it can be accessed by the module's +:attr:`AnsibleModule.params` where it can be accessed by the module's other code. .. _flow_passing_module_constants: @@ -357,7 +357,7 @@ For now, :code:`ANSIBLE_VERSION` is also available at its old location inside of :ref:`ziploader` passes these as part of the JSON-ified argument string via stdin. When :class:`ansible.module_utils.basic.AnsibleModule` is instantiated, it parses this -string and places the constants into :attribute:`AnsibleModule.constants` +string and places the constants into :attr:`AnsibleModule.constants` where other code can access it. Unlike the ``ANSIBLE_VERSION``, where some efforts were made to keep the old diff --git a/docsite/rst/faq.rst b/docsite/rst/faq.rst index b0d1846dfc5..cd0f191e782 100644 --- a/docsite/rst/faq.rst +++ b/docsite/rst/faq.rst @@ -329,7 +329,7 @@ be applied to single tasks only, once a playbook is completed. .. _interpolate_variables: When should I use {{ }}? Also, how to interpolate variables or dynamic variable names -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ A steadfast rule is 'always use {{ }} except when `when:`'. Conditionals are always run through Jinja2 as to resolve the expression, diff --git a/docsite/rst/guide_azure.rst b/docsite/rst/guide_azure.rst index c5c11a88301..de47a5b7de0 100644 --- a/docsite/rst/guide_azure.rst +++ b/docsite/rst/guide_azure.rst @@ -332,6 +332,7 @@ A sample azure_rm.ini file is included along with the inventory script in contri file will contain the following: .. code-block:: ini + [azure] # Control which resource groups are included. By default all resources groups are included. # Set resource_groups to a comma separated list of resource groups names.