From 0b85680ae5e7278ab64d0ce586eeb22f7c85bae9 Mon Sep 17 00:00:00 2001 From: Simon Conseil Date: Wed, 20 Apr 2022 22:51:17 +0200 Subject: [PATCH 1/8] Add option to set :noindex: Fix #130 --- sphinx_automodapi/automodapi.py | 9 +++++++++ sphinx_automodapi/automodsumm.py | 4 +++- .../templates/autosummary_core/class.rst | 3 +++ sphinx_automodapi/utils.py | 11 +++++++++-- 4 files changed, 24 insertions(+), 3 deletions(-) diff --git a/sphinx_automodapi/automodapi.py b/sphinx_automodapi/automodapi.py index f993cf5..a6cd719 100644 --- a/sphinx_automodapi/automodapi.py +++ b/sphinx_automodapi/automodapi.py @@ -63,6 +63,10 @@ documentation. The option ``:inherited-members:`` or ``:no-inherited-members:`` allows the user to overrride the global setting. + * ``:noindex:`` + Propagates the ``noindex`` flag to autodoc. Use it to avoid duplicate + objects warnings. + This extension also adds four sphinx configuration options: @@ -239,6 +243,7 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None, hds = '-^' allowedpkgnms = [] allowothers = False + noindex = False # look for actual options unknownops = [] @@ -266,6 +271,8 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None, inherited_members = False elif opname == 'include-all-objects': allowothers = True + elif opname == 'noindex': + noindex = True else: unknownops.append(opname) @@ -321,6 +328,8 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None, clsfuncoptions = [] if toctreestr: clsfuncoptions.append(toctreestr) + if noindex: + clsfuncoptions.append(':noindex:') if toskip: clsfuncoptions.append(':skip: ' + ','.join(toskip)) if allowedpkgnms: diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index bd6d9f1..a0146bf 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -124,6 +124,7 @@ class Automodsumm(Autosummary): option_spec['allowed-package-names'] = _str_list_converter option_spec['inherited-members'] = flag option_spec['no-inherited-members'] = flag + option_spec['noindex'] = flag def run(self): env = self.state.document.settings.env @@ -457,7 +458,7 @@ def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst', new_files = [] # write - for name, path, template_name, inherited_mem in sorted(items): + for name, path, template_name, inherited_mem, noindex in sorted(items): if path is None: # The corresponding autosummary:: directive did not have @@ -601,6 +602,7 @@ def get_members_class(obj, typ, include_public=[], else: mod_name, obj_name = '.'.join(parts[:-1]), parts[-1] + ns['noindex'] = noindex ns['fullname'] = name ns['module'] = mod_name ns['objname'] = obj_name diff --git a/sphinx_automodapi/templates/autosummary_core/class.rst b/sphinx_automodapi/templates/autosummary_core/class.rst index 85105fa..198d04b 100644 --- a/sphinx_automodapi/templates/autosummary_core/class.rst +++ b/sphinx_automodapi/templates/autosummary_core/class.rst @@ -9,6 +9,9 @@ .. autoclass:: {{ objname }} :show-inheritance: + {% if noindex -%} + :noindex: + {%- endif %} {% if '__init__' in methods %} {% set caught_result = methods.remove('__init__') %} diff --git a/sphinx_automodapi/utils.py b/sphinx_automodapi/utils.py index f0b1fff..2cab3ad 100644 --- a/sphinx_automodapi/utils.py +++ b/sphinx_automodapi/utils.py @@ -108,7 +108,7 @@ def find_mod_objs(modname, onlylocals=False): def find_autosummary_in_lines_for_automodsumm(lines, module=None, filename=None): """Find out what items appear in autosummary:: directives in the given lines. - Returns a list of (name, toctree, template, inherited_members) + Returns a list of (name, toctree, template, inherited_members, noindex) where *name* is a name of an object and *toctree* the :toctree: path of the corresponding autosummary directive (relative to the root of the file name), @@ -133,12 +133,14 @@ def find_autosummary_in_lines_for_automodsumm(lines, module=None, filename=None) template_arg_re = re.compile(r'^\s+:template:\s*(.*?)\s*$') inherited_members_arg_re = re.compile(r'^\s+:inherited-members:\s*$') no_inherited_members_arg_re = re.compile(r'^\s+:no-inherited-members:\s*$') + noindex_arg_re = re.compile(r'^\s+:noindex:\s*$') documented = [] toctree = None template = None inherited_members = None + noindex = None current_module = module in_autosummary = False base_indent = "" @@ -168,6 +170,11 @@ def find_autosummary_in_lines_for_automodsumm(lines, module=None, filename=None) inherited_members = False continue + m = noindex_arg_re.match(line) + if m: + noindex = True + continue + if line.strip().startswith(':'): warn(line) continue # skip options @@ -181,7 +188,7 @@ def find_autosummary_in_lines_for_automodsumm(lines, module=None, filename=None) not name.startswith(current_module + '.'): name = "%s.%s" % (current_module, name) documented.append((name, toctree, template, - inherited_members)) + inherited_members, noindex)) continue if not line.strip() or line.startswith(base_indent + " "): From da1dbc307fe89aa6ca1f332293daac8c44535549 Mon Sep 17 00:00:00 2001 From: Simon Conseil Date: Fri, 6 May 2022 21:09:58 +0200 Subject: [PATCH 2/8] Remove py2 compat code --- .../tests/example_module/abstract_classes.py | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/sphinx_automodapi/tests/example_module/abstract_classes.py b/sphinx_automodapi/tests/example_module/abstract_classes.py index a5893c3..af1102d 100644 --- a/sphinx_automodapi/tests/example_module/abstract_classes.py +++ b/sphinx_automodapi/tests/example_module/abstract_classes.py @@ -1,10 +1,4 @@ -try: - # Python 3 - from collections.abc import Sequence -except ImportError: - # Python 2 (this import also works in Python <= 3.7, but will be removed in - # Python 3.8) - from collections import Sequence +from collections.abc import Sequence __all__ = ['SequenceSubclass'] From 39cd650c86b1c62c1ff0fe8c47070d38e889efe8 Mon Sep 17 00:00:00 2001 From: Simon Conseil Date: Fri, 6 May 2022 22:21:22 +0200 Subject: [PATCH 3/8] Add test --- .../tests/duplicated_warning/docs/conf.py | 11 +++++++ .../tests/duplicated_warning/docs/foo.rst | 9 ++++++ .../tests/duplicated_warning/docs/index.rst | 19 ++++++++++++ .../duplicated_warning/duplicated/__init__.py | 6 ++++ .../duplicated/foo/__init__.py | 5 ++++ .../duplicated_warning/duplicated/foo/foo.py | 17 +++++++++++ sphinx_automodapi/tests/test_cases.py | 30 +++++++++++++++++++ 7 files changed, 97 insertions(+) create mode 100644 sphinx_automodapi/tests/duplicated_warning/docs/conf.py create mode 100644 sphinx_automodapi/tests/duplicated_warning/docs/foo.rst create mode 100644 sphinx_automodapi/tests/duplicated_warning/docs/index.rst create mode 100644 sphinx_automodapi/tests/duplicated_warning/duplicated/__init__.py create mode 100644 sphinx_automodapi/tests/duplicated_warning/duplicated/foo/__init__.py create mode 100644 sphinx_automodapi/tests/duplicated_warning/duplicated/foo/foo.py diff --git a/sphinx_automodapi/tests/duplicated_warning/docs/conf.py b/sphinx_automodapi/tests/duplicated_warning/docs/conf.py new file mode 100644 index 0000000..6c97b0d --- /dev/null +++ b/sphinx_automodapi/tests/duplicated_warning/docs/conf.py @@ -0,0 +1,11 @@ +project = 'duplicated' +copyright = '2022, Maximilian Nöthe' +author = 'Maximilian Nöthe' +release = '0.1' + + +extensions = [ + "sphinx_automodapi.automodapi", +] + +html_theme = 'alabaster' diff --git a/sphinx_automodapi/tests/duplicated_warning/docs/foo.rst b/sphinx_automodapi/tests/duplicated_warning/docs/foo.rst new file mode 100644 index 0000000..15c9792 --- /dev/null +++ b/sphinx_automodapi/tests/duplicated_warning/docs/foo.rst @@ -0,0 +1,9 @@ +Foo Submodule +============= + + +API Reference +------------- + +.. automodapi:: sphinx_automodapi.tests.duplicated_warning.duplicated.foo + :noindex: diff --git a/sphinx_automodapi/tests/duplicated_warning/docs/index.rst b/sphinx_automodapi/tests/duplicated_warning/docs/index.rst new file mode 100644 index 0000000..55140c9 --- /dev/null +++ b/sphinx_automodapi/tests/duplicated_warning/docs/index.rst @@ -0,0 +1,19 @@ +.. duplicated documentation master file, created by + sphinx-quickstart on Tue Mar 29 17:11:23 2022. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to duplicated's documentation! +====================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + foo + + +API Reference +------------- + +.. automodapi:: sphinx_automodapi.tests.duplicated_warning.duplicated diff --git a/sphinx_automodapi/tests/duplicated_warning/duplicated/__init__.py b/sphinx_automodapi/tests/duplicated_warning/duplicated/__init__.py new file mode 100644 index 0000000..41d8653 --- /dev/null +++ b/sphinx_automodapi/tests/duplicated_warning/duplicated/__init__.py @@ -0,0 +1,6 @@ +from .foo import Foo + + +__all__ = [ + 'Foo', +] diff --git a/sphinx_automodapi/tests/duplicated_warning/duplicated/foo/__init__.py b/sphinx_automodapi/tests/duplicated_warning/duplicated/foo/__init__.py new file mode 100644 index 0000000..a15a7ef --- /dev/null +++ b/sphinx_automodapi/tests/duplicated_warning/duplicated/foo/__init__.py @@ -0,0 +1,5 @@ +from .foo import Foo + +__all__ = [ + "Foo", +] diff --git a/sphinx_automodapi/tests/duplicated_warning/duplicated/foo/foo.py b/sphinx_automodapi/tests/duplicated_warning/duplicated/foo/foo.py new file mode 100644 index 0000000..c48bbf3 --- /dev/null +++ b/sphinx_automodapi/tests/duplicated_warning/duplicated/foo/foo.py @@ -0,0 +1,17 @@ +__all__ = [ + 'Foo', + 'Bar', + 'baz', +] + + +class Foo: + '''Awesome Foo class''' + + +class Bar: + '''Awesome Bar class''' + + +def baz(): + '''Aweomse baz function''' diff --git a/sphinx_automodapi/tests/test_cases.py b/sphinx_automodapi/tests/test_cases.py index 351e388..161dc32 100644 --- a/sphinx_automodapi/tests/test_cases.py +++ b/sphinx_automodapi/tests/test_cases.py @@ -115,3 +115,33 @@ def test_run_full_case(tmpdir, case_dir, parallel): with open(path_reference, encoding='utf8') as f: reference = f.read() assert actual.strip() == reference.strip() + + +def test_duplicated_warning(tmpdir): + input_dir = os.path.join(os.path.dirname(__file__), 'duplicated_warning', 'docs') + docs_dir = tmpdir.mkdir('docs').strpath + + conf = deepcopy(DEFAULT_CONF) + conf.update({'automodapi_toctreedirnm': 'api', + 'automodapi_writereprocessed': True, + 'automodsumm_writereprocessed': True}) + + start_dir = os.path.abspath('.') + src_dir = '.' + + for root, dirnames, filenames in os.walk(input_dir): + for filename in filenames: + root_dir = os.path.join(docs_dir, os.path.relpath(root, input_dir)) + ensuredir(root_dir) + input_file = os.path.join(root, filename) + shutil.copy(input_file, root_dir) + + argv = ['-W', '-b', 'html', src_dir, '_build/html'] + + try: + os.chdir(docs_dir) + status = build_main(argv=argv) + finally: + os.chdir(start_dir) + + assert status == 0 From 6f68814873414fe355c261557afc47a0bd168a8a Mon Sep 17 00:00:00 2001 From: Simon Conseil Date: Fri, 6 May 2022 22:38:21 +0200 Subject: [PATCH 4/8] Fix package discovery --- sphinx_automodapi/tests/duplicated_warning/__init__.py | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 sphinx_automodapi/tests/duplicated_warning/__init__.py diff --git a/sphinx_automodapi/tests/duplicated_warning/__init__.py b/sphinx_automodapi/tests/duplicated_warning/__init__.py new file mode 100644 index 0000000..e69de29 From 209ec821232053ea35c6f0df43a1bfe0a39a7870 Mon Sep 17 00:00:00 2001 From: Simon Conseil Date: Fri, 6 May 2022 22:38:38 +0200 Subject: [PATCH 5/8] Cleanup --- sphinx_automodapi/tests/test_cases.py | 5 ----- 1 file changed, 5 deletions(-) diff --git a/sphinx_automodapi/tests/test_cases.py b/sphinx_automodapi/tests/test_cases.py index 161dc32..63b0171 100644 --- a/sphinx_automodapi/tests/test_cases.py +++ b/sphinx_automodapi/tests/test_cases.py @@ -121,11 +121,6 @@ def test_duplicated_warning(tmpdir): input_dir = os.path.join(os.path.dirname(__file__), 'duplicated_warning', 'docs') docs_dir = tmpdir.mkdir('docs').strpath - conf = deepcopy(DEFAULT_CONF) - conf.update({'automodapi_toctreedirnm': 'api', - 'automodapi_writereprocessed': True, - 'automodsumm_writereprocessed': True}) - start_dir = os.path.abspath('.') src_dir = '.' From d097d38e4aba7ba22067f2bde8b47c31320a866b Mon Sep 17 00:00:00 2001 From: Simon Conseil Date: Fri, 6 May 2022 22:43:52 +0200 Subject: [PATCH 6/8] Include test files --- setup.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.cfg b/setup.cfg index 0dfbcc6..4886f2c 100644 --- a/setup.cfg +++ b/setup.cfg @@ -32,7 +32,7 @@ test = [options.package_data] sphinx_automodapi = templates/*/*.rst -sphinx_automodapi.tests = cases/*/*.*, cases/*/*/*.*, cases/*/*/*/*.*, cases/*/*/*/*/*.* +sphinx_automodapi.tests = cases/*/*.*, cases/*/*/*.*, cases/*/*/*/*.*, cases/*/*/*/*/*.*, duplicated_warning/docs/* [tool:pytest] minversion = 4.6 From e8bc34ca9c43688314a00ca0b1035dc677b7eeee Mon Sep 17 00:00:00 2001 From: "P. L. Lim" <2090236+pllim@users.noreply.github.com> Date: Fri, 9 Dec 2022 12:11:36 -0500 Subject: [PATCH 7/8] Typos --- sphinx_automodapi/tests/duplicated_warning/docs/conf.py | 4 ++-- .../tests/duplicated_warning/duplicated/foo/foo.py | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/sphinx_automodapi/tests/duplicated_warning/docs/conf.py b/sphinx_automodapi/tests/duplicated_warning/docs/conf.py index 6c97b0d..b3a40ef 100644 --- a/sphinx_automodapi/tests/duplicated_warning/docs/conf.py +++ b/sphinx_automodapi/tests/duplicated_warning/docs/conf.py @@ -1,6 +1,6 @@ project = 'duplicated' -copyright = '2022, Maximilian Nöthe' -author = 'Maximilian Nöthe' +copyright = '2022, Maximilian Linhoff' +author = 'Maximilian Linhoff' release = '0.1' diff --git a/sphinx_automodapi/tests/duplicated_warning/duplicated/foo/foo.py b/sphinx_automodapi/tests/duplicated_warning/duplicated/foo/foo.py index c48bbf3..c706ea3 100644 --- a/sphinx_automodapi/tests/duplicated_warning/duplicated/foo/foo.py +++ b/sphinx_automodapi/tests/duplicated_warning/duplicated/foo/foo.py @@ -14,4 +14,4 @@ class Bar: def baz(): - '''Aweomse baz function''' + '''Awesome baz function''' From db8636234a5466b9e23852ae2eb17f22e2d1a46e Mon Sep 17 00:00:00 2001 From: "P. L. Lim" <2090236+pllim@users.noreply.github.com> Date: Fri, 9 Dec 2022 12:36:27 -0500 Subject: [PATCH 8/8] Comment out language = None --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index c453cc2..96b1ffc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -38,7 +38,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +#language = None # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files.