diff --git a/.gitignore b/.gitignore index 963e589a..82d3306d 100644 --- a/.gitignore +++ b/.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 \ No newline at end of file +releasenotes/build diff --git a/README.rst b/README.rst index 51a5a484..c4046804 100644 --- a/README.rst +++ b/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 diff --git a/doc/source/contributing.rst b/doc/source/contributor/index.rst similarity index 95% rename from doc/source/contributing.rst rename to doc/source/contributor/index.rst index 219b02c8..bb0c76e1 100644 --- a/doc/source/contributing.rst +++ b/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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 111f9317..86810b03 100644 --- a/doc/source/index.rst +++ b/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 - installation - usage - contributing - -Indices and tables -================== + install/index + contributor/index + reference/index * :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/doc/source/installation.rst b/doc/source/install/index.rst similarity index 73% rename from doc/source/installation.rst rename to doc/source/install/index.rst index 6857cf8d..e230886e 100644 --- a/doc/source/installation.rst +++ b/doc/source/install/index.rst @@ -1,6 +1,6 @@ -============ -Installation -============ +================ +Installing Sushy +================ At the command line:: diff --git a/doc/source/readme.rst b/doc/source/reference/index.rst similarity index 52% rename from doc/source/readme.rst rename to doc/source/reference/index.rst index 78ea95d6..a0259edf 100644 --- a/doc/source/readme.rst +++ b/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 diff --git a/doc/source/usage.rst b/doc/source/reference/usage.rst similarity index 99% rename from doc/source/usage.rst rename to doc/source/reference/usage.rst index a0973a09..8de18177 100644 --- a/doc/source/usage.rst +++ b/doc/source/reference/usage.rst @@ -1,8 +1,7 @@ .. _usage: -===== -Usage -===== +Usaging Sushy +============= To use sushy in a project: diff --git a/setup.cfg b/setup.cfg index 6c4dd618..f71245d3 100644 --- a/setup.cfg +++ b/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.* diff --git a/sushy/resources/system/processor.py b/sushy/resources/system/processor.py index 36c3b1b4..72fa416c 100644 --- a/sushy/resources/system/processor.py +++ b/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