internet/community.general
3
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2026-05-07 13:52:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix Docs build issues (#22295)

Browse Source 
* restore network docs fragments

* Fix RST errors

* code-block formatting
This commit is contained in:
John R Barker
2017-03-05 11:41:29 +00:00
committed by GitHub
parent 6c2585f0c8
commit 3afb67e9b2
11 changed files with 397 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/docsite/rst/dev_guide/developing_modules.rst
View File

@@ -19,30 +19,30 @@ as we work through this tutorial.
See :doc:`../modules` for a list of existing modules.
Modules can be written in any language and are found in the path specified
by :envvar:`ANSIBLE_LIBRARY` or the ``--module-path`` command line option or
in the `library section of the Ansible configration file <http://docs.ansible.com/ansible/intro_configuration.html#library>`_.
by :envvar:`ANSIBLE_LIBRARY` or the ``--module-path`` command line option or
in the `library section of the Ansible configration file <http://docs.ansible.com/ansible/intro_configuration.html#library>`_.
.. _module_dev_should_you:
Should You Develop A Module?
````````````````````````````
Before diving into the work of creating a new module, you should think about whether you actually *should*
Before diving into the work of creating a new module, you should think about whether you actually *should*
develop a module. Ask the following questions:
1. Does a similar module already exist?
1. Does a similar module already exist?
There are a lot of existing modules available, and more that are in development. You should check out the list of existing modules at :doc:`../modules` or look at the `module PRs <https://github.com/ansible/ansible/labels/module>`_ for the ansible repository on Github to see if a module that does what you want exists or is in development.
2. Should you use or develop an action plugin instead?
2. Should you use or develop an action plugin instead?
Action plugins get run on the master instead of on the target. For modules like file/copy/template, some of the work needs to be done on the master before the module executes on the target. Action plugins execute first on the master and can then execute the normal module on the target if necessary.
Action plugins get run on the master instead of on the target. For modules like file/copy/template, some of the work needs to be done on the master before the module executes on the target. Action plugins execute first on the master and can then execute the normal module on the target if necessary.
For more information about action plugins, go `here <https://docs.ansible.com/ansible/dev_guide/developing_plugins.html>`_.
For more information about action plugins, go `here <https://docs.ansible.com/ansible/dev_guide/developing_plugins.html>`_.
3. Should you use a role instead?
Check out the roles documentation `here <http://docs.ansible.com/ansible/playbooks_roles.html#roles>`_.
Check out the roles documentation `here <http://docs.ansible.com/ansible/playbooks_roles.html#roles>`_.
.. _developing_modules_all:

12
docs/docsite/rst/dev_guide/developing_modules_documenting.rst
View File

@@ -35,7 +35,9 @@ ANSIBLE_METADATA Block
ANSIBLE_METADATA contains information about the module for use by other tools. At the moment, it informs other tools which type of maintainer the module has and to what degree users can rely on a module's behaviour remaining the same over time.
For new modules, the following block can be simply added into your module::
For new modules, the following block can be simply added into your module
.. code-block:: python
ANSIBLE_METADATA = {'status': ['preview'],
'supported_by': 'community',
@@ -55,7 +57,7 @@ Version 1.0 of the metadata
Structure
`````````
Format::
.. code-block:: python
ANSIBLE_METADATA = {
'version': '1.0',
@@ -298,11 +300,11 @@ built in the ``docs/docsite/_build/html/$MODULENAME_module.html`` directory.
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:: shell-session
.. 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/your/modules/
source hacking/env-setup
./test/sanity/validate-modules/validate-modules --arg-spec --warnings lib/ansible/modules/your/modules/
.. tip::

9
docs/docsite/rst/dev_guide/developing_modules_in_groups.rst
View File

@@ -3,10 +3,9 @@ Information for submitting a group of modules
.. contents:: Topics
.. _module_dev_welcome:
Submitting a group of modules
`````````````````````````````
Welcome
```````
This section discusses how to get multiple related modules into Ansible.
This document is intended for both companies wishing to add modules for their own products as well as users of 3rd party products wishing to add Ansible functionality.
@@ -60,7 +59,7 @@ Where to get support
Ansible has a thriving and knowledgeable community of module developers that is a great resource for getting your questions answered.
On :doc:`community` you can find how to:
On :doc:`../community` you can find how to:
* Subscribe to the Mailing Lists - We suggest "Ansible Development List" (for codefreeze info) and "Ansible Announce list"
* ``#ansible-devel`` - We have found that IRC ``#ansible-devel`` on FreeNodes IRC network works best for module developers so we can have an interactive dialogue.
@@ -92,7 +91,7 @@ And that's it.
Before pushing your PR to GitHub it's a good idea to review the :doc:`developing_modules_checklist` again.
After publishing your PR to https://github.com/ansible/ansible, a Shippable CI test should run within a few minutes. Check the results (at the end of the PR page) to ensure that it's passing (green). If it's not passing, inspect each of the results. Most of the errors should be self-explanatory and are often related to badly formatted documentation (see :doc:`YAMLSyntax`) or code that isn't valid Python 2.4 & Python 2.6 (see :doc:`developing_modules_python3`). If you aren't sure what a Shippable test message means, copy it into the PR along with a comment and we will review.
After publishing your PR to https://github.com/ansible/ansible, a Shippable CI test should run within a few minutes. Check the results (at the end of the PR page) to ensure that it's passing (green). If it's not passing, inspect each of the results. Most of the errors should be self-explanatory and are often related to badly formatted documentation (see :doc:`../YAMLSyntax`) or code that isn't valid Python 2.4 & Python 2.6 (see :doc:`developing_modules_python3`). If you aren't sure what a Shippable test message means, copy it into the PR along with a comment and we will review.
If you need further advice, consider join the ``#ansible-devel`` IRC channel (see how in the "Where to get support").