chilipp / autodocsumm Goto Github PK
View Code? Open in Web Editor NEWExtending your autodoc API docs with a summary
License: Apache License 2.0
Extending your autodoc API docs with a summary
License: Apache License 2.0
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
Setup:
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.
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.
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:
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))
+ /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.
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
[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.*
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
Hi. Thanks for autodocsumm.
Sphinx 5 is out but it is not supported by autodocsumm:
Line 41 in 2839945
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.
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).
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
.
For some reason, RTD installs Sphinx 1.8.5 and doesn't update it
https://readthedocs.org/projects/autodocsumm/builds/13526310/
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)
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 😄
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!
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"""
.. currentmodule:: mymodule.myclass
.. autoclasssumm:: myclass
:autosummary-members:
After upgrading Sphinx from 6.1.2 to 7.2.6 (with autodocsumm 0.2.11), the following warnings are issued while building docs:
autodocsumm/autodocsumm/__init__.py
Line 223 in 7009e5e
RemovedInSphinx80Warning: The tuple interface of ObjectMember is deprecated. Use (obj.__name__, obj.object) instead.
members = [(membername, member) for (membername, member) in members
autodocsumm/autodocsumm/__init__.py
Line 230 in 7009e5e
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:
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
autodocsumm/autodocsumm/__init__.py
Lines 223 to 224 in 7009e5e
Also, I noticed a couple other unrelated deprecation warnings while running the tests (with Sphinx 7.2.6).
Hi,
this package pins sphinx to version >= 2.2, < 8.0
. However, version 8.0 was recently released
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.
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.
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.
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
build
with --no-isolation
I'm using during all processes only locally installed modulesHere 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 ================================================================
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.
+ 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 ================================================================
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.
It is not possible to show inherited attributes and methods in sub class
When autosummary
is used as a directive and not as a directive option, the alignment of the table is centered.
- For :data:`OrT` type:
.. autosummary::
FORWARD_INT
REVERSE_INT
ORIENT_REV
FWDOR_REVOR
- For :data:`IndOrT` type:
.. autosummary::
IND
OR
Is it possible to left-align the table, for example, with an option under autosummary
directive please?
python 3.9.5
sphinx 5.3.0
autodocsumm 0.2.9
furo 2022.9.29
Thank you for your work!
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
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
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.
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:
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.
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.
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.
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'\*')
.
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.
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?
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.
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?
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.
See the failed tests for f36aa77. We're working on it
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
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 :).
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
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
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 =============================================================================
SphinxWarning: while setting up extension autodocsumm: directive 'autoclass' is already registered, it will be overridden
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:
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.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.
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)
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.