To use the extension, add 'sphinx_feature_classification.support_matrix'
to
the extensions
list in the conf.py
file in your Sphinx project.
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.
.. support_matrix:: support-matrix.ini
See below for more details on the format of this file.
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 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:
[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 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
optional
choice(group)
condition
notes
Mandatory: | No |
---|
Additional information about the feature.
cli
Mandatory: | No |
---|
A sample CLI command that can be used to utilize the feature.
api
Mandatory: | No |
---|
The alias for this feature in the API.
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
partial
missing
driver-notes.XXX
Mandatory: | No |
---|
Additional information about the implementation of this feature in driver
XXX
. While this is optional, it is highly recommended for implementations
in the partial
state.
For example:
[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>
api=volume-attach
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>
api=volume-detach
driver.slow-driver=complete
driver-notes.slow-driver=Works without issue if instance is off. When
hotplugging, requires version foo of the driver.
driver.fast-driver=complete
Notice that a driver is only required to implement detach-volume if they
completed implementing attach-volume
.
This is simply the combined example from above.
[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>
api=volume-attach
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>
api=volume-detach
driver.slow-driver=complete
driver-notes.slow-driver=Works without issue if instance is off. When
hotplugging, requires version foo of the driver.
driver.fast-driver=complete
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.