IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

[autosummary] address code review

Browse Source
This commit is contained in:
woutdenolf 2019-04-07 11:43:22 +02:00
parent 4004dd5635
commit 6e0b0517c0
6 changed files with 35 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
doc/usage/extensions/autosummary.rst
View File

@ -25,9 +25,9 @@ The :mod:`sphinx.ext.autosummary` extension does this in three parts:
These files by default contain only the corresponding
:mod:`sphinx.ext.autodoc` directive, but can be customized with templates.
3. Optionally, the new :confval:`autosummary_recursion_limit` config value can be
used to generate "stub" files recursively for packages. Warning: this will overwrite
existing files for packages.
3. Optionally, :confval:`autosummary_depth_limit` config value can be
used to generate "stub" files of modules and sub-packages for packages
under the :rst:dir:`autosummary` directive.
.. rst:directive:: autosummary
@ -59,27 +59,6 @@ The :mod:`sphinx.ext.autosummary` extension does this in three parts:
.. currentmodule:: sphinx.ext.autosummary
When :confval:`autosummary_recursion_limit != 0`, the :rst:dir:`autosummary`
directive recursively generates stub ``.rst`` files for packages.
For example, ::
.. currentmodule:: sphinx
.. autosummary::
autosummary
produces a table like this:
.. currentmodule:: sphinx.ext
.. autosummary::
autosummary
.. currentmodule:: sphinx.ext.autosummary
Autosummary preprocesses the docstrings and signatures with the same
:event:`autodoc-process-docstring` and :event:`autodoc-process-signature`
hooks as :mod:`~sphinx.ext.autodoc`.
@ -169,17 +148,16 @@ also use these config values:
The new files will be placed in the directories specified in the
``:toctree:`` options of the directives.
Packages can be explored recursively when generating stub pages.
.. confval:: autosummary_depth_limit
.. confval:: autosummary_recursion_limit
Integer that determines the maximal recursion depth.
Integer that determines the maximal depth (starting from root) when adding
modules and sub-packages of packages.
- ``autosummary_recursion_limit = -1``: no recursion limit
- ``autosummary_recursion_limit = 0``: disable recursion (default)
- ``autosummary_recursion_limit > 0``: limit recursion depth
- ``autosummary_depth_limit = -1``: no limit
- ``autosummary_depth_limit = 0``: disable adding modules and sub-packages (default)
- ``autosummary_depth_limit > 0``: limited depth starting from root
.. versionadded:: 2.0
.. versionadded:: 2.1
.. confval:: autosummary_mock_imports
@ -284,14 +262,14 @@ The following variables available in the templates:
List containing names of "public" modules in the package. Only available for
modules that are packages.
.. versionadded:: 2.0
.. versionadded:: 2.1
.. data:: packages
List containing names of "public" sub-packages in the package. Only available for
modules that are packages.
.. versionadded:: 2.0
.. versionadded:: 2.1
Additionally, the following filters are available

3
sphinx/__main__.py
View File

@ -12,5 +12,4 @@ import sys
from sphinx.cmd.build import main
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
sys.exit(main(sys.argv[1:]))

7
sphinx/ext/autosummary/__init__.py
View File

@ -733,14 +733,13 @@ def process_generate_options(app):
'But your source_suffix does not contain .rst. Skipped.'))
return
recursion_limit = app.config.autosummary_recursion_limit
depth_limit = app.config.autosummary_depth_limit
with mock(app.config.autosummary_mock_imports):
generate_autosummary_docs(genfiles, builder=app.builder,
warn=logger.warning, info=logger.info,
suffix=suffix, base_path=app.srcdir,
recursion_limit=recursion_limit,
app=app)
app=app, depth_limit=depth_limit)
def setup(app):
@ -764,7 +763,7 @@ def setup(app):
app.connect('doctree-read', process_autosummary_toc)
app.connect('builder-inited', process_generate_options)
app.add_config_value('autosummary_generate', [], True, [bool])
app.add_config_value('autosummary_recursion_limit', 0, True, [int])
app.add_config_value('autosummary_depth_limit', 0, 'env', [int])
app.add_config_value('autosummary_mock_imports',
lambda config: config.autodoc_mock_imports, 'env')
return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

20
sphinx/ext/autosummary/generate.py
View File

@ -98,8 +98,8 @@ def generate_autosummary_docs(sources, # type: List[str]
builder=None, # type: Builder
template_dir=None, # type: str
imported_members=False, # type: bool
recursion_limit=0, # type: int
app=None # type: Any
app=None, # type: Any
depth_limit=0, # type: int
):
# type: (...) -> None
showed_sources = list(sorted(sources))
@ -163,20 +163,20 @@ def generate_autosummary_docs(sources, # type: List[str]
ispackage = hasattr(obj, '__path__')
if ispackage:
depth = len(name.split('.')) - 1
recurse_package = depth < recursion_limit or recursion_limit < 0
if recurse_package:
add_package_children = depth < depth_limit or depth_limit < 0
if add_package_children:
info(__('[autosummary] add modules/packages from %s') % repr(name))
else:
recurse_package = False
add_package_children = False
fn = os.path.join(path, name + suffix)
# Skip it if it exists and not a package.
if os.path.isfile(fn):
if ispackage and recursion_limit != 0:
if ispackage and depth_limit != 0:
# Overwrite the file because submodules/packages
# could have been added/removed from the package
# or the recursion limit might have changed.
# or the depth limit might have changed.
# Warning: this file could have been created by the user
# in which case it is lost.
warn('[autosummary] overwriting docs of package %s' % (repr(name)))
@ -242,7 +242,7 @@ def generate_autosummary_docs(sources, # type: List[str]
get_members(obj, 'class', imported=imported_members)
ns['exceptions'], ns['all_exceptions'] = \
get_members(obj, 'exception', imported=imported_members)
if recurse_package:
if add_package_children:
ns['modules'], ns['all_modules'] = \
get_package_members(obj, 'module')
ns['packages'], ns['all_packages'] = \
@ -283,7 +283,7 @@ def generate_autosummary_docs(sources, # type: List[str]
base_path=base_path, builder=builder,
template_dir=template_dir,
imported_members=imported_members,
recursion_limit=recursion_limit,
depth_limit=depth_limit,
app=app)
@ -465,7 +465,7 @@ def main(argv=sys.argv[1:]):
'.' + args.suffix,
template_dir=args.templates,
imported_members=args.imported_members,
recursion_limit=args.recursion_limit,
depth_limit=args.depth_limit,
app=app)

3
tests/roots/test-ext-autosummary-package/conf.py
View File

@ -5,6 +5,3 @@ sys.path.insert(0, os.path.abspath('.'))
extensions = ['sphinx.ext.autosummary']
autosummary_generate = True
# The suffix of source filenames.
source_suffix = '.rst'

18
tests/test_ext_autosummary.py
View File

@ -202,12 +202,12 @@ def test_autosummary_generate(app, status, warning):
def _assert_autosummary_generate_package(app):
app.builder.build_all()
# Prepare recursion
# Prepare package exploration
max_depth = 3
recursion_limit = app.config.autosummary_recursion_limit
assert recursion_limit <= max_depth
depth_limit = app.config.autosummary_depth_limit
assert depth_limit <= max_depth
unlimited = recursion_limit < 0
unlimited = depth_limit < 0
# All packages, modules and classes have the same name
package_name = 'package'
@ -270,7 +270,7 @@ def _assert_autosummary_generate_package(app):
modules = []
directories = []
while True:
limit_reached = (depth == recursion_limit) and not unlimited
limit_reached = (depth == depth_limit) and not unlimited
last_package = depth == max_depth
has_packages = not limit_reached and not last_package
has_modules = not limit_reached
@ -319,15 +319,15 @@ def test_autosummary_generate_package(make_app, app_params):
import sphinx.ext.autosummary.generate
logger = sphinx.ext.autosummary.logger
args, kwargs = app_params
confoverrides = {'autosummary_recursion_limit': 0}
confoverrides = {'autosummary_depth_limit': 0}
kwargs['confoverrides'] = confoverrides
# Try different recursion limits
# Try different depth limits
# TODO: going from higher to lower limit
# currently fails because generated files
# are not deleted
for limit in 0, 1, 2, 3, -1:
logger.info('autosummary_recursion_limit = {}'.format(limit))
confoverrides['autosummary_recursion_limit'] = limit
logger.info('autosummary_depth_limit = {}'.format(limit))
confoverrides['autosummary_depth_limit'] = limit
app = make_app(*args, **kwargs)
_assert_autosummary_generate_package(app)
# Cleanup