Options to document private/special methods

.github/workflows/ci_workflows.yml

@@ -100,9 +100,6 @@ jobs:
       run: choco install graphviz
     - name: Install tox
       run: python -m pip install tox
-    - name: Install codecov
-      if: ${{ contains(matrix.toxenv,'-cov') }}
-      run: python -m pip install codecov
     - name: Run tox
       run: tox ${{ matrix.toxargs }} -v -e ${{ matrix.toxenv }}
     - name: Upload coverage to codecov

setup.cfg

@@ -27,7 +27,6 @@ test =
     pytest
     pytest-cov
     cython
-    codecov
     coverage
 
 [options.package_data]

sphinx_automodapi/automodsumm.py

@@ -46,7 +46,7 @@
         in the generated documentation. The flags ``:inherited-members:`` or
         ``:no-inherited-members:`` allows overrriding this global setting.
 
-This extension also adds two sphinx configuration options:
+This extension also adds four sphinx configuration options:
 
 * ``automodsumm_writereprocessed``
     Should be a bool, and if ``True``, will cause `automodsumm`_ to write files
@@ -62,6 +62,16 @@ class members that are inherited from a base class. This value can be
     ``:inherited-members:`` or ``:no-inherited-members:`` options.  Defaults to
     ``False``.
 
+* ``automodsumm_private_methods_of``
+    Should be a list of fully qualified names of classes where all of its
+    private methods (i.e., method names beginning with an underscore, but
+    not ending with a double underscore) should be documented. Defaults to ``[]``.
+
+* ``automodsumm_special_methods_of``
+    Should be a list of fully qualified names of classes where all of its
+    special methods (i.e., method names beginning with a double underscore and
+    ending with a double underscore) should be documented. Defaults to ``[]``.
+
 .. _sphinx.ext.autosummary: http://sphinx-doc.org/latest/ext/autosummary.html
 .. _autosummary: http://sphinx-doc.org/latest/ext/autosummary.html#directive-autosummary
 
@@ -269,7 +279,9 @@ def process_automodsumm_generation(app):
             generate_automodsumm_docs(
                 lines, sfn, app=app, builder=app.builder,
                 base_path=app.srcdir,
-                inherited_members=app.config.automodsumm_inherited_members)
+                inherited_members=app.config.automodsumm_inherited_members,
+                private_methods_of=app.config.automodsumm_private_methods_of,
+                special_methods_of=app.config.automodsumm_special_methods_of)
 
 
 # _automodsummrex = re.compile(r'^(\s*)\.\. automodsumm::\s*([A-Za-z0-9_.]+)\s*'
@@ -406,7 +418,9 @@ def automodsumm_to_autosummary_lines(fn, app):
 def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst',
                               base_path=None, builder=None,
                               template_dir=None,
-                              inherited_members=False):
+                              inherited_members=False,
+                              private_methods_of=[],
+                              special_methods_of=[]):
     """
     This function is adapted from
     `sphinx.ext.autosummary.generate.generate_autosummmary_docs` to
@@ -520,10 +534,13 @@ def get_members_mod(obj, typ, include_public=[]):
                 return public, items
 
             def get_members_class(obj, typ, include_public=[],
-                                  include_base=False):
+                                  include_base=False,
+                                  private_methods=False, special_methods=False):
                 """
                 typ = None -> all
                 include_base -> include attrs that are from a base class
+                private_methods -> include all private methods
+                special_methods -> include all special methods
                 """
                 items = []
 
@@ -548,6 +565,7 @@ def get_members_class(obj, typ, include_public=[],
                     else:
                         names = getattr(obj, '__dict__').keys()
 
+                methods = []
                 for name in names:
                     try:
                         documenter = get_documenter(app, safe_getattr(obj, name), obj)
@@ -559,8 +577,18 @@ def get_members_class(obj, typ, include_public=[],
                         # In Sphinx 2.0 and above, properties have a separate
                         # objtype, but we treat them the same here.
                         items.append(name)
+                    if typ in (None, 'method') and documenter.objtype == 'method':
+                        methods.append(name)
                 public = [x for x in items
                           if x in include_public or not x.startswith('_')]
+                if private_methods:  # Include all private methods
+                    private = [x for x in methods if x not in public
+                               and x.startswith('_') and not x.endswith('__')]
+                    public.extend(private)
+                if special_methods:  # Include all special methods
+                    special = [x for x in methods if x not in public
+                               and x.startswith('__') and x.endswith('__')]
+                    public.extend(special)
                 return public, items
 
             ns = {}
@@ -581,12 +609,19 @@ def get_members_class(obj, typ, include_public=[],
                     # use default value
                     include_base = inherited_members
 
+                private_methods = True if name in private_methods_of else False
+                special_methods = True if name in special_methods_of else False
+
+                class_kwargs = {
+                    'include_base': include_base,
+                    'private_methods': private_methods,
+                    'special_methods': special_methods,
+                }
+
                 api_class_methods = ['__init__', '__call__']
-                ns['members'] = get_members_class(obj, None,
-                                                  include_base=include_base)
+                ns['members'] = get_members_class(obj, None, **class_kwargs)
                 ns['methods'], ns['all_methods'] = \
-                    get_members_class(obj, 'method', api_class_methods,
-                                      include_base=include_base)
+                    get_members_class(obj, 'method', api_class_methods, **class_kwargs)
                 ns['attributes'], ns['all_attributes'] = \
                     get_members_class(obj, 'attribute',
                                       include_base=include_base)
@@ -664,6 +699,8 @@ def setup(app):
 
     app.add_config_value('automodsumm_writereprocessed', False, True)
     app.add_config_value('automodsumm_inherited_members', False, 'env')
+    app.add_config_value('automodsumm_private_methods_of', [], 'env')
+    app.add_config_value('automodsumm_special_methods_of', [], 'env')
 
     return {'parallel_read_safe': True,
             'parallel_write_safe': True}

sphinx_automodapi/tests/cases/private_methods/README.md

@@ -0,0 +1,2 @@
+Documenting a module with classes, also including private methods 
+for a particular list of classes.

sphinx_automodapi/tests/cases/private_methods/input/index.rst

@@ -0,0 +1 @@
+.. automodapi:: sphinx_automodapi.tests.example_module.private_classes

sphinx_automodapi/tests/cases/private_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Banana.rst

@@ -0,0 +1,19 @@
+Banana
+======
+
+.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes
+
+.. autoclass:: Banana
+   :show-inheritance:
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+
+      ~Banana._energy
+      ~Banana.eat
+
+   .. rubric:: Methods Documentation
+
+   .. automethod:: _energy
+   .. automethod:: eat

sphinx_automodapi/tests/cases/private_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Fruit.rst

@@ -0,0 +1,31 @@
+Fruit
+=====
+
+.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes
+
+.. autoclass:: Fruit
+   :show-inheritance:
+
+   .. rubric:: Attributes Summary
+
+   .. autosummary::
+
+      ~Fruit.weight
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+
+      ~Fruit._out_of_date
+      ~Fruit.buy
+      ~Fruit.eat
+
+   .. rubric:: Attributes Documentation
+
+   .. autoattribute:: weight
+
+   .. rubric:: Methods Documentation
+
+   .. automethod:: _out_of_date
+   .. automethod:: buy
+   .. automethod:: eat

sphinx_automodapi/tests/cases/private_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Orange.rst

@@ -0,0 +1,17 @@
+Orange
+======
+
+.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes
+
+.. autoclass:: Orange
+   :show-inheritance:
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+
+      ~Orange.eat
+
+   .. rubric:: Methods Documentation
+
+   .. automethod:: eat

sphinx_automodapi/tests/cases/private_methods/output/index.rst.automodapi

@@ -0,0 +1,19 @@
+
+sphinx_automodapi.tests.example_module.private_classes Module
+-------------------------------------------------------------
+
+.. automodule:: sphinx_automodapi.tests.example_module.private_classes
+
+Classes
+^^^^^^^
+
+.. automodsumm:: sphinx_automodapi.tests.example_module.private_classes
+    :classes-only:
+    :toctree: api
+
+Class Inheritance Diagram
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automod-diagram:: sphinx_automodapi.tests.example_module.private_classes
+    :private-bases:
+    :parts: 1

sphinx_automodapi/tests/cases/private_methods/output/index.rst.automodsumm

@@ -0,0 +1,9 @@
+.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes
+
+.. autosummary::
+    :toctree: api
+
+    Fruit
+    Banana
+    Orange
+

sphinx_automodapi/tests/cases/special_methods/README.md

@@ -0,0 +1,2 @@
+Documenting a module with classes, also including special methods 
+for a particular list of classes.

sphinx_automodapi/tests/cases/special_methods/input/index.rst

@@ -0,0 +1 @@
+.. automodapi:: sphinx_automodapi.tests.example_module.private_classes

sphinx_automodapi/tests/cases/special_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Banana.rst

@@ -0,0 +1,17 @@
+Banana
+======
+
+.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes
+
+.. autoclass:: Banana
+   :show-inheritance:
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+
+      ~Banana.eat
+
+   .. rubric:: Methods Documentation
+
+   .. automethod:: eat

sphinx_automodapi/tests/cases/special_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Fruit.rst

@@ -0,0 +1,31 @@
+Fruit
+=====
+
+.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes
+
+.. autoclass:: Fruit
+   :show-inheritance:
+
+   .. rubric:: Attributes Summary
+
+   .. autosummary::
+
+      ~Fruit.weight
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+
+      ~Fruit.__len__
+      ~Fruit.buy
+      ~Fruit.eat
+
+   .. rubric:: Attributes Documentation
+
+   .. autoattribute:: weight
+
+   .. rubric:: Methods Documentation
+
+   .. automethod:: __len__
+   .. automethod:: buy
+   .. automethod:: eat

sphinx_automodapi/tests/cases/special_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Orange.rst

@@ -0,0 +1,19 @@
+Orange
+======
+
+.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes
+
+.. autoclass:: Orange
+   :show-inheritance:
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+
+      ~Orange.__add__
+      ~Orange.eat
+
+   .. rubric:: Methods Documentation
+
+   .. automethod:: __add__
+   .. automethod:: eat

sphinx_automodapi/tests/cases/special_methods/output/index.rst.automodapi

@@ -0,0 +1,19 @@
+
+sphinx_automodapi.tests.example_module.private_classes Module
+-------------------------------------------------------------
+
+.. automodule:: sphinx_automodapi.tests.example_module.private_classes
+
+Classes
+^^^^^^^
+
+.. automodsumm:: sphinx_automodapi.tests.example_module.private_classes
+    :classes-only:
+    :toctree: api
+
+Class Inheritance Diagram
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automod-diagram:: sphinx_automodapi.tests.example_module.private_classes
+    :private-bases:
+    :parts: 1

sphinx_automodapi/tests/cases/special_methods/output/index.rst.automodsumm

@@ -0,0 +1,9 @@
+.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes
+
+.. autosummary::
+    :toctree: api
+
+    Fruit
+    Banana
+    Orange
+