From 6f4f7011f126cf80e59e2928b5b6d2f03b3da147 Mon Sep 17 00:00:00 2001 From: Dylan Silva Date: Mon, 8 May 2017 09:08:55 -0700 Subject: [PATCH] Updates to docs for developers (#24034) - Added items to index for TOC - Changed some formatting on overview_architecture - removed some out of date items from developing_modules_general --- .../rst/dev_guide/developing_modules_general.rst | 9 +++------ docs/docsite/rst/dev_guide/index.rst | 16 +++++++++++----- .../rst/dev_guide/overview_architecture.rst | 9 +++------ 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_modules_general.rst b/docs/docsite/rst/dev_guide/developing_modules_general.rst index f8e9c76a4c..edc029a5c6 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general.rst @@ -23,7 +23,7 @@ modules. Keep in mind, though, that some modules in Ansible's source tree are 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` +Ok, let's get going with an example. We're going to use Python. For starters, save this as a file named :file:`timetest.py` .. code-block:: python @@ -46,7 +46,7 @@ There's a useful test script in the source checkout for Ansible: .. code-block:: shell-session - git clone git://github.com/ansible/ansible.git --recursive + git clone git://github.com/ansible/ansible.git source ansible/hacking/env-setup For instructions on setting up Ansible from source, please see @@ -230,7 +230,7 @@ this, just have the module return a `ansible_facts` key, like so, along with oth These 'facts' will be available to all statements called after that module (but not before) in the playbook. A good idea might be to 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. - + Returning a new fact from a python module could be done like:: module.exit_json(msg=message, ansible_facts=dict(leptons=5000, colors=my_colors)) @@ -331,6 +331,3 @@ 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. - - - diff --git a/docs/docsite/rst/dev_guide/index.rst b/docs/docsite/rst/dev_guide/index.rst index b96871b8de..4b24f64256 100644 --- a/docs/docsite/rst/dev_guide/index.rst +++ b/docs/docsite/rst/dev_guide/index.rst @@ -17,16 +17,22 @@ To get started, select one of the following topics. overview_architecture developing_modules - testing - developing_python3 + developing_modules_general + developing_modules_documenting + developing_modules_best_practices + developing_modules_checklist + developing_modules_in_groups + developing_program_flow_modules + developing_module_utilities developing_plugins developing_inventory - developing_api - developing_module_utilities developing_core + developing_python3 + developing_api + developing_test_pr developing_rebasing + testing repomerge developing_releases ../committer_guidelines ./style_guide/index - diff --git a/docs/docsite/rst/dev_guide/overview_architecture.rst b/docs/docsite/rst/dev_guide/overview_architecture.rst index 882e0a5ab7..f315d55540 100644 --- a/docs/docsite/rst/dev_guide/overview_architecture.rst +++ b/docs/docsite/rst/dev_guide/overview_architecture.rst @@ -16,14 +16,14 @@ Ansible works by connecting to your nodes and pushing out small programs, called Your library of modules can reside on any machine, and there are no servers, daemons, or databases required. Typically you'll work with your favorite terminal program, a text editor, and probably a version control system to keep track of changes to your content. Plugins -------- +`````````````````` Plugins are pieces of code that augment Ansible's core functionality. Ansible ships with a number of handy plugins, and you can easily write your own. Inventory ```````````````````` -By default, Ansible represents what machines it manages using a very simple INI file that puts all of your managed machines in groups of your own choosing. +By default, Ansible represents what machines it manages using a very simple INI file that puts all of your managed machines in groups of your own choosing. To add new machines, there is no additional SSL signing server involved, so there's never any hassle deciding why a particular machine didn’t get linked up due to obscure NTP or DNS issues. @@ -51,7 +51,7 @@ Playbooks can finely orchestrate multiple slices of your infrastructure topology Ansible's approach to orchestration is one of finely-tuned simplicity, as we believe your automation code should make perfect sense to you years down the road and there should be very little to remember about special syntax or features. -Here's what a simple playbook looks like:: +Here's what a simple playbook looks like:: --- - hosts: webservers @@ -70,6 +70,3 @@ Extending Ansible with Plug-ins and the API ```````````````````````````````````````````` Should you want to write your own, Ansible modules can be written in any language that can return JSON (Ruby, Python, bash, etc). Inventory can also plug in to any datasource by writing a program that speaks to that datasource and returns JSON. There's also various Python APIs for extending Ansible’s connection types (SSH is not the only transport possible), callbacks (how Ansible logs, etc), and even for adding new server side behaviors. - - -