Improved documentation structure (#165)

* Improved documentation structure Details: * Made list of modules a TOC so that it shows up in the left hand menu. * Renamed common_return_values.rst to return_values.rst because it now applies to just this collection specifically intead of being common. (it has not been updated yet). * Renamed list_of_all_modules.rst to all_modules.rst for consistency with the section title inside of the file. * Updated copyright dates in conf.py. * Changed attributes of toctree in index.rst. * Removed duplicated CONTRIBUTING.rst file in main directory; it also exists in docs/sources. * Removed duplicate inclusion of CONTRIBUTING.rst into development.rst because it is already included at the top level into index.rst. Signed-off-by: Andreas Maier <maiera@de.ibm.com> * Removed page with common return values Details: * The common return values page was inherited from the prior docs approach, and makes sense for Ansible built-in modules. However, the zhmc Ansibe modules do not need any of the common return types and decribe all of their return values on the module pages. Therefore, this change removes the common return values page. Signed-off-by: Andreas Maier <maiera@de.ibm.com>
zhmcclient · Oct 23, 2020 · f5c7879 · f5c7879
1 parent 1332fc2
commit f5c7879
Show file tree

Hide file tree

Showing 8 changed files with 33 additions and 261 deletions.
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
diff --git a/docs/source/all_modules.rst b/docs/source/all_modules.rst
@@ -0,0 +1,19 @@
+.. _all_modules:
+
+All modules
+-----------
+
+.. toctree::
+   :maxdepth: 1
+
+   modules/zhmc_adapter
+   modules/zhmc_cpc
+   modules/zhmc_crypto_attachment
+   modules/zhmc_hba
+   modules/zhmc_nic
+   modules/zhmc_partition
+   modules/zhmc_storage_group
+   modules/zhmc_storage_group_attachment
+   modules/zhmc_storage_volume
+   modules/zhmc_user
+   modules/zhmc_virtual_function
diff --git a/docs/source/changes.rst b/docs/source/changes.rst
@@ -75,6 +75,12 @@ Released: not yet
   machine generation. This makes the 'mac_address' property writeable, and adds
   the 'vlan_type', 'function_number' and 'function_range' properties.
 
+**Cleanup:**
+
+* Removed the page describing common return values, because all return values
+  are specifically described on the module pages without referencing any
+  common return value type.
+
 **Known issues:**
 
 * See `list of open issues`_.

diff --git a/docs/source/common_return_values.rst b/docs/source/common_return_values.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -17,8 +17,8 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'zhmc Ansible modules'
-copyright = '2020, IBM'
+project = 'ibm.zhmc Ansible modules'
+copyright = '2016-2020, IBM'
 author = 'IBM'
 
 # The full version, including alpha/beta/rc tags

diff --git a/docs/source/development.rst b/docs/source/development.rst
@@ -115,11 +115,6 @@ its ``-k`` option. Invoke ``py.test --help`` for details on the expression
 syntax of its ``-k`` option.
 
 
-.. _`Contributing`:
-
-.. include:: CONTRIBUTING.rst
-
-
 .. _`Releasing a version`:
 
 Releasing a version

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,24 +1,18 @@
-.. zhmc Ansible modules documentation master file, created by
-   sphinx-quickstart on Sat Oct  3 14:54:45 2020.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
-Welcome to zhmc Ansible modules's documentation!
-================================================
+ibm.zhmc Ansible modules
+========================
 
 .. toctree::
-   :maxdepth: 1
-   :caption: Ansible Contents:
-   :glob:
+   :maxdepth: 2
+   :name: mastertoc
 
    intro
-   list_of_all_modules
-   common_return_values
+   all_modules
    modules_support
    development
+   CONTRIBUTING
    appendix
    changes
-   CONTRIBUTING  
 
 Indices and tables
 ==================

diff --git a/docs/source/list_of_all_modules.rst b/docs/source/list_of_all_modules.rst