From 6c7a563f34488a74189203c2bbc9715eb3ab50cd Mon Sep 17 00:00:00 2001
From: Paul Ganssle <paul@ganssle.io>
Date: Thu, 3 May 2018 19:30:03 -0400
Subject: [PATCH 1/5] Update docs requirements to include
sphinx-autodoc-variants
---
docs/requirements-docs.txt | 1 +
1 file changed, 1 insertion(+)
diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index 1c03c18..40a2cdf 100644
--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -1,2 +1,3 @@
Sphinx
sphinx_rtd_theme>=0.3.1
+sphinx-autodoc-variants
From 98bfdda9c6e389956f7ccff021e9ab35a15280f5 Mon Sep 17 00:00:00 2001
From: Paul Ganssle <paul@ganssle.io>
Date: Wed, 13 Dec 2017 16:37:18 -0500
Subject: [PATCH 2/5] Example of how variants show up in sphinx
---
docs/conf.py | 5 ++-
docs/examples/__init__.py | 0
docs/examples/example_mod.py | 17 ++++++++++
docs/examples/example_mod.rst | 7 ++++
docs/examples/example_variants.py | 32 ++++++++++++++++++
docs/index.rst | 2 ++
docs/sphinx.rst | 55 +++++++++++++++++++++++++++++++
7 files changed, 117 insertions(+), 1 deletion(-)
create mode 100644 docs/examples/__init__.py
create mode 100644 docs/examples/example_mod.py
create mode 100644 docs/examples/example_mod.rst
create mode 100644 docs/examples/example_variants.py
create mode 100644 docs/sphinx.rst
diff --git a/docs/conf.py b/docs/conf.py
index 935c6b6..cfad161 100755
--- a/docs/conf.py
+++ b/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']
diff --git a/docs/examples/__init__.py b/docs/examples/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/docs/examples/example_mod.py b/docs/examples/example_mod.py
new file mode 100644
index 0000000..108a08b
--- /dev/null
+++ b/docs/examples/example_mod.py
@@ -0,0 +1,17 @@
+"""
+Example module with function variants
+"""
+
+from variants import primary
+
+@primary
+def func():
+ """This is the primary variant"""
+
+@func.variant('alternate')
+def func():
+ """This is an alternate function"""
+
+
+def non_variant_func():
+ """This is a function that is NOT a variant"""
diff --git a/docs/examples/example_mod.rst b/docs/examples/example_mod.rst
new file mode 100644
index 0000000..d52ffff
--- /dev/null
+++ b/docs/examples/example_mod.rst
@@ -0,0 +1,7 @@
+==============
+Example Module
+==============
+
+.. automodule:: example_mod
+ :members:
+ :undoc-members:
diff --git a/docs/examples/example_variants.py b/docs/examples/example_variants.py
new file mode 100644
index 0000000..91f4959
--- /dev/null
+++ b/docs/examples/example_variants.py
@@ -0,0 +1,32 @@
+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('variant_1')
+def primary_func(x):
+ """This is variant_1, it only takes one argument."""
+
+
+@primary_func.variant('variant_2')
+def primary_func(x, y, z):
+ """This is variant_2, 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('variant_1')
+ def primary_method(self, x):
+ """This is variant_1, it takes one argument."""
diff --git a/docs/index.rst b/docs/index.rst
index 92fc67d..f5332df 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,8 +11,10 @@ Contents:
:maxdepth: 2
readme
+ sphinx
installation
usage
+ examples/example_mod
.. toctree::
:maxdepth: 1
diff --git a/docs/sphinx.rst b/docs/sphinx.rst
new file mode 100644
index 0000000..ff7d913
--- /dev/null
+++ b/docs/sphinx.rst
@@ -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:
From 9419e857258e37e8dd261a68abdd2129b1fe266d Mon Sep 17 00:00:00 2001
From: Paul Ganssle <paul@ganssle.io>
Date: Thu, 3 May 2018 18:24:30 -0400
Subject: [PATCH 3/5] Drop duplicate example
---
docs/examples/example_mod.py | 17 -----------------
docs/examples/example_mod.rst | 7 -------
docs/index.rst | 3 +--
3 files changed, 1 insertion(+), 26 deletions(-)
delete mode 100644 docs/examples/example_mod.py
delete mode 100644 docs/examples/example_mod.rst
diff --git a/docs/examples/example_mod.py b/docs/examples/example_mod.py
deleted file mode 100644
index 108a08b..0000000
--- a/docs/examples/example_mod.py
+++ /dev/null
@@ -1,17 +0,0 @@
-"""
-Example module with function variants
-"""
-
-from variants import primary
-
-@primary
-def func():
- """This is the primary variant"""
-
-@func.variant('alternate')
-def func():
- """This is an alternate function"""
-
-
-def non_variant_func():
- """This is a function that is NOT a variant"""
diff --git a/docs/examples/example_mod.rst b/docs/examples/example_mod.rst
deleted file mode 100644
index d52ffff..0000000
--- a/docs/examples/example_mod.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-==============
-Example Module
-==============
-
-.. automodule:: example_mod
- :members:
- :undoc-members:
diff --git a/docs/index.rst b/docs/index.rst
index f5332df..d2ad2b1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,10 +11,9 @@ Contents:
:maxdepth: 2
readme
- sphinx
installation
usage
- examples/example_mod
+ Variant Autodoc (Sphinx) <sphinx>
.. toctree::
:maxdepth: 1
From 01e6c99209520b467c3e0a7aa99491807868f09d Mon Sep 17 00:00:00 2001
From: Paul Ganssle <paul@ganssle.io>
Date: Thu, 3 May 2018 18:28:10 -0400
Subject: [PATCH 4/5] Improve example variant documentation
---
changelog.d/36.doc.rst | 1 +
docs/examples/example_variants.py | 15 +++++++++------
2 files changed, 10 insertions(+), 6 deletions(-)
create mode 100644 changelog.d/36.doc.rst
diff --git a/changelog.d/36.doc.rst b/changelog.d/36.doc.rst
new file mode 100644
index 0000000..29145cb
--- /dev/null
+++ b/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.
diff --git a/docs/examples/example_variants.py b/docs/examples/example_variants.py
index 91f4959..d13beee 100644
--- a/docs/examples/example_variants.py
+++ b/docs/examples/example_variants.py
@@ -9,14 +9,14 @@ def primary_func(x, y):
"""
-@primary_func.variant('variant_1')
+@primary_func.variant('onearg')
def primary_func(x):
- """This is variant_1, it only takes one argument."""
+ """This is the ``onearg`` variant, it only takes one argument."""
-@primary_func.variant('variant_2')
+@primary_func.variant('threearg')
def primary_func(x, y, z):
- """This is variant_2, it takes three arguments."""
+ """This is the ``threearg`` variant, it takes three arguments."""
class VariantMethodsClass(object):
@@ -27,6 +27,9 @@ def primary_method(self, x, y):
primary method documentation.
"""
- @primary_method.variant('variant_1')
+ @primary_method.variant('onearg')
def primary_method(self, x):
- """This is variant_1, it takes one argument."""
+ """This is the ``onearg`` variant, it takes one argument."""
+
+ def normal_method(self, a, b):
+ """This is a normal method, it has no variants"""
From 069abfd47e1ea4e35ad54ac1a6029b9e4fac595a Mon Sep 17 00:00:00 2001
From: Paul Ganssle <paul@ganssle.io>
Date: Fri, 12 Oct 2018 16:26:29 -0400
Subject: [PATCH 5/5] Fix travis for Python 3.3
This is a bug in how virtualenv released their first version that
doesn't support Python 3.3 that we now have to work around.
---
.travis.yml | 7 +++++--
1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/.travis.yml b/.travis.yml
index 97aae61..c066509 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -15,7 +15,10 @@ matrix:
env: TOXENV=docs
# command to install dependencies, e.g. pip install -r requirements.txt --use-mirrors
-install: pip install -U tox-travis
+install:
+ - pip install -U tox-travis
+ - if [[ $TRAVIS_PYTHON_VERSION == "3.3" ]]; then pip install 'virtualenv<16.0'; fi
+ - if [[ $TRAVIS_PYTHON_VERSION == "3.3" ]]; then pip install 'setuptools<40.0'; fi
# command to run tests, e.g. python setup.py test
-script: tox
\ No newline at end of file
+script: tox