From 8a754e0858d922e955e71b253c139e071ecec432 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 28 Apr 2024 18:04:21 +0200 Subject: Adding upstream version 2.14.3. Signed-off-by: Daniel Baumann --- .../dev_guide/documenting_modules_network.rst | 52 ++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 docs/docsite/rst/network/dev_guide/documenting_modules_network.rst (limited to 'docs/docsite/rst/network/dev_guide/documenting_modules_network.rst') 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 0000000..99ba7a9 --- /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_.rst`` (for example, ``platform_myos.rst``). The platform name should match the module prefix. See `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. -- cgit v1.2.3