List traits in documentation

We're going to have to switch to something other than a list of strings
or use Sphinx-style inline documentation if we want to provide anything
more useful.

Change-Id: I45c29fe2bdd3fdcb3c69e07f5e9e5be36de9b797
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>

.gitignore

@@ -11,3 +11,6 @@ build/
 /ChangeLog
 /RELEASENOTES.rst
 /releasenotes/notes/reno.cache
+
+# dynamically generated documentation
+doc/source/reference/traits.rst

doc/ext/traits.py

@@ -0,0 +1,52 @@
+# Copyright 2020, Red Hat, Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""Generate a listing of all known traits."""
+
+import os
+
+import os_traits
+
+REFERENCE_DIR = os.path.join(
+    os.path.dirname(os.path.abspath(__file__)), os.pardir, 'source',
+    'reference',
+)
+
+
+def _generate_trait_list():
+    yield 'Available Traits'
+    yield '================'
+    yield ''
+    yield 'Below is a list of all traits currently available.'
+    yield ''
+
+    for trait in os_traits.get_traits():
+        yield f'- ``{trait}``'
+
+    yield ''
+
+
+def generate_trait_list(app):
+    """Generate a listing of all known traits."""
+    with open(os.path.join(REFERENCE_DIR, 'traits.rst'), 'w+') as fh:
+        for line in _generate_trait_list():
+            print(line, file=fh)
+
+
+def setup(app):
+    app.connect('builder-inited', generate_trait_list)
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

doc/source/conf.py

@@ -11,6 +11,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import os
+import sys
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('../'))
+
 # -- General configuration ----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -18,6 +26,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'openstackdocstheme',
+    'ext.traits',
 ]
 
 # openstackdocstheme options
@@ -33,8 +42,8 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'os-traits'
-copyright = u'2016, OpenStack Foundation'
+project = 'os-traits'
+copyright = '2016-2020, OpenStack Foundation'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True

doc/source/index.rst

@@ -40,3 +40,4 @@ Reference
    :maxdepth: 2
 
    reference/index
+   reference/traits

os_traits/hw/gpu/cuda.py

@@ -12,6 +12,63 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
+"""
+CUDA
+----
+
+Applications that need to perform massively parallel operations, like
+processing large arrays, may use the CUDA framework to accelerate their
+processing on graphics processing units (GPUs). The CUDA framework has two
+complementary pieces to it.
+
+There are a set of GPU instruction set extensions that are implemented by
+various graphics cards. These instruction set extensions are known as the CUDA
+Compute Capability.
+
+The second part of the framework is an SDK that allows developers to take
+advantage of the hardware's instruction set extensions of a particular version
+(a specific CUDA Compute Capability version, that is).
+
+An application will link with a version of the CUDA SDK, and the version of the
+CUDA SDK controls which CUDA Compute Capability versions the application will
+be able to work with.
+
+The ``os_traits.hw.gpu.cuda`` module contains traits for both the CUDA compute
+capability version as well as the CUDA SDK version. For example,
+``os_traits.hw.gpu.cuda.COMPUTE_CAPABILITY_V3_2`` and
+``os_traits.hw.gpu.cuda.SDK_V6_5``.
+
+The ``os_traits.hw.gpu.cuda`` module contains a utility function called
+``compute_capabilities_supported()`` that accepts a trait indicating the CUDA
+SDK version and returns a ``set()`` containing the matching CUDA compute
+capability traits that that version of the CUDA SDK knows how to utilize.
+
+Here is an example of listing the CUDA compute capability version traits that
+the CUDA SDK 8.0 is capable of working with::
+
+    >>> from os_traits.hw.gpu import cuda
+    >>> import pprint
+    >>>
+    >>> sdk8_caps = cuda.compute_capabilities_supported(cuda.SDK_V8_0)
+    >>> pprint.pprint(sdk8_caps)
+    set(['HW_GPU_CUDA_COMPUTE_CAPABILITY_V2_0',
+         'HW_GPU_CUDA_COMPUTE_CAPABILITY_V2_1',
+         'HW_GPU_CUDA_COMPUTE_CAPABILITY_V3_0',
+         'HW_GPU_CUDA_COMPUTE_CAPABILITY_V3_2',
+         'HW_GPU_CUDA_COMPUTE_CAPABILITY_V3_5',
+         'HW_GPU_CUDA_COMPUTE_CAPABILITY_V3_7',
+         'HW_GPU_CUDA_COMPUTE_CAPABILITY_V5_0',
+         'HW_GPU_CUDA_COMPUTE_CAPABILITY_V5_2',
+         'HW_GPU_CUDA_COMPUTE_CAPABILITY_V5_3',
+         'HW_GPU_CUDA_COMPUTE_CAPABILITY_V6_0',
+         'HW_GPU_CUDA_COMPUTE_CAPABILITY_V6_1',
+         'HW_GPU_CUDA_COMPUTE_CAPABILITY_V6_2'])
+
+For more information on CUDA, see the `Wikipedia article`_.
+
+.. _Wikipedia article: https://en.wikipedia.org/wiki/CUDA
+"""
+
 
 TRAITS = [
     # ref: https://en.wikipedia.org/wiki/CUDA