Merge pull request #36 from pganssle/example_variants

Add variants example documentation

Author: pganssle

changelog.d/36.doc.rst

@@ -0,0 +1 @@
+Added a documentation page demonstrating the use of the sphinx-autodocs-variants extension for displaying function groups.

docs/conf.py

@@ -29,9 +29,12 @@
 # Insert the project root dir as the first element in the PYTHONPATH.
 # This lets us ensure that the source package is imported, and that its
 # version is used.
+sys.path.insert(0, os.path.abspath('.'))
 sys.path.insert(0, os.path.join(project_root, 'src'))
+sys.path.append(os.path.join(project_root, 'docs/examples'))
 
 import variants
+import examples
 
 # -- General configuration ---------------------------------------------
 
@@ -40,7 +43,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx_autodoc_variants']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/examples/__init__.py

@@ -0,0 +1,35 @@
+import variants
+
+
+@variants.primary
+def primary_func(x, y):
+    """
+    This is the primary function. Its docstring should be shown under the
+    primary function documentation.
+    """
+
+
+@primary_func.variant('onearg')
+def primary_func(x):
+    """This is the ``onearg`` variant, it only takes one argument."""
+
+
+@primary_func.variant('threearg')
+def primary_func(x, y, z):
+    """This is the ``threearg`` variant, it takes three arguments."""
+
+
+class VariantMethodsClass(object):
+    @variants.primary
+    def primary_method(self, x, y):
+        """
+        This is the primary method, its docstring should be shown under the
+        primary method documentation.
+        """
+
+    @primary_method.variant('onearg')
+    def primary_method(self, x):
+        """This is the ``onearg`` variant, it takes one argument."""
+
+    def normal_method(self, a, b):
+        """This is a normal method, it has no variants"""

docs/examples/example_variants.py

@@ -13,6 +13,7 @@ Contents:
    readme
    installation
    usage
+   Variant Autodoc (Sphinx) <sphinx>
 
 .. toctree::
    :maxdepth: 1

docs/index.rst

@@ -1,2 +1,3 @@
 Sphinx
 sphinx_rtd_theme>=0.3.1
+sphinx-autodoc-variants

docs/requirements-docs.txt

@@ -0,0 +1,55 @@
+=====================
+Documentation example
+=====================
+
+Using the `sphinx_autodoc_variants <https://github.com/python-variants/sphinx_autodoc_variants>`_ extension, primary and variant functions can be grouped together as a single function group.
+
+Functions
+---------
+
+With the ``sphinx_autodoc_variants`` extension enabled in ``conf.py``, function groups at the module level will automatically be grouped together by the ``automodule`` directive. To explicitly document a function group, use the ``autoprimary_function`` directive:
+
+.. code-block:: rst
+
+    .. autoprimary_function:: examples.example_variants.primary_func
+        :members:
+
+Which generates:
+
+.. autoprimary_function:: examples.example_variants.primary_func
+    :members:
+    :noindex:
+
+
+Methods
+-------
+For a class containing function group methods, the ``autoclass`` directive works, so:
+
+.. code-block:: rst
+
+    .. autoclass:: examples.example_variants.VariantMethodsClass
+        :members:
+
+Resulting in:
+
+.. autoclass:: examples.example_variants.VariantMethodsClass
+    :members:
+    :noindex:
+
+
+As with functions, individual method groups can be documented using the ``autoprimary_method`` directive:
+
+.. code-block:: rst
+
+    .. autoprimary_method:: examples.example_variants.VariantMethodsClass.primary_method
+        :members:
+
+Which generates:
+
+.. autoprimary_method:: examples.example_variants.VariantMethodsClass.primary_method
+    :members:
+
+
+.. .. automodule:: examples.example_variants
+..    :members:
+..    :undoc-members: