Rework sushy documentation for doc migration

Also, edited docstrings in one of the source code files
as they were generating errors for sphinx with autodoc
which was not previously enabled.

Depends-On: Ie380d2a38e9ca62b8f8f4e2ed1c40f5d717348ee
Change-Id: I77ef3dee7ae4d94e40fa01f80937ae7aa06c8204

.gitignore

@@ -44,6 +44,7 @@ output/*/index.html
 
 # Sphinx
 doc/build
+doc/source/reference/api
 
 # pbr generates these
 AUTHORS
@@ -55,4 +56,4 @@ ChangeLog
 .*sw?
 
 # Files created by releasenotes build
-releasenotes/build
+releasenotes/build

README.rst

@@ -1,6 +1,5 @@
-=====
-Sushy
-=====
+About Sushy
+===========
 
 Sushy is a Python library to communicate with `Redfish`_ based systems.
 
@@ -14,9 +13,9 @@ project. As the project grows and more features from `Redfish`_ are
 needed we can expand Sushy to fullfil those requirements.
 
 * Free software: Apache license
-* Documentation: http://sushy.rtfd.io
-* Usage: http://sushy.readthedocs.io/en/latest/usage.html
-* Source: http://git.openstack.org/cgit/openstack/sushy
-* Bugs: http://bugs.launchpad.net/sushy
+* Documentation: https://docs.openstack.org/sushy/latest/
+* Usage: https://docs.openstack.org/sushy/latest/reference/usage.html
+* Source: https://git.openstack.org/cgit/openstack/sushy
+* Bugs: https://bugs.launchpad.net/sushy
 
 .. _Redfish: http://www.dmtf.org/standards/redfish

doc/source/contributor/index.rst

@@ -1,9 +1,12 @@
 .. _contributing:
 
-============
-Contributing
-============
-.. include:: ../../CONTRIBUTING.rst
+=====================
+Contributing to Sushy
+=====================
+
+How to contribute
+=================
+.. include:: ../../../CONTRIBUTING.rst
 
 
 Running a Redfish emulator

doc/source/index.rst

@@ -3,23 +3,20 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+=================================
 Welcome to Sushy's documentation!
 =================================
 
-Contents:
+.. include:: ../../README.rst
+
+Documentation
+=============
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   About Sushy <readme>
-   installation
-   usage
-   contributing
-
-Indices and tables
-==================
+   install/index
+   contributor/index
+   reference/index
 
 * :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

doc/source/install/index.rst

@@ -1,6 +1,6 @@
-============
-Installation
-============
+================
+Installing Sushy
+================
 
 At the command line::
 

doc/source/reference/index.rst

@@ -1,7 +1,9 @@
-.. include:: ../../README.rst
+=======================
+Sushy Library Reference
+=======================
 
 Features
---------
+========
 
 * Abstraction around the SystemCollection and System resources (Basic
   server identification and asset information)
@@ -9,11 +11,27 @@ Features
 * Changing systems boot device, frequency (Once or permanently) and mode
   (UEFI or BIOS)
 
-Check out the :ref:`usage` page.
+.. toctree::
+   :maxdepth: 2
 
-TODO
-----
+   usage
+
+Missing Features
+================
+
+These are some features that sushy is presently missing.
 
 * Collect sensor data (Health state, temperature, fans etc...)
 * System inspection (Number of CPUs, memory and disk size)
 * Serial console
+
+Sushy Python API Reference
+==========================
+
+* :ref:`modindex`
+
+.. # api/autoindex is hidden since it's in the modindex link above.
+.. toctree::
+  :hidden:
+
+  api/autoindex

doc/source/reference/usage.rst

@@ -1,8 +1,7 @@
 ..  _usage:
 
-=====
-Usage
-=====
+Usaging Sushy
+=============
 
 To use sushy in a project:
 

setup.cfg

@@ -49,3 +49,9 @@ output_file = sushy/locale/sushy.pot
 all_files = 1
 build-dir = releasenotes/build
 source-dir = releasenotes/source
+
+[pbr]
+autodoc_index_modules = True
+api_doc_dir = reference/api
+autodoc_exclude_modules =
+    sushy.tests.*

sushy/resources/system/processor.py

@@ -77,10 +77,7 @@ class ProcessorCollection(base.ResourceCollectionBase):
         return Processor
 
     _summary = None
-    """The summary of processors of the system in general detail
-
-    This has to be accessed by exposed :prop:`summary`.
-    """
+    """The summary of processors of the system in general detail"""
 
     @property
     def summary(self):
@@ -88,10 +85,9 @@ class ProcessorCollection(base.ResourceCollectionBase):
 
         It is calculated once when the first time it is queried. On refresh,
         this property gets reset.
-        :returns: A namedtuple containing the following:
-            count: The number of processors in the system. To be precise,
-                   it returns the number of logical CPUs (threads).
-            architecture: The architecture of the processor/s.
+
+        :returns: A namedtuple containing the ``count`` of processors
+            in regards to logical CPUs, and their ``architecture``.
         """
         if self._summary is None:
             count, architecture = 0, None