Merge "Rework sushy documentation for doc migration"

.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