tests-sample-autodocs: adding sample set

Signed-off-by: James Knight <[email protected]>

Author: jdknight

tests/sample-sets/autodocs/autodocs.rst

@@ -0,0 +1,33 @@
+sphinx.ext.autodocs
+===================
+
+This page shows an example of various autodoc capabilities.
+
+autodocs - automodule
+---------------------
+
+The automodule directive:
+
+.. automodule:: Hello
+    :members:
+
+----
+
+The autoclass directive:
+
+.. autoclass:: Hello
+    :members: say_hello
+    :noindex:
+
+    .. method:: foo(arg1, arg2)
+        :noindex:
+
+        An overwritten description of the method ``foo``.
+
+----
+
+The autofunction directive:
+
+.. currentmodule:: func
+
+.. autofunction:: my_custom_function

tests/sample-sets/autodocs/autosummary.rst

@@ -0,0 +1,17 @@
+sphinx.ext.autosummary
+======================
+
+An example of a local docstring:
+
+.. autosummary::
+
+    Hello
+
+An example of an external module docstring:
+
+.. currentmodule:: sphinx
+
+.. autosummary::
+
+    environment.BuildEnvironment
+    util.relative_uri

tests/sample-sets/autodocs/conf.py

@@ -0,0 +1,14 @@
+from pathlib import Path
+import sys
+
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinxcontrib.confluencebuilder',
+]
+
+
+test_dir = Path(__file__).parent.resolve()
+src_dir = test_dir / 'src'
+sys.path.insert(0, str(src_dir))

tests/sample-sets/autodocs/index.rst

@@ -0,0 +1,8 @@
+Autodocs
+========
+
+.. toctree::
+    :maxdepth: 1
+
+    autodocs
+    autosummary

tests/sample-sets/autodocs/src/Hello.py

@@ -0,0 +1,47 @@
+"""
+This is a module docstring
+"""
+
+
+class Hello:
+    """
+    This is a Hello class docstring
+    """
+
+    def __init__(self, name, name2):
+        """
+        This is an __init__ method docstring.
+        Creates a new :class:`Hello` instance.
+        :param name: name for the hello
+        :param name2: name2 for the hello
+        :param name3: name3 for the hello
+        :type name: str
+        """
+        self.name = name
+
+    def say_hello(self):
+        """
+        This is a say_hello method decorator
+        """
+        print('Hello %s' % self.name)
+
+    def foo(self, arg1, arg2):
+        """
+        A method's docstring with parameters and return value.
+
+        Use all the cool Sphinx capabilities in this description, e.g. to give
+        usage examples ...
+
+        :Example:
+
+        >>> another_class.foo('', AClass())
+
+        :param arg1: first argument
+        :type arg1: string
+        :param arg2: second argument
+        :type arg2: :class:`module.AClass`
+        :return: something
+        :rtype: string
+        :raises: TypeError
+        """
+        return '' + 1

tests/sample-sets/autodocs/src/func.py

@@ -0,0 +1,7 @@
+
+def my_custom_function(obj):
+    """
+    A function's docstring with a parameter.
+
+    :param obj: the function argument
+    """

tests/sample-sets/autodocs/tox.ini

@@ -0,0 +1,11 @@
+[tox]
+package_root={toxinidir}{/}..{/}..{/}..
+
+[testenv]
+commands =
+    {envpython} -m tests.test_sample {posargs}
+setenv =
+    PYTHONDONTWRITEBYTECODE=1
+    TOX_INI_DIR={toxinidir}
+passenv = *
+use_develop = true