From 7765bd41e62f3bd93ddfa64b726b98128c8f668b Mon Sep 17 00:00:00 2001
From: Sandra McCann <samccann@redhat.com>
Date: Tue, 18 Jun 2019 16:35:09 -0400
Subject: [PATCH] add platform docs to network dev guide (#57960)

* add info on how to create platform docs to network dev guide
---
 docs/docsite/rst/dev_guide/index.rst          |  1 +
 .../dev_guide/documenting_modules_network.rst | 52 +++++++++++++++++++
 docs/docsite/rst/network/dev_guide/index.rst  |  4 ++
 3 files changed, 57 insertions(+)
 create mode 100644 docs/docsite/rst/network/dev_guide/documenting_modules_network.rst

diff --git a/docs/docsite/rst/dev_guide/index.rst b/docs/docsite/rst/dev_guide/index.rst
index 57565740fc6..645bc4fba5f 100644
--- a/docs/docsite/rst/dev_guide/index.rst
+++ b/docs/docsite/rst/dev_guide/index.rst
@@ -35,6 +35,7 @@ Find the task that best describes what you want to do:
    * I want to :ref:`debug my module code <debugging>`.
    * I want to :ref:`add tests <developing_testing>`.
    * I want to :ref:`document my module <module_documenting>`.
+   * I want to :ref:`document my set of modules for a network platform <documenting_modules_network>`.
    * I want to follow :ref:`conventions and tips for clean, usable module code <developing_modules_best_practices>`.
    * I want to :ref:`make sure my code runs on Python 2 and Python 3 <developing_python_3>`.
 
diff --git a/docs/docsite/rst/network/dev_guide/documenting_modules_network.rst b/docs/docsite/rst/network/dev_guide/documenting_modules_network.rst
new file mode 100644
index 00000000000..78c88b37643
--- /dev/null
+++ b/docs/docsite/rst/network/dev_guide/documenting_modules_network.rst
@@ -0,0 +1,52 @@
+
+.. _documenting_modules_network:
+
+*********************************
+Documenting new network platforms
+*********************************
+
+.. contents::
+  :local:
+
+When you create network modules for a new platform, or modify the connections provided by an existing network platform(such as ``network_cli`` and ``httpapi``), you also need to update  the :ref:`settings_by_platform` table and add or modify the Platform Options file for your platform.
+
+You should already have documented each module as described in :ref:`developing_modules_documenting`.
+
+Modifying the platform options table
+====================================
+
+The :ref:`settings_by_platform` table is a convenient summary of the connections options provided by each network platform that has modules in Ansible. Add a row for your platform to this table, in alphabetical order.  For example:
+
+.. code-block:: text
+
+    +-------------------+-------------------------+-------------+---------+---------+----------+
+    | My OS             | ``myos``                | ✓           | ✓       |         | ✓        |
+
+Ensure that the table stays formatted correctly. That is:
+
+* Each row is inserted in alphabetical order.
+* The cell division ``|`` markers line up with the ``+`` markers.
+* The check marks appear only for the connection types provided by the network modules.
+
+
+
+Adding a platform-specific options section
+==========================================
+
+The platform- specific sections are individual ``.rst`` files that provide more detailed information for the users of your network platform modules.   Name your new file ``platform_<name>.rst`` (for example, ``platform_myos.rst``).  The platform name should match the module prefix. See `platform_eos.rst <https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/network/user_guide/platform_eos.rst>`_ and :ref:`eos_platform_options` for an example of the details you should provide in your platform-specific options section.
+
+Your platform-specific section should include the following:
+
+* **Connections available table** - a deeper dive into each connection type, including details on credentials, indirect access, connections settings, and enable mode.
+* **How to use each connection type** - with working examples of each connection type.
+
+If your network platform supports SSH connections, also include the following at the bottom of your ``.rst`` file:
+
+.. code-block:: text
+
+    .. include:: shared_snippets/SSH_warning.txt
+
+Adding your new file to the table of contents
+=============================================
+
+As a final step, add your new file in alphabetical order in the ``platform_index.rst`` file. You should then build the documentation to verify your additions. See :ref:`community_documentation_contributions` for more details.
diff --git a/docs/docsite/rst/network/dev_guide/index.rst b/docs/docsite/rst/network/dev_guide/index.rst
index b4e74607f12..eb702f635b6 100644
--- a/docs/docsite/rst/network/dev_guide/index.rst
+++ b/docs/docsite/rst/network/dev_guide/index.rst
@@ -19,8 +19,12 @@ If you want to extend Ansible for Network Automation by creating a module or plu
 Find the network developer task that best describes what you want to do:
 
    * I want to :ref:`develop a network connection plugin <developing_plugins_network>`.
+   * I want to :ref:`document my set of modules for a network platform <documenting_modules_network>`.
+
+If you prefer to read the entire guide, here's a list of the pages in order.
 
 .. toctree::
   :maxdepth: 1
 
   developing_plugins_network
+  documenting_modules_network