1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
=====
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.
``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``
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``. While this is optional, it is highly recommended for implementations
in the ``partial`` state.
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>
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``.
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>
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
|
