From 198c9a5903b839f1de815831662c908cb743591b Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Fri, 4 Oct 2013 10:41:44 -0400 Subject: [PATCH] Adding some labels so we don't get "#id22" for the links in the docs. --- docsite/latest/rst/developing_api.rst | 4 +++ docsite/latest/rst/developing_inventory.rst | 4 +++ docsite/latest/rst/developing_modules.rst | 29 ++++++++++++++++++++- 3 files changed, 36 insertions(+), 1 deletion(-) diff --git a/docsite/latest/rst/developing_api.rst b/docsite/latest/rst/developing_api.rst index 3fd7d628484..9b1d253b6cf 100644 --- a/docsite/latest/rst/developing_api.rst +++ b/docsite/latest/rst/developing_api.rst @@ -9,6 +9,8 @@ API so you have a considerable amount of power across the board. This chapter d .. contents:: `Table of contents` :depth: 2 +.. _python_api: + Python API ---------- @@ -43,6 +45,8 @@ expressed in the 'ansible-modules' documentation.:: A module can return any type of JSON data it wants, so Ansible can be used as a framework to rapidly build powerful applications and scripts. +.. _detailed_api_example: + Detailed API Example ```````````````````` diff --git a/docsite/latest/rst/developing_inventory.rst b/docsite/latest/rst/developing_inventory.rst index f7da62a7396..1905b3d8b88 100644 --- a/docsite/latest/rst/developing_inventory.rst +++ b/docsite/latest/rst/developing_inventory.rst @@ -8,6 +8,8 @@ How do we write a new one? Simple! We just create a script or program that can return JSON in the right format when fed the proper arguments. You can do this in any language. +.. _inventory_script_conventions: + Script Conventions `````````````````` @@ -46,6 +48,8 @@ if the script does not wish to do this, returning an empty hash/dictionary is th "monitoring" : "pack.example.com" } +.. _inventory_script_tuning: + Tuning the External Inventory Script ```````````````````````````````````` diff --git a/docsite/latest/rst/developing_modules.rst b/docsite/latest/rst/developing_modules.rst index e8b1a75179d..0a294b36312 100644 --- a/docsite/latest/rst/developing_modules.rst +++ b/docsite/latest/rst/developing_modules.rst @@ -11,8 +11,11 @@ by `ANSIBLE_LIBRARY` or the ``--module-path`` command line option. :depth: 2 +.. _module_dev_tutorial: + Tutorial ```````` + Let's build a module to get and set the system time. For starters, let's build a module that just outputs the current time. @@ -45,6 +48,8 @@ Ok, let's get going with an example. We'll use Python. For starters, save this "time" : date }) +.. _module_testing: + Testing Modules ``````````````` @@ -63,6 +68,8 @@ You should see output that looks something like this:: If you did not, you might have a typo in your module, so recheck it and try again. +.. _reading_input: + Reading Input ````````````` @@ -176,6 +183,8 @@ This should return something like:: {"changed": true, "time": "2012-03-14 12:23:00.000307"} +.. _module_provided_facts: + Module Provided 'Facts' ``````````````````````` @@ -199,6 +208,8 @@ These 'facts' will be available to all statements called after that module (but A good idea might be make a module called 'site_facts' and always call it at the top of each playbook, though we're always open to improving the selection of core facts in Ansible as well. +.. _common_module_boilerplate: + Common Module Boilerplate ````````````````````````` @@ -248,6 +259,8 @@ can function outside of Ansible. If submitting a module to ansible's core code, which we encourage, use of the AnsibleModule class is required. +.. _developing_for_check_mode: + Check Mode `````````` .. versionadded:: 1.1 @@ -274,6 +287,8 @@ system state is altered when the user enables check mode. If your module does not support check mode, when the user runs Ansible in check mode, your module will simply be skipped. +.. _module_dev_pitfalls: + Common Pitfalls ``````````````` @@ -295,6 +310,8 @@ will still be shown in Ansible, but the command will not succeed. Always use the hacking/test-module script when developing modules and it will warn you about these kind of things. +.. _module_dev_conventions: + Conventions/Recommendations ``````````````````````````` @@ -321,6 +338,8 @@ and guidelines: * As results from many hosts will be aggregrated at once, modules should return only relevant output. Returning the entire contents of a log file is generally bad form. +.. _module_dev_shorthand: + Shorthand Vs JSON ````````````````` @@ -334,6 +353,7 @@ will know what to do:: If you're writing a module in Python or Ruby or whatever, though, returning JSON is probably the simplest way to go. +.. _module_documenting: Documenting Your Module ``````````````````````` @@ -344,6 +364,8 @@ which conforms to the schema defined below. You may find it easier to start writing your ``DOCUMENTATION`` string in an editor with YAML syntax highlighting before you include it in your Python file. +.. _module_doc_example: + Example +++++++ @@ -384,6 +406,8 @@ The ``module_formatter.py`` script and ``ansible-doc(1)`` append the ``EXAMPLES`` blob after any existing (deprecated) ``examples`` you may have in the YAML ``DOCUMENTATION`` string. +.. _module_dev_testing: + Building & Testing ++++++++++++++++++ @@ -418,6 +442,8 @@ output formats available: You can use ANSIBLE_KEEP_REMOTE_FILES=1 to prevent ansible from deleting the remote files so you can debug your module. +.. _module_contribution: + Getting Your Module Into Core ````````````````````````````` @@ -425,7 +451,8 @@ High-quality modules with minimal dependencies can be included in the core, but core modules (just due to the programming preferences of the developers) will need to be implemented in Python and use the AnsibleModule common code, and should generally use consistent arguments with the rest of -the program. Stop by the mailing list to inquire about requirements. +the program. Stop by the mailing list to inquire about requirements if you like, and submit +a github pull request to the main project. .. seealso::