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
12
README.rst
12
README.rst
@@ -7,17 +7,9 @@ Team and repository tags
|
|||||||
|
|
||||||
.. Change things from this point on
|
.. Change things from this point on
|
||||||
|
|
||||||
===============================
|
=============================
|
||||||
sphinx-feature-classification
|
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
|
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
|
contains and which features they support. The directive takes an INI file with
|
||||||
|
|||||||
0
doc/source/conf.py
Executable file → Normal file
0
doc/source/conf.py
Executable file → Normal file
@@ -1,4 +0,0 @@
|
|||||||
============
|
|
||||||
Contributing
|
|
||||||
============
|
|
||||||
.. include:: ../../CONTRIBUTING.rst
|
|
||||||
5
doc/source/contributor/index.rst
Normal file
5
doc/source/contributor/index.rst
Normal file
@@ -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.
|
sphinx-feature-classification
|
||||||
You can adapt this file completely to your liking, but it should at least
|
=============================
|
||||||
contain the root `toctree` directive.
|
|
||||||
|
|
||||||
Welcome to sphinx-feature-classification's documentation!
|
.. include:: ../../README.rst
|
||||||
=========================================================
|
:start-line: 9
|
||||||
|
:end-line: -4
|
||||||
Contents:
|
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
|
||||||
|
|
||||||
readme
|
|
||||||
installation
|
|
||||||
usage
|
|
||||||
contributing
|
|
||||||
|
|
||||||
Indices and tables
|
|
||||||
==================
|
|
||||||
|
|
||||||
* :ref:`genindex`
|
|
||||||
* :ref:`modindex`
|
|
||||||
* :ref:`search`
|
|
||||||
|
|
||||||
|
contributor/index
|
||||||
|
install/index
|
||||||
|
user/index
|
||||||
|
|||||||
7
doc/source/install/index.rst
Normal file
7
doc/source/install/index.rst
Normal file
@@ -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. |
|
|
||||||
+---------------+------------------------------------------------------+
|
|
||||||
216
doc/source/user/index.rst
Normal file
216
doc/source/user/index.rst
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user