Merge pull request #951 from sphinx-contrib/simplify-autodocs-in-v2

translator: simplify v2 autodocs renderings

Author: jdknight

sphinxcontrib/confluencebuilder/storage/translator.py

@@ -575,32 +575,16 @@ def depart_field_list(self, node):
             self.body.append(self.context.pop())  # table
 
     def visit_field(self, node):
-        if self.v2:
-            self.body.append(self._start_tag(node, 'ac:layout'))
-            self.context.append(self._end_tag(node, suffix=''))
-
-            self.body.append(self._start_tag(node, 'ac:layout-section',
-                **{
-                    'ac:type': 'two_left_sidebar',
-                    'ac:breakout-mode': 'default',
-                }))
-            self.context.append(self._end_tag(node))
-        else:
+        if not self.v2:
             self.body.append(self._start_tag(node, 'tr', suffix=self.nl))
             self.context.append(self._end_tag(node))
 
     def depart_field(self, node):
-        if self.v2:
-            self.body.append(self.context.pop())  # ac:layout-section
-            self.body.append(self.context.pop())  # ac:layout
-        else:
+        if not self.v2:
             self.body.append(self.context.pop())  # tr
 
     def visit_field_name(self, node):
-        if self.v2:
-            self.body.append(self._start_tag(node, 'ac:layout-cell'))
-            self.context.append(self._end_tag(node))
-        else:
+        if not self.v2:
             self.body.append(self._start_tag(node, 'td',
                 **{'style': 'border: none'}))
             self.context.append(self._end_tag(node))
@@ -612,22 +596,18 @@ def depart_field_name(self, node):
         self.body.append(':')
         self.body.append(self.context.pop())  # strong
 
-        if self.v2:
-            self.body.append(self.context.pop())  # ac:layout-cell
-        else:
+        if not self.v2:
             self.body.append(self.context.pop())  # td
 
     def visit_field_body(self, node):
-        if self.v2:
-            self.body.append(self._start_tag(node, 'ac:layout-cell'))
-        else:
+        if not self.v2:
             self.body.append(self._start_tag(node, 'td',
                 **{'style': 'border: none'}))
-
-        self.context.append(self._end_tag(node))
+            self.context.append(self._end_tag(node))
 
     def depart_field_body(self, node):
-        self.body.append(self.context.pop())  # td/ac:layout-cell
+        if not self.v2:
+            self.body.append(self.context.pop())  # td
 
     # -----------------------------
     # body elements -- option lists

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