From 62ac59ac496b5558e87c35fadf9b62fe30e9a36f Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Sun, 24 May 2020 22:31:28 -0600 Subject: [PATCH 1/2] Permit putting class members on 'stub' pages --- .gitignore | 1 + sphinx_automodapi/automodapi.py | 2 +- sphinx_automodapi/automodsumm.py | 25 ++++++++-- .../{class.rst => class-flat.rst} | 0 .../autosummary_core/class-stubs.rst | 46 +++++++++++++++++++ 5 files changed, 68 insertions(+), 6 deletions(-) rename sphinx_automodapi/templates/autosummary_core/{class.rst => class-flat.rst} (100%) create mode 100644 sphinx_automodapi/templates/autosummary_core/class-stubs.rst diff --git a/.gitignore b/.gitignore index 8f9b3ad..4a29fba 100644 --- a/.gitignore +++ b/.gitignore @@ -33,6 +33,7 @@ develop-eggs distribute-*.tar.gz # Other +.vimsession .cache .tox .*.swp diff --git a/sphinx_automodapi/automodapi.py b/sphinx_automodapi/automodapi.py index 411e7b1..4c700c3 100644 --- a/sphinx_automodapi/automodapi.py +++ b/sphinx_automodapi/automodapi.py @@ -434,7 +434,7 @@ def setup(app): from . import automodsumm app.setup_extension(automodsumm.__name__) - app.connect('source-read', process_automodapi) + app.connect('source-read', process_automodapi, priority=100) app.add_config_value('automodapi_inheritance_diagram', True, True) app.add_config_value('automodapi_toctreedirnm', 'api', True) diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index 61525eb..c6fc6fe 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -55,6 +55,12 @@ actually used by sphinx, so this option is only for figuring out the cause of sphinx warnings or other debugging. Defaults to ``False``. +* ``automodsumm_stub_pages`` + Should be a bool, and if ``True``, will cause `automodsumm`_ to + generate individual stub pages for class attributes and class methods + rather than documenting all class methods and attributes on the same + page. Defaults to ``False``. + * ``automodsumm_inherited_members`` Should be a bool and if ``True``, will cause `automodsumm`_ to document class members that are inherited from a base class. This value can be @@ -266,10 +272,13 @@ def process_automodsumm_generation(app): for sfn, lines in zip(filestosearch, liness): suffix = os.path.splitext(sfn)[1] if len(lines) > 0: - generate_automodsumm_docs( + new_files = generate_automodsumm_docs( lines, sfn, app=app, builder=app.builder, suffix=suffix, base_path=app.srcdir, + stub_pages=app.config.automodsumm_stub_pages, inherited_members=app.config.automodsumm_inherited_members) + for f in new_files: + env.found_docs.add(env.path2doc(f)) # _automodsummrex = re.compile(r'^(\s*)\.\. automodsumm::\s*([A-Za-z0-9_.]+)\s*' @@ -408,6 +417,7 @@ def automodsumm_to_autosummary_lines(fn, app): def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst', base_path=None, builder=None, template_dir=None, + stub_pages=False, inherited_members=False): """ This function is adapted from @@ -487,11 +497,11 @@ def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst', fn = os.path.join(path, name + suffix) # skip it if it exists + # always add to new_files so we can add them to env.found_docs + new_files.append(fn) if os.path.isfile(fn): continue - new_files.append(fn) - f = open(fn, 'w') try: @@ -502,8 +512,11 @@ def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst', template = template_env.get_template(template_name) else: tmplstr = 'autosummary_core/%s.rst' + tmplname = doc.objtype + if tmplname == 'class': + tmplname = 'class-stubs' if stub_pages else 'class-flat' try: - template = template_env.get_template(tmplstr % doc.objtype) + template = template_env.get_template(tmplstr % tmplname) except TemplateNotFound: template = template_env.get_template(tmplstr % 'base') @@ -649,6 +662,7 @@ def get_members_class(obj, typ, include_public=[], finally: f.close() + return new_files def setup(app): @@ -663,9 +677,10 @@ def setup(app): app.add_directive('automod-diagram', Automoddiagram) app.add_directive('automodsumm', Automodsumm) - app.connect('builder-inited', process_automodsumm_generation) + app.connect('builder-inited', process_automodsumm_generation, priority=100) app.add_config_value('automodsumm_writereprocessed', False, True) + app.add_config_value('automodsumm_stub_pages', False, 'env') app.add_config_value('automodsumm_inherited_members', False, 'env') return {'parallel_read_safe': True, diff --git a/sphinx_automodapi/templates/autosummary_core/class.rst b/sphinx_automodapi/templates/autosummary_core/class-flat.rst similarity index 100% rename from sphinx_automodapi/templates/autosummary_core/class.rst rename to sphinx_automodapi/templates/autosummary_core/class-flat.rst diff --git a/sphinx_automodapi/templates/autosummary_core/class-stubs.rst b/sphinx_automodapi/templates/autosummary_core/class-stubs.rst new file mode 100644 index 0000000..e6994f8 --- /dev/null +++ b/sphinx_automodapi/templates/autosummary_core/class-stubs.rst @@ -0,0 +1,46 @@ +{% if referencefile %} +.. include:: {{ referencefile }} +{% endif %} + +{{ objname }} +{{ underline }} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :show-inheritance: + + {% if '__init__' in methods %} + {% set caught_result = methods.remove('__init__') %} + {% endif %} + + {% block attributes_summary %} + {% if attributes %} + + .. rubric:: Attributes Summary + + .. autosummary:: + :toctree: + :template: base.rst + {% for item in attributes %} + ~{{ name }}.{{ item }} + {%- endfor %} + + {% endif %} + {% endblock %} + + {% block methods_summary %} + {% if methods %} + + .. rubric:: Methods Summary + + .. autosummary:: + :toctree: + :template: base.rst + {% for item in methods %} + ~{{ name }}.{{ item }} + {%- endfor %} + + {% endif %} + {% endblock %} + From e80971acbde2a7027beda4a08d2ca040d3c417d5 Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Sun, 24 May 2020 23:36:24 -0600 Subject: [PATCH 2/2] Ensure autosummary sees the automodsumm templates --- sphinx_automodapi/automodsumm.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index c6fc6fe..ebc7677 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -444,7 +444,13 @@ def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst', template_dirs = [os.path.join(os.path.dirname(__file__), 'templates'), os.path.join(base_path, '_templates')] if builder is not None: - # allow the user to override the templates + # allow the user to override the templates and ensure class stub + # pages read the automodsumm base.rst + # TODO: Will this override user base.rst files? + local_dir_full = os.path.join(template_dirs[0], 'autosummary_core') + templates_path = builder.config.templates_path + if local_dir_full not in templates_path: + templates_path.append(local_dir_full) template_loader = BuiltinTemplateLoader() template_loader.init(builder, dirs=template_dirs) else: