diff --git a/README.rst b/README.rst index a9240a5..7c3ab20 100644 --- a/README.rst +++ b/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 diff --git a/doc/source/conf.py b/doc/source/conf.py old mode 100755 new mode 100644 diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst deleted file mode 100644 index 1728a61..0000000 --- a/doc/source/contributing.rst +++ /dev/null @@ -1,4 +0,0 @@ -============ -Contributing -============ -.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 0000000..3d4ceb4 --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,5 @@ +============ +Contributing +============ + +.. include:: ../../../CONTRIBUTING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index de02f50..60dbc42 100644 --- a/doc/source/index.rst +++ b/doc/source/index.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 diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 0000000..0323ebb --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,7 @@ +============ +Installation +============ + +At the command line:: + + $ pip install sphinx-feature-classification diff --git a/doc/source/installation.rst b/doc/source/installation.rst deleted file mode 100644 index 481219b..0000000 --- a/doc/source/installation.rst +++ /dev/null @@ -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 diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3..0000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst diff --git a/doc/source/usage.rst b/doc/source/usage.rst deleted file mode 100644 index b628927..0000000 --- a/doc/source/usage.rst +++ /dev/null @@ -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 - 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 - 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. | -+---------------+------------------------------------------------------+ diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 0000000..957f3ec --- /dev/null +++ b/doc/source/user/index.rst @@ -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 + 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 + 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 + 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 + driver.slow-driver=complete + driver.fast-driver=complete