doc: Rework everything
Basically rewrite all the documentation. The usage guide is significantly improved, adding a detailed comparison of drivers, features and implementations and examples for how this can actually be used as a directive (something that wasn't at all obvious at first glance). We also take the opportunity to change the new-style documentation layout. Change-Id: I7fcd49f580450e74f716fc5b388e5370deca4b04 Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane
parent
34e2fddbdd
commit
4f5ab257c2
12
README.rst
12
README.rst
|
|
@ -7,17 +7,9 @@ Team and repository tags
|
|||
|
||||
.. Change things from this point on
|
||||
|
||||
===============================
|
||||
=============================
|
||||
sphinx-feature-classification
|
||||
===============================
|
||||
|
||||
.. image:: https://img.shields.io/pypi/v/oslo.db.svg
|
||||
:target: https://pypi.org/project/oslo.db/
|
||||
:alt: Latest Version
|
||||
|
||||
.. image:: https://img.shields.io/pypi/dm/oslo.db.svg
|
||||
:target: https://pypi.org/project/oslo.db/
|
||||
:alt: Downloads
|
||||
=============================
|
||||
|
||||
This is a Sphinx directive that allows creating matrices of drivers a project
|
||||
contains and which features they support. The directive takes an INI file with
|
||||
|
|
|
|||
|
|
@ -1,4 +0,0 @@
|
|||
============
|
||||
Contributing
|
||||
============
|
||||
.. include:: ../../CONTRIBUTING.rst
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
============
|
||||
Contributing
|
||||
============
|
||||
|
||||
.. include:: ../../../CONTRIBUTING.rst
|
||||
|
|
@ -1,25 +1,13 @@
|
|||
.. sphinx-feature-classification documentation master file, created by
|
||||
sphinx-quickstart on Tue Jul 9 22:26:36 2013.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
=============================
|
||||
sphinx-feature-classification
|
||||
=============================
|
||||
|
||||
Welcome to sphinx-feature-classification's documentation!
|
||||
=========================================================
|
||||
|
||||
Contents:
|
||||
.. include:: ../../README.rst
|
||||
:start-line: 9
|
||||
:end-line: -4
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
readme
|
||||
installation
|
||||
usage
|
||||
contributing
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
||||
contributor/index
|
||||
install/index
|
||||
user/index
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
At the command line::
|
||||
|
||||
$ pip install sphinx-feature-classification
|
||||
|
|
@ -1,12 +0,0 @@
|
|||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
At the command line::
|
||||
|
||||
$ pip install sphinx-feature-classification
|
||||
|
||||
Or, if you have virtualenvwrapper installed::
|
||||
|
||||
$ mkvirtualenv sphinx-feature-classification
|
||||
$ pip install sphinx-feature-classification
|
||||
|
|
@ -1 +0,0 @@
|
|||
.. include:: ../../README.rst
|
||||
|
|
@ -1,92 +0,0 @@
|
|||
========
|
||||
Usage
|
||||
========
|
||||
|
||||
Sphinx Configuration
|
||||
====================
|
||||
|
||||
To use the extension, add ``'sphinx_feature_classification.support_matrix'`` to
|
||||
the ``extensions`` list in the ``conf.py`` file in your Sphinx project.
|
||||
|
||||
Documenting Your Drivers
|
||||
========================
|
||||
|
||||
1. This extension uses an ini file to render your driver matrix in Sphinx. You
|
||||
can begin by creating the file support-matrix.ini file in your sphinx's
|
||||
source directory.
|
||||
|
||||
2. In the INI file, create driver sections that are prefixed with driver-. The
|
||||
section has various options that can be specified.
|
||||
|
||||
+------------+-----------+---------------------------------------+
|
||||
| Field Name | Mandatory | Description |
|
||||
+============+===========+=======================================+
|
||||
| title | **Yes** | Friendly name of the driver. |
|
||||
+------------+-----------+---------------------------------------+
|
||||
| link | No | A link to documentation of the driver.|
|
||||
+------------+-----------+---------------------------------------+
|
||||
|
||||
.. code-block:: INI
|
||||
|
||||
[driver.slow-driver]
|
||||
title=Slow Driver
|
||||
link=https://docs.openstack.org/foo/latest/some-slow-driver-doc
|
||||
|
||||
[driver.fast-driver]
|
||||
title=Fast Driver
|
||||
link=https://docs.openstack.org/foo/latest/some-fast-driver-doc
|
||||
|
||||
|
||||
3. Next we'll create a couple of feature sections to show which drivers support
|
||||
them. Notice that a driver is only required to implement detach-volume if
|
||||
they completed implementing attach-volume.
|
||||
|
||||
.. code-block:: INI
|
||||
|
||||
[operation.attach-volume]
|
||||
title=Attach block volume to instance
|
||||
status=optional
|
||||
notes=The attach volume operation provides a means to hotplug
|
||||
additional block storage to a running instance.
|
||||
cli=my-project attach-volume <instance> <volume>
|
||||
driver.slow-driver=complete
|
||||
driver.fast-driver=complete
|
||||
|
||||
[operation.detach-volume]
|
||||
title=Detach block volume from instance
|
||||
status=condition(operation.attach-volume==complete)
|
||||
notes=The detach volume operation provides a means to remove additional block
|
||||
storage from a running instance.
|
||||
cli=my-project detach-volume <instance> <volume>
|
||||
driver.slow-driver=complete
|
||||
driver.fast-driver=complete
|
||||
|
||||
The 'status' field takes possible values
|
||||
|
||||
+---------------+------------------------------------------------------+
|
||||
| Status | Description |
|
||||
+===============+======================================================+
|
||||
| mandatory | Unconditionally required to be implemented. |
|
||||
+---------------+------------------------------------------------------+
|
||||
| optional | Optional to support, nice to have. |
|
||||
+---------------+------------------------------------------------------+
|
||||
| choice(group) | At least one of the options within the named group |
|
||||
| | must be implemented. |
|
||||
+---------------+------------------------------------------------------+
|
||||
| condition | Required, if the referenced condition is met. |
|
||||
+---------------+------------------------------------------------------+
|
||||
|
||||
The value against each 'driver-XXXX' entry refers to the level
|
||||
of the implementation of the feature in that driver
|
||||
|
||||
+---------------+------------------------------------------------------+
|
||||
| Status | Description |
|
||||
+===============+======================================================+
|
||||
| complete | Fully implemented, expected to work at all times. |
|
||||
+---------------+------------------------------------------------------+
|
||||
| partial | Implemented, but with caveats about when it will |
|
||||
| | work eg some configurations or hardware or guest OS |
|
||||
| | may not support it. |
|
||||
+---------------+------------------------------------------------------+
|
||||
| missing | Not implemented at all. |
|
||||
+---------------+------------------------------------------------------+
|
||||
|
|
@ -0,0 +1,216 @@
|
|||
=====
|
||||
Usage
|
||||
=====
|
||||
|
||||
Sphinx Configuration
|
||||
--------------------
|
||||
|
||||
To use the extension, add ``'sphinx_feature_classification.support_matrix'`` to
|
||||
the ``extensions`` list in the ``conf.py`` file in your Sphinx project.
|
||||
|
||||
.. code-block:: python
|
||||
:caption: conf.py
|
||||
|
||||
extensions = [
|
||||
'sphinx_feature_classification.support_matrix',
|
||||
# ... other extensions
|
||||
]
|
||||
|
||||
Once added, include the ``support_matrix`` directive in your chosen document.
|
||||
The directive takes a single argument: a relative path to the INI file in which
|
||||
the driver matrix is defined.
|
||||
|
||||
.. code-block:: rst
|
||||
:caption: support-matrix.rst
|
||||
|
||||
.. support_matrix:: support-matrix.ini
|
||||
|
||||
See below for more details on the format of this file.
|
||||
|
||||
|
||||
Drivers vs. Features vs. Implementations
|
||||
----------------------------------------
|
||||
|
||||
Drivers
|
||||
Drivers are *backends* that are used to implement a set of features. What a
|
||||
driver actually is depends entirely on the project being documented. For a
|
||||
project like OpenStack Compute (nova), this could be a virtualization driver
|
||||
(*libvirt*, *Hyper-V*, *PowerVM*, etc.). For a project like OpenStack
|
||||
Storage, this could be a block storage driver (*LVM*, *NFS*, *RBD*, etc.). It
|
||||
is entirely project-specific.
|
||||
|
||||
Features
|
||||
Features are more clear cut. Features are something that your project should
|
||||
support (or *must* support). For a project like OpenStack Compute (nova),
|
||||
this could be the ability to restart an instance. For a project like
|
||||
OpenStack Storage (cinder), this could be the ability to create a snapshot of
|
||||
a volume.
|
||||
|
||||
Implementation
|
||||
Implementations refer to the state of a feature within a given driver. As not
|
||||
all features are required, not all drivers may implement them.
|
||||
|
||||
|
||||
Documenting Your Drivers
|
||||
------------------------
|
||||
|
||||
This extension uses an INI file to render your driver matrix in Sphinx. For
|
||||
example, you may wish to call this file ``support-matrix.ini``. This file
|
||||
should be placed somewhere within your Sphinx source directory. Within the INI
|
||||
file, there are multiple sections.
|
||||
|
||||
Driver Sections
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Driver sections are prefixed with ``driver.``. You can specify as many of them
|
||||
as you need for your project. The section has various options that can be
|
||||
specified.
|
||||
|
||||
``title``
|
||||
:Mandatory: **Yes**
|
||||
|
||||
Friendly name of the driver.
|
||||
|
||||
``link``
|
||||
:Mandatory: No
|
||||
|
||||
A link to documentation of the driver.
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: INI
|
||||
:caption: support-matrix.ini
|
||||
|
||||
[driver.slow-driver]
|
||||
title=Slow Driver
|
||||
link=https://docs.openstack.org/foo/latest/some-slow-driver-doc
|
||||
|
||||
[driver.fast-driver]
|
||||
title=Fast Driver
|
||||
link=https://docs.openstack.org/foo/latest/some-fast-driver-doc
|
||||
|
||||
Feature Sections
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Feature sections are prefixed with ``operation.``. As with driver sections, you
|
||||
can specify as many of them as you need for your project. These sections are
|
||||
also used to describe the feature and indicate the implementation status of the
|
||||
feature among the various drivers, as seen below. These sections have the
|
||||
following options:
|
||||
|
||||
``title``
|
||||
:Mandatory: **Yes**
|
||||
|
||||
Friendly name of the feature.
|
||||
|
||||
``status``
|
||||
:Mandatory: **Yes**
|
||||
|
||||
The importance of the feature or whether it's required. One of:
|
||||
|
||||
``mandatory``
|
||||
Unconditionally required to be implemented.
|
||||
|
||||
``optional``
|
||||
Optional to support; nice to have.
|
||||
|
||||
``choice(group)``
|
||||
At least one of the options within the named group must be implemented.
|
||||
|
||||
``condition``
|
||||
Required, if the referenced condition is met.
|
||||
|
||||
``notes``
|
||||
:Mandatory: No
|
||||
|
||||
Additional information about the feature.
|
||||
|
||||
``cli``
|
||||
:Mandatory: No
|
||||
|
||||
A sample CLI command that can be used to utilize the feature.
|
||||
|
||||
In addition, there are some driver specific options that should be repeated
|
||||
for every driver defined earlier in the file.
|
||||
|
||||
``driver.XXX``
|
||||
:Mandatory: **Yes** (for each driver)
|
||||
|
||||
The level of implementation of this feature in driver ``XXX``. One of:
|
||||
|
||||
``complete``
|
||||
Fully implemented, expected to work at all times.
|
||||
|
||||
``partial``
|
||||
Implemented, but with caveats about when it will work. For example, some
|
||||
configurations, hardware or guest OS' may not support it.
|
||||
|
||||
``missing``
|
||||
Not implemented at all.
|
||||
|
||||
``driver-notes.XXX``
|
||||
:Mandatory: No
|
||||
|
||||
Additional information about the implementation of this feature in driver
|
||||
``XXX``.
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: INI
|
||||
:caption: support-matrix.ini
|
||||
|
||||
[operation.attach-volume]
|
||||
title=Attach block volume to instance
|
||||
status=optional
|
||||
notes=The attach volume operation provides a means to hotplug additional
|
||||
block storage to a running instance.
|
||||
cli=my-project attach-volume <instance> <volume>
|
||||
driver.slow-driver=complete
|
||||
driver.fast-driver=complete
|
||||
|
||||
[operation.detach-volume]
|
||||
title=Detach block volume from instance
|
||||
status=condition(operation.attach-volume==complete)
|
||||
notes=The detach volume operation provides a means to remove additional
|
||||
block storage from a running instance.
|
||||
cli=my-project detach-volume <instance> <volume>
|
||||
driver.slow-driver=complete
|
||||
driver.fast-driver=complete
|
||||
|
||||
Notice that a driver is only required to implement detach-volume if they
|
||||
completed implementing ``attach-volume``.
|
||||
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
This is simply the combined example from above.
|
||||
|
||||
.. code-block:: INI
|
||||
:caption: support-matrix.ini
|
||||
|
||||
[driver.slow-driver]
|
||||
title=Slow Driver
|
||||
link=https://docs.openstack.org/foo/latest/some-slow-driver-doc
|
||||
|
||||
[driver.fast-driver]
|
||||
title=Fast Driver
|
||||
link=https://docs.openstack.org/foo/latest/some-fast-driver-doc
|
||||
|
||||
[operation.attach-volume]
|
||||
title=Attach block volume to instance
|
||||
status=optional
|
||||
notes=The attach volume operation provides a means to hotplug additional
|
||||
block storage to a running instance.
|
||||
cli=my-project attach-volume <instance> <volume>
|
||||
driver.slow-driver=complete
|
||||
driver.fast-driver=complete
|
||||
|
||||
[operation.detach-volume]
|
||||
title=Detach block volume from instance
|
||||
status=condition(operation.attach-volume==complete)
|
||||
notes=The detach volume operation provides a means to remove additional
|
||||
block storage from a running instance.
|
||||
cli=my-project detach-volume <instance> <volume>
|
||||
driver.slow-driver=complete
|
||||
driver.fast-driver=complete
|
||||
Loading…
Reference in New Issue