chilipp / autodocsumm

Extending your autodoc API docs with a summary

Extending your autodoc API docs with a summary

docs
tests
package

Welcome! This sphinx extension provides some useful extensions to the Sphinxs autodoc extension. Those are

1. It creates a Table of Contents in the style of the autosummary extension with methods, classes, functions and attributes
2. As you can include the __init__ method documentation for via the autoclass_content configuration value, we provide the autodata_content configuration value to include the documentation from the __call__ method
3. You can exclude the string representation of specific objects. E.g. if you have a large dictionary using the not_document_data configuration value.

See the Documentation on Readthedocs for more details.

Installation

Simply install it via pip:

$ pip install autodocsumm

Local development

Use pip on the source on GitHub:

$ pip install .

Requirements

The package only requires Sphinx to be installed. It has been tested for versions higher than 1.3.

Quickstart

In order to activate the autodocsumm extension, you have to list it in your conf.py:

extensions = [
    'sphinx.ext.autodoc',
    ...,
    'autodocsumm',
]

Once this is done, you can use the :autosummary: option for autodoc directives to generate a table at the top, e.g.:

.. automodule:: my.awesome.module
    :autosummary:

Optionally, you can make autodocsumm active by default for all autodoc directives by adding in conf.py:

autodoc_default_options = {
    'autosummary': True,
}

Disclaimer

Copyright 2016-2019, Philipp S. Sommer

Copyright 2020-2021, Helmholtz-Zentrum Hereon

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

autodocsumm's Issues

Surprising effect on attribute documentation

I have observed that when I document a class with autodocsumm it will result in the documentation containing not only the documented attributes of the class but also inherited attributes and none documented attributes with a type annotation.
Removing the :autosummary: directive makes the issue go away which is why I assume the issue is related to autodocsumm.

For example, consider the following classes.

class Foo:
    """
    Foo is a class that does not inherit from any thing
    """

    classattr: str = "MyClassAttr"
    """
    This is a class attribute
    """

    def __init__(self):
        self.instance_attr: str = "MyInstanceAttr"
        """
        This is an instance attribute
        """

        self.typed_instance_attr: str = "MyTypedAttrNoDocs"


class Bar(Foo):
    """
    Bar is a class that inherits from Foo
    """

    def __init__(self):
        self.other_instance_attr: str = "MyOtherInstanceAttr"
        """
        This is annother instance attribute
        """

        super().__init__()

and the following rst file.

API
===

This is the debugproject API docs

.. automodule:: debugproject
    :autosummary:
    :no-inherited-members:

This result is the documentation below for Bar

Here I would not expect instance_attr and typed_instance_attr to be included in the docs but they are documented inline but not in the table provided by autodocsumm.

See the full example in https://github.com/jenshnielsen/debugproject/tree/autodocsumm_attrs

Type annotations are not rendered properly

Hi, thanks for the cool project. It seems that the type annotations for the class arguments are not rendered properly. Catch this in Marshmallow docs: https://marshmallow.readthedocs.io/en/stable/marshmallow.validate.html

Take the first And class as an example. Here is the raw definition:

And(*validators: Callable[[Any], Any], error: Optional[str] = None)

Expected output:

And(*validators, error)

Actual output:

And(*validators, Any], error)

• sphinx==4.1.2
• autodocsumm==0.2.6

Possible dependency mismatch between Conda and PyPI packages

If I list package dependencies on conda-forge, I get this:

$ conda search "autodocsumm=0.2.12" --info
Loading channels: done
autodocsumm 0.2.12 pyhd8ed1ab_0
-------------------------------
file name   : autodocsumm-0.2.12-pyhd8ed1ab_0.conda
name        : autodocsumm
version     : 0.2.12
build       : pyhd8ed1ab_0
build number: 0
size        : 19 KB
license     : Apache-2.0
subdir      : noarch
url         : https://conda.anaconda.org/conda-forge/noarch/autodocsumm-0.2.12-pyhd8ed1ab_0.conda
md5         : b0e58323e15cb50328a1bb3e8158a49c
timestamp   : 2024-01-05 11:36:27 UTC
dependencies: 
  - python >=3.5
  - six
  - sphinx >=2.2,<=5.0

while the pyproject.toml file lists this:

requires-python = '>= 3.7'
dependencies = [
    'Sphinx >= 2.2, < 8.0',
]

Is this intentional?

Exception attribute 'args' not shown in attribute summary table

The standard Python Exception class exposes an args attribute, but that attribute is not included in the attribute summary table generated by autodocsumm.

The args attribute is in the list returned by dir(), and inspect.getmembers() returns it as well, so it is pretty officially there.

0.2.5: pytest warnings

+ PYTHONPATH=/home/tkloczko/rpmbuild/BUILDROOT/python-autodocsumm-0.2.5-2.fc35.x86_64/usr/lib64/python3.8/site-packages:/home/tkloczko/rpmbuild/BUILDROOT/python-autodocsumm-0.2.5-2.fc35.x86_64/usr/lib/python3.8/site-packages
+ PYTHONDONTWRITEBYTECODE=1
+ /usr/bin/pytest -ra -q
=========================================================================== test session starts ============================================================================
platform linux -- Python 3.8.9, pytest-6.2.4, py-1.10.0, pluggy-0.13.1
benchmark: 3.4.1 (defaults: timer=time.perf_counter disable_gc=False min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=100000)
Using --randomly-seed=2950380200
rootdir: /home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5, configfile: setup.cfg
plugins: forked-1.3.0, shutil-1.7.0, virtualenv-1.7.0, expect-1.1.0, httpbin-1.0.0, flake8-1.0.7, timeout-1.4.2, betamax-0.8.1, freezegun-0.4.2, case-1.5.3, isort-1.3.0, aspectlib-1.5.2, asyncio-0.15.1, toolbox-0.5, xprocess-0.17.1, aiohttp-0.3.0, checkdocs-2.7.0, mock-3.6.1, rerunfailures-9.1.1, requests-mock-1.9.3, cov-2.12.1, pyfakefs-4.5.0, cases-3.6.1, flaky-3.7.0, hypothesis-6.14.0, benchmark-3.4.1, xdist-2.3.0, pylama-7.7.1, randomly-3.8.0, Faker-8.8.2, datadir-1.3.1, regressions-2.2.0
collected 22 items

tests/test_autodocsumm.py .x...                                                                                                                                      [ 23%]
. .                                                                                                                                                                  [ 28%]
tests/test_autodocsumm.py ...............                                                                                                                            [100%]

============================================================================= warnings summary =============================================================================
tests/test_autodocsumm.py: 32 warnings
  /home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:197: RemovedInSphinx60Warning: DocumenterBridge.filename_set is deprecated.
    self.directive.filename_set.add(self.analyzer.srcname)

tests/test_autodocsumm.py: 51 warnings
  /home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:492: RemovedInSphinx50Warning: The 'ignore' argument to prepare_docstring() is deprecated.
    doc.append(prepare_docstring(docstring, ignore))

-- Docs: https://docs.pytest.org/en/stable/warnings.html
========================================================================= short test summary info ==========================================================================
XFAIL tests/test_autodocsumm.py::TestAutosummaryDocumenter::test_warnings_depreciation
=============================================================== 20 passed, 1 xfailed, 83 warnings in 10.32s ================================================================

get_documenters is deprecated in Sphinx 5

When using with Sphinx 4.0.2, I get plenty of deprecation warnings like this:

venv37/lib/python3.7/site-packages/autodocsumm/__init__.py:202: RemovedInSphinx50Warning: get_documenters() is deprecated.
  registry = get_documenters(self.env.app)

invoked here:

autodocsumm/autodocsumm/__init__.py

Line 202 in 3510543

registry = get_documenters(self.env.app)

the deprecated APIs page suggests sphinx.registry.documenters as the new API, looks like it's just a dictionary: https://github.com/sphinx-doc/sphinx/blob/2809b30c17a8fe362910f40b91fa2c17012d3ef1/sphinx/registry.py#L63

https://www.sphinx-doc.org/en/master/extdev/deprecated.html

Crash when encountering class attributes that are aliases

Hi,

I have encountered an issue where autodocsumm crashes when it encounters a class attribute that is a type instance (i.e. it is just an alias). What appears to happen is the following:

• autodoc's ClassCodumenter's get_doc returns None for aliases.
• AutoSummary's get_grouped_documenters attempts to iterate over the return value of get_doc
• Combined, this results in a TypeError when a class has a type instance as an attribute

minimal-example.zip

Apply autosummary for module but not nested classes

I'm using autodocsumm along with sphinx-apidoc to generate documentation.

My current usage is as follows:

.. automodule:: {{ pkgname }}
   :members:
   :undoc-members:
   :inherited-members:
   :autosummary:

This creates the summary table as desired for the module, but also causes each class etc. in the package added by automodule to have a summary table, which is not desired. Is there an easy way I can get just the summary table for the module, and not for nested structures?

Reference target not found in specific cases

I've had some issues with reference targets not being found in the summary table. This happens in multiple of my projects, but within each project, the problem was limited to some modules only. This is a bit annoying because you can't just click an object in the summary table and jump directly to its full documentation.

I think I've found the cause for the issue now. Let me give an example project structure.

my_module
├─ submodule1
├─ submodule2

submodule1.py

class MyClass1:
    pass

submodule1.rst

.. automodule:: my_module.submodule1
    :members:
    :autosummary:

This will generate the following output:

.. py:module:: my_module.submodule1
**Classes:**
.. autosummary::
    ~my_module.submodule1.MyClass1

[...]

Everything works fine and all reference targets are found, until I add an import statement like import my_module.submodule2 to submodule1.py. Why and how the in-code imports break the reference targets is something that I don't fully understand. But as soon as I import some other module from my own package, the reference targets in the module that contains the import statement are no longer found.

I've found that reference targets work correctly if I make a minor change to autodocsumm.

autodocsumm/autodocsumm/__init__.py

Lines 305 to 308 in 255292a

	for (documenter, _) in documenters:
	self.add_line(
	indent + '~' + documenter.fullname, sourcename)
	self.add_line('', sourcename)

By changing Line 307 to indent + documenter.object_name, sourcename), reference targets work correctly for module and class summaries in all cases that I have tested.

The generated output after this is

.. py:module:: my_module.submodule1
**Classes:**
.. autosummary::
    MyClass1

[...]

The visual representation of the summary table does not change because of this.

Edit: I forgot, this on Python 3.8 with Sphinx v4.4.0

Docs are not building

For some reason, RTD installs Sphinx 1.8.5 and doesn't update it

https://readthedocs.org/projects/autodocsumm/builds/13526310/

Some way to put documentation on separate pages like sphinx.ext.autosummary

Is there a way to put the documentation for each function/method on a separate page like you can do with sphinx.ext.autosummary? I have been trying to figure out if it's possible to do it by somehow mixing autodocsumm and autosummary, but I'm not seeing a straightforward way to do it.

My main motivation here is that I like that autodocsumm uses autodoc to determine which members are included. autosummary uses its own method, which is very coarse compared to autodoc (e.g., autosummary doesn't seem to have a way to exclude undocumented or private methods, even by editing the template).

0.2.8: sphinx is failing and some refferences warnings

Looks like sphinx is failing because missing entries in sys.path

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/conf.py", line 20, in <module>
    import autodocsumm
ModuleNotFoundError: No module named 'autodocsumm'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 272, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 202, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 165, in read
    namespace = eval_config_file(filename, tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 345, in eval_config_file
    raise ConfigError(msg % traceback.format_exc()) from exc
sphinx.errors.ConfigError: There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/conf.py", line 20, in <module>
    import autodocsumm
ModuleNotFoundError: No module named 'autodocsumm'


Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/conf.py", line 20, in <module>
    import autodocsumm
ModuleNotFoundError: No module named 'autodocsumm'

This can be fixed by patch:

--- a/docs/conf.py~     2022-04-19 19:21:53.000000000 +0000
+++ b/docs/conf.py      2022-04-19 19:28:05.964287059 +0000
@@ -17,12 +17,13 @@
 import os.path as osp
 import re
 import six
-import autodocsumm

 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath(osp.dirname(__file__)))
+sys.path.append(os.path.abspath('..'))
+
+import autodocsumm

 # -- General configuration ------------------------------------------------

However after that sphinx fails in other place

[tkloczko@devel-g2v autodocsumm-0.2.8]$ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0
[autosummary] generating autosummary for: api/autodocsumm.rst, conf_settings.rst, demo_class.rst, demo_grouper.rst, demo_module.rst, examples.rst, index.rst
Failed to import dummy.
Possible hints:
* ModuleNotFoundError: No module named 'dummy'
* KeyError: 'dummy'
Failed to import dummy.
Possible hints:
* ModuleNotFoundError: No module named 'dummy'
* KeyError: 'dummy'
Failed to import dummy.
Possible hints:
* ModuleNotFoundError: No module named 'dummy'
* KeyError: 'dummy'
Failed to import dummy.
Possible hints:
* ModuleNotFoundError: No module named 'dummy'
* KeyError: 'dummy'
Failed to import dummy.
Possible hints:
* ModuleNotFoundError: No module named 'dummy'
* KeyError: 'dummy'
Failed to import dummy.
Possible hints:
* ModuleNotFoundError: No module named 'dummy'
* KeyError: 'dummy'
loading intersphinx inventory from https://www.sphinx-doc.org/en/master/objects.inv...
loading intersphinx inventory from https://docs.python.org/3.9/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 7 added, 0 changed, 0 removed
reading sources... [ 14%] api/autodocsumm
Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/events.py", line 94, in emit
    results.append(listener.handler(self.app, *args))
  File "/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/conf.py", line 395, in example_grouper
    import dummy2
ModuleNotFoundError: No module named 'dummy2'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 276, in build_main
    app.build(args.force_all, filenames)
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 330, in build
    self.builder.build_update()
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 283, in build_update
    self.build(['__all__'], to_build)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 300, in build
    updated_docnames = set(self.read())
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 407, in read
    self._read_serial(docnames)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 428, in _read_serial
    self.read_doc(docname)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 468, in read_doc
    doctree = read_doc(self.app, self.env, self.env.doc2path(docname))
  File "/usr/lib/python3.8/site-packages/sphinx/io.py", line 181, in read_doc
    pub.publish()
  File "/usr/lib/python3.8/site-packages/docutils/core.py", line 217, in publish
    self.document = self.reader.read(self.source, self.parser,
  File "/usr/lib/python3.8/site-packages/sphinx/io.py", line 101, in read
    self.parse()
  File "/usr/lib/python3.8/site-packages/docutils/readers/__init__.py", line 78, in parse
    self.parser.parse(self.input, document)
  File "/usr/lib/python3.8/site-packages/sphinx/parsers.py", line 89, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 170, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2769, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 327, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 393, in new_subsection
    newabsoffset = self.nested_parse(
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 196, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2342, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2354, in explicit_construct
    return method(self, expmatch)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2096, in directive
    return self.run_directive(
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2146, in run_directive
    result = directive_instance.run()
  File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/directive.py", line 154, in run
    documenter.generate(more_content=self.content)
  File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 978, in generate
    self.add_content(more_content)
  File "/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py", line 367, in add_content
    self.add_autosummary(relative_ref_paths=True)
  File "/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py", line 296, in add_autosummary
    grouped_documenters = self.get_grouped_documenters()
  File "/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py", line 273, in get_grouped_documenters
    user_section = self.env.app.emit_firstresult(
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 457, in emit_firstresult
    return self.events.emit_firstresult(event, *args,
  File "/usr/lib/python3.8/site-packages/sphinx/events.py", line 112, in emit_firstresult
    for result in self.emit(name, *args, allowed_exceptions=allowed_exceptions):
  File "/usr/lib/python3.8/site-packages/sphinx/events.py", line 102, in emit
    raise ExtensionError(__("Handler %r for event %r threw an exception") %
sphinx.errors.ExtensionError: Handler <function example_grouper at 0x7fd2e0adb8b0> for event 'autodocsumm-grouper' threw an exception (exception: No module named 'dummy2')

Extension error:
Handler <function example_grouper at 0x7fd2e0adb8b0> for event 'autodocsumm-grouper' threw an exception (exception: No module named 'dummy2')

As dummy.py and dummy2.py are in docs/ final patch can look like below:

+++ b/docs/conf.py      2022-04-19 19:31:22.948359190 +0000
@@ -17,12 +17,14 @@
 import os.path as osp
 import re
 import six
-import autodocsumm

 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath(osp.dirname(__file__)))
+sys.path.append(os.path.abspath('..'))
+sys.path.append(os.path.abspath('.'))
+
+import autodocsumm

 # -- General configuration ------------------------------------------------

Wit habove documentation build corrctly.

It is yet another issue. On building my packages I'm usimg sphinx-build command with -n swich which shows warnimgs about missing references. These are not critical issues.
Here is the output with warnings:

[tkloczko@devel-g2v autodocsumm-0.2.8]$ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0
loading pickled environment... done
[autosummary] generating autosummary for: api/autodocsumm.rst, conf_settings.rst, demo_class.rst, demo_grouper.rst, demo_module.rst, examples.rst, index.rst
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
writing... python-autodocsumm.3 { conf_settings examples demo_module demo_class demo_grouper api/autodocsumm } /home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/dummy2.py:docstring of dummy2.MyClass:1:<autosummary>:1: WARNING: py:obj reference target not found: dummy2.MyClass.do_something
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/dummy2.py:docstring of dummy2.MyClass:1:<autosummary>:1: WARNING: py:obj reference target not found: dummy2.MyClass.some_attr
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/dummy2.py:docstring of dummy2.MyClass.do_something:1:<autosummary>:1: WARNING: py:obj reference target not found: dummy2.MyClass.some_other_attr
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/call_demo.py:docstring of call_demo.MyClass.do_something:1:<autosummary>:1: WARNING: py:obj reference target not found: call_demo.MyClass.do_something
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/call_demo.py:docstring of call_demo.MyClass.do_something:: WARNING: py:class reference target not found: any
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/call_demo.py:docstring of call_demo.MyClass.do_something:: WARNING: py:class reference target not found: anything else
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.AttributeDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.DataDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/inline_autoclasssumm.py:docstring of inline_autoclasssumm.MyClass.do_something:1:<autosummary>:1: WARNING: py:obj reference target not found: inline_autoclasssumm.MyClass.some_attr
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.AttributeDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.DataDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoDocSummDirective:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummClassDocumenter:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ClassDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummClassDocumenter:3: WARNING: py:class reference target not found: sphinx.ext.autodoc.ClassDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummClassDocumenter.add_content:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ClassDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummClassDocumenter.add_content:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ClassDocumenter
docstring of autodocsumm.AutoSummClassDocumenter.member_sections:3: WARNING: py:attr reference target not found: sphinx.ext.autodoc.Documenter.member_order
docstring of autodocsumm.AutoSummClassDocumenter.option_spec:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ClassDocumenter
docstring of autodocsumm.AutoSummClassDocumenter.priority:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ClassDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummModuleDocumenter:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummModuleDocumenter:3: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummModuleDocumenter.add_content:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummModuleDocumenter.add_content:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
docstring of autodocsumm.AutoSummModuleDocumenter.member_sections:3: WARNING: py:attr reference target not found: sphinx.ext.autodoc.Documenter.member_order
docstring of autodocsumm.AutoSummModuleDocumenter.option_spec:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
docstring of autodocsumm.AutoSummModuleDocumenter.priority:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutosummaryDocumenter.get_grouped_documenters:3: WARNING: py:meth reference target not found: sphinx.ext.autodoc.ModuleDocumenter.generate
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutosummaryDocumenter.get_grouped_documenters:3: WARNING: py:meth reference target not found: sphinx.ext.autodoc.ModuleDocumenter.document_members
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutosummaryDocumenter.get_grouped_documenters:10: WARNING: py:attr reference target not found: member_sections
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutosummaryDocumenter.get_grouped_documenters:18: WARNING: py:class reference target not found: sphinx.ext.autodoc.Documenter.member_order
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutosummaryDocumenter.get_grouped_documenters:18: WARNING: py:attr reference target not found: member_sections
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.CallableAttributeDocumenter:: WARNING: py:class reference target not found: DocumenterBridge
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.CallableAttributeDocumenter:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.AttributeDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.CallableAttributeDocumenter:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.AttributeDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.CallableDataDocumenter:: WARNING: py:class reference target not found: DocumenterBridge
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.CallableDataDocumenter:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.DataDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.CallableDataDocumenter:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.DataDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.dont_document_data:: WARNING: py:class reference target not found: sphinx.Options
docstring of autodocsumm.member_options:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
done
build succeeded, 40 warnings.

These are non-critical warnings 😄

Documenting class methods / attributes in `bysource` order

Hi there! First of all, let me say that this is a great extension, and it's come in handy in a project I am working on.

I have a question about ordering class members in the TOC for each class. When I use member-order: "bysource" and have autosummary: True in my autodoc_default_options, I notice that my module TOC is ordered by source, but the members in my classes are ordered alphabetically instead. Is there a way to specify bysource ordering for class members as well?

If it is any help, I am using autodocsumm==0.2.1

Thanks!

Sorting sections in the summary

hello there, i may be over-using this extension by returning other names than "Members" and "Attributes" from a autodocsumm-grouper handler. the order of sections within a summary is then determined by the one in which the members were evaluated. would you be interested to include an option for sorting these sections? i suppose the most flexible would be to accept either None (default) for no sorting or a callable that is then used for the key-parameter of the sorting.

CI is not starting

for whatever reasons, Travis does not start the jobs which is blocking #38, #37, #36

would be a good opportunity to switch to github actions...

add option to list inherited attributes & methods too

It is not possible to show inherited attributes and methods in sub class

Broken with sphinx 3.5 on windows

Hello,

It works fine with Sphinx 3.4, see attach error log file.

sphinx-err-dd25pm9e.log

Regression bug from 0.1.13 to 0.2.x ?

Hello

I have a problem with autodocsumm 1.2.x which generates a summary of all the module objects, (wrongly) including the imported objects. Also, the links between the summary table and the objects are not all created (some summary entries whose links worked before are not links at all in 1.2.x).

Reverting to 1.1.13 resolved the case for me.

I'm sorry I don't have a simple example project to reproduce the issue, but at least I'll initiate the bug report :-)

Don't hesitate if you're not able to reproduce the bug, I'll try to find time to build a simple projet.

Thank you anyways for this very helpful tool.

0.2.8: pytest warnings

I'm trying to package your module as an rpm package. So I'm using the typical PEP517 based build, install and test cycle used on building packages from non-root account.

• python3 -sBm build -w --no-isolation
• because I'm calling build with --no-isolation I'm using during all processes only locally installed modules
• install .whl file in </install/prefix>
• run pytest with PYTHONPATH pointing to sitearch and sitelib inside </install/prefix>

Here is pytest output:

+ PYTHONPATH=/home/tkloczko/rpmbuild/BUILDROOT/python-autodocsumm-0.2.8-2.fc35.x86_64/usr/lib64/python3.8/site-packages:/home/tkloczko/rpmbuild/BUILDROOT/python-autodocsumm-0.2.8-2.fc35.x86_64/usr/lib/python3.8/site-packages
+ /usr/bin/pytest -ra -q
=========================================================================== test session starts ============================================================================
platform linux -- Python 3.8.13, pytest-7.1.1, pluggy-1.0.0
rootdir: /home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8, configfile: setup.cfg
collected 22 items

tests/test_autodocsumm.py ..........x...........                                                                                                                     [100%]

============================================================================= warnings summary =============================================================================
tests/test_autodocsumm.py: 18 warnings
  /home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/tests/test_autodocsumm.py:44: GuessedAtParserWarning: No parser was explicitly specified, so I'm using the best available HTML parser for this system ("html.parser"). This usually isn't a problem, but if you run this code on another system, or in a different virtual environment, it may use a different parser and behave differently.

  The code that caused this warning is on line 44 of the file /home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/tests/test_autodocsumm.py. To get rid of this warning, pass the additional argument 'features="html.parser"' to the BeautifulSoup constructor.

    soup = bs4.BeautifulSoup(html)

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
========================================================================= short test summary info ==========================================================================
XFAIL tests/test_autodocsumm.py::TestAutosummaryDocumenter::test_warnings_depreciation
================================================================ 21 passed, 1 xfailed, 18 warnings in 3.63s ================================================================

sub classes appear as miscellaneous

• If a class defines a subclass, the subclass appear in summary chapter "miscellaneous"
• And in autodocsumm, it says "miscallaneous", which is wrong. Correct: "Miscellaneous"

feature: print module/class summary without method descriptions on same page

The idea is that one can use

.. autoclass:: module.Class
    :autosummary:

which prints the class docstring and the autodocsummary. Today, autodocsumm does not print anything, because there are no methods documented. This means, the class methods must be documented somewhere else, maybe in another rst. I don't know if this is possible.

The result would be something like this: http://pandas.pydata.org/pandas-docs/stable/reference/series.html#missing-data-handling

"Failed to import" error if a class is imported and it has an attribute without a default value

Consider a class that has an attribute without a default value, and is imported. If autoclass is applied to this class and autosummary is turned on, sphinx-build errors out.

Reproduce

Download
bug.tar.gz. Unarchive it, and run

PYTHONPATH=. sphinx-build -v -d "./_build" docs "_build/html" -b html -W --color

It produces an error:

Running Sphinx v3.4.1
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index


Traceback (most recent call last):
  File "/home/hong/.local/lib/python3.7/site-packages/sphinx/cmd/build.py", line 280, in build_main
    app.build(args.force_all, filenames)
  File "/home/hong/.local/lib/python3.7/site-packages/sphinx/application.py", line 352, in build
    self.builder.build_update()
  File "/home/hong/.local/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 298, in build_update
    len(to_build))
  File "/home/hong/.local/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 310, in build
    updated_docnames = set(self.read())
  File "/usr/lib/python3.7/contextlib.py", line 119, in __exit__
    next(self.gen)
  File "/home/hong/.local/lib/python3.7/site-packages/sphinx/util/logging.py", line 214, in pending_warnings
    memhandler.flushTo(logger)
  File "/home/hong/.local/lib/python3.7/site-packages/sphinx/util/logging.py", line 179, in flushTo
    logger.handle(record)
  File "/usr/lib/python3.7/logging/__init__.py", line 1529, in handle
    self.callHandlers(record)
  File "/usr/lib/python3.7/logging/__init__.py", line 1591, in callHandlers
    hdlr.handle(record)
  File "/usr/lib/python3.7/logging/__init__.py", line 901, in handle
    rv = self.filter(record)
  File "/usr/lib/python3.7/logging/__init__.py", line 762, in filter
    result = f.filter(record)
  File "/home/hong/.local/lib/python3.7/site-packages/sphinx/util/logging.py", line 422, in filter
    raise exc
sphinx.errors.SphinxWarning: /home/hong/tmp/myproject/_impl.py:docstring of myproject._impl.A.rst:1:autosummary: failed to import myproject.A.a

Warning, treated as error:
/home/hong/tmp/myproject/_impl.py:docstring of myproject._impl.A.rst:1:autosummary: failed to import myproject.A.a

Content of bug.tar.gz:

├── docs
│   ├── conf.py
│   └── index.rst
└── myproject
    ├── _impl.py
    └── __init__.py

_impl.py:

class A:
    "A's doc"

    a: int
    "a's doc."

__init__.py:

from ._impl import A

conf.py:

project = 'myproject'
copyright = '2020, someone'
author = 'someone'
extensions = [
    'sphinx.ext.autodoc',
    'autodocsumm'
]
html_theme = 'alabaster'

index.rst:

Welcome to myproject's documentation!
=====================================

.. currentmodule:: myproject

.. autoclass:: A
   :members:
   :show-inheritance:
   :autosummary:

Either removing :autosummary: or put the definition of class A to __init__.py resolves the error.

Feature request: option to set ":nosignatures:" for autosummary

Would be useful to be able to specify the :nosignatures: option for the autosummary to disable exception/class/function signatures. I'm currently resorting to monkey-patching AutosummaryDocumenter.add_autosummary to inline the option globally.

Estimated date for 0.2.9 release?

Hi @Chilipp, just wanted to check if there's an estimated date of release for v0.2.9. One of the projects I work on relies on autodocsumm but would like to upgrade to Sphinx v5.0, which v0.2.8 is not compatible with. (I see that master is compatible with v5.0, as of #79.)

Warning when building documentation with v0.2.0 or v0.2.1

Since version 0.2 of autodocsumm, we are seeing the following warning when building our documentation:

some_module.py:docstring of some_module.some_function:1:<autosummary>:1: WARNING: Inline emphasis start-string without end-string.

The warning appears in files that have

from itertools import product

at the top. I suspect it has something to do with the asterisk in the first argument of itertools.product (it's *iterables), but I'm not sure. My apologies for the slightly vague bug report, if there's any way in which I can make it more clear, please let me know.

Missing upper bound on sphinx version for `autodocsumm==2.2.x`

A missing upper bound on version 2.2.x is causing downstream package sphinx-toolbox to incorrectly install autodocsumm=2.2.0 together with sphinx>=4.

see sphinx-toolbox/sphinx-toolbox#71

Add support for autoexception directive

The Sphinx autodoc extension supports a directive autoexception (https://documentation.help/Sphinx/autodoc.html#directive-autoexception).

Specifying :autosummary: on the autoexception directive fails:

.../docs/client/exceptions.rst:49: WARNING: An option to autoexception is either unknown or has an invalid value: 'autosummary'

For consistency, it would be great to enable its use. I believe the autoexception directive behaves pretty much the same as the autoclass directive, but I did not dig deep into this. The autodoc documentation is not very specific about it, unfortunately.

0.2.5: sphinx warnings

+ /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx
running build_sphinx
Running Sphinx v4.0.2
making output directory... done
WARNING: html_static_path entry '_static' does not exist
[autosummary] generating autosummary for: api/autodocsumm.rst, conf_settings.rst, demo_class.rst, demo_grouper.rst, demo_module.rst, examples.rst, index.rst
Failed to import 'my.awesome.module': no module named my.awesome.module
loading intersphinx inventory from http://www.sphinx-doc.org/en/master/objects.inv...
loading intersphinx inventory from https://docs.python.org/3.7/objects.inv...
intersphinx inventory has moved: http://www.sphinx-doc.org/en/master/objects.inv -> https://www.sphinx-doc.org/en/master/objects.inv
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 7 added, 0 changed, 0 removed
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:492: RemovedInSphinx50Warning: The 'ignore' argument to prepare_docstring() is deprecated.
  doc.append(prepare_docstring(docstring, ignore))
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:492: RemovedInSphinx50Warning: The 'ignore' argument to prepare_docstring() is deprecated.
  doc.append(prepare_docstring(docstring, ignore))
reading sources... [100%] index
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:docstring of autodocsumm.NoDataAttributeDocumenter.rst:1: WARNING: autosummary: failed to import autodocsumm.NoDataAttributeDocumenter.analyzer
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:docstring of autodocsumm.NoDataAttributeDocumenter.rst:1: WARNING: autosummary: failed to import autodocsumm.NoDataAttributeDocumenter.args
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:docstring of autodocsumm.NoDataAttributeDocumenter.rst:1: WARNING: autosummary: failed to import autodocsumm.NoDataAttributeDocumenter.fullname
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:docstring of autodocsumm.NoDataAttributeDocumenter.rst:1: WARNING: autosummary: failed to import autodocsumm.NoDataAttributeDocumenter.module
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:docstring of autodocsumm.NoDataAttributeDocumenter.rst:1: WARNING: autosummary: failed to import autodocsumm.NoDataAttributeDocumenter.object_name
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:docstring of autodocsumm.NoDataAttributeDocumenter.rst:1: WARNING: autosummary: failed to import autodocsumm.NoDataAttributeDocumenter.retann
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:docstring of autodocsumm.NoDataDataDocumenter.rst:1: WARNING: autosummary: failed to import autodocsumm.NoDataDataDocumenter.analyzer
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:docstring of autodocsumm.NoDataDataDocumenter.rst:1: WARNING: autosummary: failed to import autodocsumm.NoDataDataDocumenter.args
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:docstring of autodocsumm.NoDataDataDocumenter.rst:1: WARNING: autosummary: failed to import autodocsumm.NoDataDataDocumenter.fullname
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:docstring of autodocsumm.NoDataDataDocumenter.rst:1: WARNING: autosummary: failed to import autodocsumm.NoDataDataDocumenter.module
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:docstring of autodocsumm.NoDataDataDocumenter.rst:1: WARNING: autosummary: failed to import autodocsumm.NoDataDataDocumenter.object_name
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/autodocsumm/__init__.py:docstring of autodocsumm.NoDataDataDocumenter.rst:1: WARNING: autosummary: failed to import autodocsumm.NoDataDataDocumenter.retann
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.5/docs/conf_settings.rst:75: WARNING: Unexpected indentation.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... autodocsumm.1 { conf_settings examples demo_module demo_class demo_grouper api/autodocsumm } done
build succeeded, 14 warnings.

Instance variable not shown correctly

Description
Instance variable is not shown correctly:

Example

class Example():
    """
    class documentation
    """
    class_variable = 12 #: This is a classvariable
    
    def __init__(self):
        """
        constructor doc
        """
        self.instance_variable = 34 #: This is an instance variable

Generated output:

Setup:

• Python 3.7.1
• Sphinx 2.0.1
• autodocsumm 0.1.9
• sphinx-rtd-theme 0.4.3

Missing declared dependency on `six` needs resolution

I understand that it's probably still desirable to support py2 in this project, but as some projects move to py3 only its becoming possible to have a package which doesn't depend on six 😲 !

Anyway, I think autodocsumm should either

A) add six to its dependencies (no version, I think)
or
B) treat six being absent as "automatic PY3 mode"

I haven't looked at the code yet, but my inclination would be to add

# _compat.py

try:
    import six
except ImportError:
    PY3 = True
else:
    PY3 = six.PY3

and see what else needs wrapping. I can submit a PR if that would be interesting.

Order in class is random

The order of class docstring, __init__ (if autoclass_content = "both" in conf.py) and autodocsumm summary is not always the same. For example

class A():
    """  
    Summary line
    
    Blubliblalblablalbalblablalb

    **Example**
    
    .. code-block:: python
    
        blie = A()
        blie.meth_1(2)
    """
    CLASS_ATTRIBUTE = 1 #: class attribute

    def __init__(self):
        """
        This is the __init__ docstring
        
        :param Fruit fruit: param line for sphinx autodoc
        """
        self.object_attribute = "jaja" #: this is an object attribute
    
    def meth_1(self, a):
        """
        method docstring
        
        :param int a: blublu
        :return: x is blibli        
        """
        return a + 1

shows class docstring first, then autodocsumm followed by __init__. But

class B(A):
    """
    class B summary
    """
    CLASS_ATTRIBUTE_B = 1 #: class attribute of class b

    def __init__(self):
        """
        This is the init docstring

        :param Fruit fruit: param line for sphinx autodoc
        """
        self.object_attribute_b = "jaja" #: this is an object attribute of class b
    
    def meth_2(self, a):
        """
        method b docstring
        
        :param int a: blublu b 
        :return: x is blibli b    
        """
        return a + 1

gives you class docstring first, then __init__ and finally autodocsumm.
This is maybe a bug not only concerning autodocsumm but also autodoc from Sphinx.
However, it would be nice if the order is always the same and if the user can define it optionally.

Sphinx 5 support

Hi. Thanks for autodocsumm.

Sphinx 5 is out but it is not supported by autodocsumm:

autodocsumm/setup.py

Line 41 in 2839945

'Sphinx>=2.2,<5.0',

I have no idea whether this restriction was added to setup.py in case a breaking change would occur or if there are actually known issues with Sphinx 5 that need to be addressed before loosening the range to "<6.0".

Is there any effort planned to support Sphinx 5?

Thanks.

autodocsumm fails to load with sphinx 2.4

sphinx.ext.autodoc.Signature has been removed in Sphinx 2.4.

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/scprep/envs/dev/lib/python3.7/site-packages/sphinx/registry.py", line 453, in load_extension
    mod = import_module(extname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scprep/envs/dev/lib/python3.7/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
  File "<frozen importlib._bootstrap>", line 983, in _find_and_load
  File "<frozen importlib._bootstrap>", line 967, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 677, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 728, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/home/docs/checkouts/readthedocs.org/user_builds/scprep/envs/dev/lib/python3.7/site-packages/autodocsumm/__init__.py", line 28, in <module>
    from sphinx.ext.autodoc import Signature, get_documenters
ImportError: cannot import name 'Signature' from 'sphinx.ext.autodoc' (unknown location)

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/scprep/envs/dev/lib/python3.7/site-packages/sphinx/cmd/build.py", line 275, in build_main
    args.tags, args.verbosity, args.jobs, args.keep_going)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scprep/envs/dev/lib/python3.7/site-packages/sphinx/application.py", line 245, in __init__
    self.setup_extension(extension)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scprep/envs/dev/lib/python3.7/site-packages/sphinx/application.py", line 397, in setup_extension
    self.registry.load_extension(self, extname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scprep/envs/dev/lib/python3.7/site-packages/sphinx/registry.py", line 456, in load_extension
    raise ExtensionError(__('Could not import extension %s') % extname, err)
sphinx.errors.ExtensionError: Could not import extension autodocsumm (exception: cannot import name 'Signature' from 'sphinx.ext.autodoc' (unknown location))

Extension error:
Could not import extension autodocsumm (exception: cannot import name 'Signature' from 'sphinx.ext.autodoc' (unknown location))

Warnings is deprecated

Hello, I find this extension very useful thanks for the work!

While executing it the following warning comes up:

autodocsumm_init_.py:498: RemovedInSphinx40Warning: Autosummary.warnings is deprecated
return self.warnings + dn + doc_nodes

The error comes from the following line:

autodocsumm/autodocsumm/__init__.py

Line 498 in edba002

return self.warnings + dn + doc_nodes

In the following page you can check that the warnings are deprecated: https://www.sphinx-doc.org/en/master/extdev/deprecated.html

I hope this helps :).

incompatibility with sphinx-3.0.0b1

See the failed tests for f36aa77. We're working on it

[FEATURE] Explicit summary directive alignment

Now behaviour

When autosummary is used as a directive and not as a directive option, the alignment of the table is centered.

Example

- For :data:`OrT` type:

.. autosummary::

    FORWARD_INT
    REVERSE_INT
    ORIENT_REV
    FWDOR_REVOR


- For :data:`IndOrT` type:

.. autosummary::

    IND
    OR

gives

Asked feature

Is it possible to left-align the table, for example, with an option under autosummary directive please?

Versions

• python 3.9.5
• sphinx 5.3.0
• autodocsumm 0.2.9
• furo 2022.9.29

Thank you for your work!

Alias Expands Nested Class Documentation

Assigning a type to a class attribute is documented as an alias, but its nested class members are being expanded.

class NestedClass:
    """Parent class"""
    class Foo:
        """Nested class"""
        def foo(self):
            """Nested method"""
            pass

        def bar(self):
            """Nested method"""
            pass

class Attribute:
    """Attribute"""
    #: Alias
    foo = NestedClass.Foo
    #: Attribute
    bar = 'bar'

Without autosummary on auto doc does not recurse on aliases:

No links to items in summary tables when using __init__.py imports

Hi dears,
if having an module import in __init__.py the links are missing for the class.
Sphinx is showing the links correctly, .e.g. for :meth:`mymodule.myclass.mymethod` for the below example.

Example:

• mymodule/__init__.py
  from mymodule.mysubmodule import myclass

• mymodule/mysubmodule.py

class myclass():
    def mymethod(self):
        """my doc"""

• doc.rst

.. currentmodule:: mymodule.myclass

.. autoclasssumm:: myclass
    :autosummary-members:

`*` escaped too much

Hey,

lovely tool!

I found that signatures with *args or **kwargs show up weird in final html output, displayed as \*args with visible backslash.

It works as expected if removing the line sig = sig.replace('*', r'\*').

Sphinx `ObjectMember`-related deprecations

After upgrading Sphinx from 6.1.2 to 7.2.6 (with autodocsumm 0.2.11), the following warnings are issued while building docs:

1. At

   autodocsumm/autodocsumm/__init__.py

   Line 223 in 7009e5e

   members = [(membername, member) for (membername, member) in members

   RemovedInSphinx80Warning: The tuple interface of ObjectMember is deprecated. Use (obj.__name__, obj.object) instead.
     members = [(membername, member) for (membername, member) in members
   

2. At

   autodocsumm/autodocsumm/__init__.py

   Line 230 in 7009e5e

   for (mname, member, isattr) in self.filter_members(members, want_all):

   RemovedInSphinx80Warning: Returning tuples of (name, object) as the second return value from get_object_members() is deprecated. Return ObjectMember(name, object) instances instead.
     for (mname, member, isattr) in self.filter_members(members, want_all):
   

From the name of the warning class, it seems the deprecated features will be removed in Sphinx 8.0.

I checked through the changelog but couldn't find any reference to these deprecations. Anyways, I looked a little further and found the following:

• sphinx-doc/sphinx@6f3c5b8
• sphinx-doc/sphinx#11631
• sphinx-doc/sphinx#11651
  • particularly sphinx-doc/sphinx@8f2a6f0

From these, the deprecations seem to have started from Sphinx 7.2.0.

---

I tried

@@ -220,8 +220,8 @@ class AutosummaryDocumenter(object):

         # remove members given by exclude-members
         if self.options.exclude_members:
-            members = [(membername, member) for (membername, member) in members
-                       if membername not in self.options.exclude_members]
+            members = [member for member in members
+                       if member.__name__ not in self.options.exclude_members]

         # document non-skipped members
         memberdocumenters = []

but results in

AttributeError: 'tuple' object has no attribute '__name__'

which is honestly quite confusing since the contents of members seem to be ObjectMember instances from the deprecation warning message above.

Anyways, I'm not sure I know how to go about fixing them since I'm not quite familiar with Sphinx extension code but obviously, a proper fix will have to do with

autodocsumm/autodocsumm/__init__.py

Line 219 in 7009e5e

members_check_module, members = self.get_object_members(want_all)

and

autodocsumm/autodocsumm/__init__.py

Lines 223 to 224 in 7009e5e

	members = [(membername, member) for (membername, member) in members
	if membername not in self.options.exclude_members]

---

Also, I noticed a couple other unrelated deprecation warnings while running the tests (with Sphinx 7.2.6).

f-strings not supported in python 3.5

By including f-strings in the latest release (https://github.com/Chilipp/autodocsumm/blob/master/autodocsumm/__init__.py#L530), autodocsumm is no longer compatible with python 3.5, despite the badge in the README saying it is. I suggest you either remove 3.5 from the badge and add a python_requires=">=3.6" to setup.py, or use str.format instead.

module-level summary location affected by headers in module docstring

Everything with autodocsumm works great I have a module with a docstring like this:

"""
========
mymodule
========

Here is a summary of module.

"""

When I build the sphinx docs, I get my module level docstring followed by the summary (table of contents) for the module.

But if the module-level docstring looks like this:

"""
=========
mymodule2
=========

Subheading
-------------
Some stuff
"""

then when I build the sphinx docs, the summary (table of contents) appears before the module-level doc string--which looks strange and doesn't really make sense.

No links to inherited items in summary tables

If the :autosummary-inherited-members: option is used on a class, the attribute and method summary tables generated by autodocsumm correctly include items for the inherited attributes and methods, but these items do not link to their descriptions. Their descriptions are in the same overall Sphinx document. That happens regardless of whether their descriptions are in the same or another RST file.

I verified that I can get working links to the inherited members properly generated with the :attr: and :meth: directives in the same RST file that specifies the autoclass directive, so the targeted members are visible from there at the Sphinx reference level.

Error if using autosummary for a cython extension module

Hi,

when adding the :autosummary: option to a automodule directive for a python module that was generated by cython, I get an error with the following traceback:

  File "[...]/autodocsumm/autodocsumm/__init__.py", line 421, in run
    doc_nodes = AutodocDirective.run(self)
  File "[...]/sphinx/ext/autodoc/directive.py", line 135, in run
    documenter.generate(more_content=self.content)
  File "[...]/sphinx/ext/autodoc/__init__.py", line 711, in generate
    self.analyzer = ModuleAnalyzer.for_module(self.real_modname)
  File "[...]/sphinx/pycode/__init__.py", line 72, in for_module
    type, source = get_module_source(modname)
  File "[...]/sphinx/util/__init__.py", line 312, in get_module_source
    raise PycodeError('source is not a .py file: %r' % filename)

The pure automodule directive without autosummary works.

So far, I haven't investigated deep enough on how this could be fixed.

Remove attributes for enums

Hi!
I just discovered this library and like it very much! There is just one thing that does not work as expected: In my code, there are some enums that contain many members (often more than ten). As all those entries are treated as class members (which they are, since a Python enum is a subclass of enum.Enum), autodocsumm creates redundant code: There is a table containing all enum values followed by all enum values.

I worked around that by inserting this code snippet into the docstring of all my enums:

.. autoclasssumm:: ClassName
    :autosummary-sections: Methods

Since these enumerations do not have any methods, no summary table is generated (which is my desired behavior). However, it is somewhat tedious to insert this snippet into the docstring of all enums.

Thus my request: Would it be possible to add an option allowing to disable the generation of a summary in such cases. I could think of two ways to achieve this:

1. Provide an option like autodocsumm_disabled_classes which you can pass a list of classes that should not have a summary. It has the downside that one still needs to manually insert the names of all enum classes.
2. Provide an option like autodocsumm_disable_enums that disables the generation of tables for all subclasses of enum.Enum.

I could also imagine that having both settings would be a valuable addition to this library.

0.2.4: sphinx_testing is used uses in test suite

That module actually is no longer maintained sphinx-doc/sphinx-testing#21

+ /usr/bin/python3 -Bm pytest -ra
=========================================================================== test session starts ============================================================================
platform linux -- Python 3.8.9, pytest-6.2.3, py-1.10.0, pluggy-0.13.1 -- /usr/bin/python3
cachedir: .pytest_cache
hypothesis profile 'default' -> database=DirectoryBasedExampleDatabase('/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.4/.hypothesis/examples')
rootdir: /home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.4, configfile: setup.cfg
plugins: forked-1.3.0, shutil-1.7.0, virtualenv-1.7.0, expect-1.1.0, cov-2.11.1, httpbin-1.0.0, xdist-2.2.1, flake8-1.0.7, timeout-1.4.2, betamax-0.8.1, pyfakefs-4.4.0, freezegun-0.4.2, cases-3.4.6, case-1.5.3, isort-1.3.0, aspectlib-1.5.2, flaky-3.7.0, mock-3.6.0, hypothesis-6.12.0, asyncio-0.15.1, toolbox-0.5
collected 0 items / 1 error

================================================================================== ERRORS ==================================================================================
________________________________________________________________ ERROR collecting tests/test_autodocsumm.py ________________________________________________________________
ImportError while importing test module '/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.4/tests/test_autodocsumm.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
/usr/lib64/python3.8/importlib/__init__.py:127: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
tests/test_autodocsumm.py:5: in <module>
    from sphinx_testing import with_app
E   ModuleNotFoundError: No module named 'sphinx_testing'
========================================================================= short test summary info ==========================================================================
ERROR tests/test_autodocsumm.py
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
============================================================================= 1 error in 0.24s =============================================================================

0.2.4: problematic dependencies definition

[tkloczko@barrel autodocsumm-0.2.4]$ grep -r 2.2 setup.py
setup.py:          'Sphinx>=2.2.*',

That kind of dependencies cannot be mapped in rpm dependencies generator.

error: Illegal char '*' (0x2a) in: 2.2.*
Provides: python-autodocsumm = 0.2.4-2.fc35 python3.8dist(autodocsumm) = 0.2.4 python3dist(autodocsumm) = 0.2.4
Requires(rpmlib): rpmlib(CompressedFileNames) <= 3.0.4-1 rpmlib(FileDigests) <= 4.6.0-1 rpmlib(PayloadFilesHavePrefix) <= 4.0-1
Requires: python(abi) = 3.8


RPM build errors:
    Illegal char '*' (0x2a) in: 2.2.*

Sphinx 4.0.0 breaks autodocsumm

Earlier today, sphinx 4.0.0 was released, and it removed a function the autodocsumm package depends on.

This causes the autodocsumm package to fail when trying to import 'force_decode' from 'sphinx.util' when invoking Sphinx to build.

From GitHub Actions run https://github.com/pywbem/pywbem/runs/2537231242?check_suite_focus=true:

sphinx-build -b html -v -d build_doc/doctrees -c docs -D latex_elements.papersize=a4 . build_doc/html
Running Sphinx v4.0.0
Original exception:
Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/site-packages/sphinx/registry.py", line 420, in load_extension
    mod = import_module(extname)

  File "/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1030, in _gcd_import
Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/site-packages/sphinx/registry.py", line 420, in load_extension
    mod = import_module(extname)
  File "/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1030, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1007, in _find_and_load
  File "<frozen importlib._bootstrap>", line 986, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 680, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 855, in exec_module
  File "<frozen importlib._bootstrap>", line 228, in _call_with_frames_removed
  File "/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/site-packages/autodocsumm/__init__.py", line 43, in <module>
    from sphinx.util import force_decode
ImportError: cannot import name 'force_decode' from 'sphinx.util' (/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/site-packages/sphinx/util/__init__.py)

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/site-packages/sphinx/cmd/build.py", line 276, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/site-packages/sphinx/application.py", line 243, in __init__
    self.setup_extension(extension)
  File "/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/site-packages/sphinx/application.py", line 400, in setup_extension
    self.registry.load_extension(self, extname)
  File "/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/site-packages/sphinx/registry.py", line 423, in load_extension
    raise ExtensionError(__('Could not import extension %s') % extname,
sphinx.errors.ExtensionError: Could not import extension autodocsumm (exception: cannot import name 'force_decode' from 'sphinx.util' (/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/site-packages/sphinx/util/__init__.py))

Extension error:
Could not import extension autodocsumm (exception: cannot import name 'force_decode' from 'sphinx.util' (/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/site-packages/sphinx/util/__init__.py))
  File "<frozen importlib._bootstrap>", line 1007, in _find_and_load
  File "<frozen importlib._bootstrap>", line 986, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 680, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 855, in exec_module
  File "<frozen importlib._bootstrap>", line 228, in _call_with_frames_removed
  File "/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/site-packages/autodocsumm/__init__.py", line 43, in <module>
    from sphinx.util import force_decode
ImportError: cannot import name 'force_decode' from 'sphinx.util' (/opt/hostedtoolcache/Python/3.9.5/x64/lib/python3.9/site-packages/sphinx/util/__init__.py)

Sphinx Warning on Directive Name Collision

SphinxWarning: while setting up extension autodocsumm: directive 'autoclass' is already registered, it will be overridden