From 12ae045a7b36f7ec5b7e6e5e1f8e703a57ceb8dc Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Sat, 14 Sep 2019 16:14:36 -0600 Subject: [PATCH 01/19] Include certain builtin class methods and ignore class methods with empty docstrings --- .gitignore | 1 + README.rst | 3 +++ setup.cfg | 4 ++-- sphinx_automodapi/automodsumm.py | 29 ++++++++++++++++++++++------- 4 files changed, 28 insertions(+), 9 deletions(-) diff --git a/.gitignore b/.gitignore index 8f9b3ad..78caebd 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ *.so *.pyd __pycache__ +.vimsession # Ignore .c files by default to avoid including generated code. If you want to # add a non-generated .c extension, use `git add -f filename.c`. diff --git a/README.rst b/README.rst index 48c0f11..d95caef 100644 --- a/README.rst +++ b/README.rst @@ -9,6 +9,9 @@ available as a standalone package since it can be used for any other package. The documentation can be found on `ReadTheDocs `_. +This extension was forked from the Astropy project for use with the ProPlot project, in order to change a few hard-coded settings that could not be changed with the existing API. + + Running tests ------------- diff --git a/setup.cfg b/setup.cfg index 1db3624..27197c3 100644 --- a/setup.cfg +++ b/setup.cfg @@ -3,8 +3,8 @@ name = sphinx-automodapi version = attr:sphinx_automodapi.__version__ description = Sphinx extension for auto-generating API documentation for entire modules long_description = file:README.rst -author = The Astropy Developers -author_email = astropy.team@gmail.com +author = Repo from The Astropy Developers, forked by Luke Davis +author_email = astropy.team@gmail.com, lukelbd@gmail.com license = BSD 3-Clause License url = http://astropy.org classifiers = diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index 61525eb..37f4b99 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -99,6 +99,10 @@ class members that are inherited from a base class. This value can be __all__ = ['Automoddiagram', 'Automodsumm', 'automodsumm_to_autosummary_lines', 'generate_automodsumm_docs', 'process_automodsumm_generation'] +api_ignore_methods = [] +api_class_methods = ['__init__', '__call__', '__bool__', '__len__', + '__getitem__', '__setitem__', '__setattr__', + '__getattr__', '__getattribute__'] def _str_list_converter(argument): """ @@ -512,7 +516,14 @@ def get_members_mod(obj, typ, include_public=[]): typ = None -> all """ items = [] + # Add back? Seems fragile to rely on automodapi to ignore + # random variables you declare or classes you import on the + # top-level module. Better to use the :skip: directive *or* + # omit objects from __all__. for name in dir(obj): + # docstring = getattr(safe_getattr(obj, name), '__doc__') + # if not docstring and typ in ('function', 'class', 'exception'): + # continue try: documenter = get_documenter(app, safe_getattr(obj, name), obj) except AttributeError: @@ -523,7 +534,7 @@ def get_members_mod(obj, typ, include_public=[]): if x in include_public or not x.startswith('_')] return public, items - def get_members_class(obj, typ, include_public=[], + def get_members_class(obj, typ, include_public=[], exclude_public=[], include_base=False): """ typ = None -> all @@ -552,19 +563,24 @@ def get_members_class(obj, typ, include_public=[], else: names = getattr(obj, '__dict__').keys() + # Modification here, only document something if it has a + # docstring! Do not inherit if empty, similar to + # :inherited-members: option for name in names: try: documenter = get_documenter(app, safe_getattr(obj, name), obj) except AttributeError: continue + if documenter.objtype == 'method' and not getattr(safe_getattr(obj, name), '__doc__', ''): + continue if typ is None or documenter.objtype == typ: items.append(name) elif typ == 'attribute' and documenter.objtype == 'property': # In Sphinx 2.0 and above, properties have a separate # objtype, but we treat them the same here. items.append(name) - public = [x for x in items - if x in include_public or not x.startswith('_')] + public = [x for x in items if x not in exclude_public and + (x in include_public or not x.startswith('_'))] return public, items ns = {} @@ -585,17 +601,16 @@ def get_members_class(obj, typ, include_public=[], # use default value include_base = inherited_members - api_class_methods = ['__init__', '__call__'] ns['members'] = get_members_class(obj, None, include_base=include_base) ns['methods'], ns['all_methods'] = \ - get_members_class(obj, 'method', api_class_methods, + get_members_class(obj, 'method', api_class_methods, api_ignore_methods, include_base=include_base) ns['attributes'], ns['all_attributes'] = \ get_members_class(obj, 'attribute', include_base=include_base) - ns['methods'].sort() - ns['attributes'].sort() + ns['methods'] = sorted(ns['methods']) + ns['attributes'] = sorted(ns['attributes']) parts = name.split('.') if doc.objtype in ('method', 'attribute'): From fd7bd101d091fcf13a31db794cf286e6f5fbd7b5 Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Sun, 15 Sep 2019 22:47:52 -0600 Subject: [PATCH 02/19] Support *stub pages* (:toctree:) for class method docs, enforce automodsumm before automodapi in sphinx event queue Debug readthedocs Testing Testing Fix --- sphinx_automodapi/automodsumm.py | 37 ++++++++++++++++--- .../autosummary_core/autosummary.rst | 22 +++++++++++ .../templates/autosummary_core/class.rst | 27 ++------------ 3 files changed, 57 insertions(+), 29 deletions(-) create mode 100644 sphinx_automodapi/templates/autosummary_core/autosummary.rst diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index 37f4b99..7bb45a5 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -100,9 +100,10 @@ class members that are inherited from a base class. This value can be 'generate_automodsumm_docs', 'process_automodsumm_generation'] api_ignore_methods = [] -api_class_methods = ['__init__', '__call__', '__bool__', '__len__', - '__getitem__', '__setitem__', '__setattr__', - '__getattr__', '__getattribute__'] +api_class_methods = [ + '__init__', '__call__', # default + '__getitem__', '__setitem__', '__setattr__', '__getattr__', # custom + ] def _str_list_converter(argument): """ @@ -270,10 +271,12 @@ 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, 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*' @@ -435,10 +438,17 @@ def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst', # Create our own templating environment - here we use Astropy's # templates rather than the default autosummary templates, in order to # allow docstrings to be shown for methods. - template_dirs = [os.path.join(os.path.dirname(__file__), 'templates'), - os.path.join(base_path, '_templates')] + local_dir = os.path.join(os.path.dirname(__file__), 'templates') + default_dir = os.path.join(base_path, '_templates') + template_dirs = [local_dir, default_dir] if builder is not None: # allow the user to override the templates + # also add to the templates_path + # TODO: messes up usage for some users? for time being IDGAF + local_dir_full = os.path.join(local_dir, 'autosummary_core') + templates_path = builder.config.templates_path + if local_dir_full not in templates_path: + templates_path.insert(0, local_dir_full) template_loader = BuiltinTemplateLoader() template_loader.init(builder, dirs=template_dirs) else: @@ -664,6 +674,7 @@ def get_members_class(obj, typ, include_public=[], exclude_public=[], finally: f.close() + return new_files def setup(app): @@ -680,6 +691,20 @@ def setup(app): app.add_directive('automodsumm', Automodsumm) app.connect('builder-inited', process_automodsumm_generation) + # insert event *before* the autosummary hook so autosummary will read + # from the updated app.builder.env.found_docs attribute + # try to use as much of API as possible here + from sphinx.ext.autosummary import process_generate_options + listener_id = None + for lid, func in app.events.listeners['builder-inited'].items(): + if func is process_generate_options: + listener_id = lid + break + if listener_id is not None: + app.disconnect(listener_id) + app.connect('builder-inited', process_generate_options) + + # original app.add_config_value('automodsumm_writereprocessed', False, True) app.add_config_value('automodsumm_inherited_members', False, 'env') diff --git a/sphinx_automodapi/templates/autosummary_core/autosummary.rst b/sphinx_automodapi/templates/autosummary_core/autosummary.rst new file mode 100644 index 0000000..5678037 --- /dev/null +++ b/sphinx_automodapi/templates/autosummary_core/autosummary.rst @@ -0,0 +1,22 @@ +{{ objname }} +{{ underline }} + + +.. currentmodule:: {{ module }} + + +{% if objtype in ['class'] %} +.. auto{{ objtype }}:: {{ objname }} + :show-inheritance: + +{% else %} +.. auto{{ objtype }}:: {{ objname }} + +{% endif %} + +{% if objtype in ['class', 'method', 'function'] %} +.. raw:: html + +
+ +{% endif %} diff --git a/sphinx_automodapi/templates/autosummary_core/class.rst b/sphinx_automodapi/templates/autosummary_core/class.rst index 85105fa..e6994f8 100644 --- a/sphinx_automodapi/templates/autosummary_core/class.rst +++ b/sphinx_automodapi/templates/autosummary_core/class.rst @@ -20,6 +20,8 @@ .. rubric:: Attributes Summary .. autosummary:: + :toctree: + :template: base.rst {% for item in attributes %} ~{{ name }}.{{ item }} {%- endfor %} @@ -33,6 +35,8 @@ .. rubric:: Methods Summary .. autosummary:: + :toctree: + :template: base.rst {% for item in methods %} ~{{ name }}.{{ item }} {%- endfor %} @@ -40,26 +44,3 @@ {% endif %} {% endblock %} - {% block attributes_documentation %} - {% if attributes %} - - .. rubric:: Attributes Documentation - - {% for item in attributes %} - .. autoattribute:: {{ item }} - {%- endfor %} - - {% endif %} - {% endblock %} - - {% block methods_documentation %} - {% if methods %} - - .. rubric:: Methods Documentation - - {% for item in methods %} - .. automethod:: {{ item }} - {%- endfor %} - - {% endif %} - {% endblock %} From bacc492abce7af3dcdc467cdfb8535d9bead9e8f Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Sun, 15 Sep 2019 23:44:56 -0600 Subject: [PATCH 03/19] Update version --- sphinx_automodapi/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx_automodapi/__init__.py b/sphinx_automodapi/__init__.py index d5b0ac1..97f3763 100644 --- a/sphinx_automodapi/__init__.py +++ b/sphinx_automodapi/__init__.py @@ -1 +1 @@ -__version__ = '0.13.dev0' +__version__ = '0.1.proplot-mods' From 47abc7cd79d3ff5e0c7dbcc2932d5cfccd0c1efd Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Sun, 15 Sep 2019 23:49:52 -0600 Subject: [PATCH 04/19] Update readme --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index d95caef..1a5661b 100644 --- a/README.rst +++ b/README.rst @@ -9,7 +9,7 @@ available as a standalone package since it can be used for any other package. The documentation can be found on `ReadTheDocs `_. -This extension was forked from the Astropy project for use with the ProPlot project, in order to change a few hard-coded settings that could not be changed with the existing API. +This extension was forked from the Astropy project for use with the ProPlot project, in order to change a few hard-coded settings that could not be changed with the existing API. ProPlot documentation can also be found on `ReadTheDocs `_. Running tests From cfe7fafbadb8b8a2c8fa636289492571e3ed6f76 Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Sun, 15 Sep 2019 23:52:57 -0600 Subject: [PATCH 05/19] Increment version --- sphinx_automodapi/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx_automodapi/__init__.py b/sphinx_automodapi/__init__.py index 97f3763..61b79c7 100644 --- a/sphinx_automodapi/__init__.py +++ b/sphinx_automodapi/__init__.py @@ -1 +1 @@ -__version__ = '0.1.proplot-mods' +__version__ = '0.2.proplot-mods' From a148ac75df1de625d66c7804388ed979627eb9d3 Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Mon, 16 Sep 2019 00:03:01 -0600 Subject: [PATCH 06/19] Increment version --- sphinx_automodapi/__init__.py | 2 +- sphinx_automodapi/automodsumm.py | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/sphinx_automodapi/__init__.py b/sphinx_automodapi/__init__.py index 61b79c7..7b4d905 100644 --- a/sphinx_automodapi/__init__.py +++ b/sphinx_automodapi/__init__.py @@ -1 +1 @@ -__version__ = '0.2.proplot-mods' +__version__ = '0.2.1.proplot-mods' diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index 7bb45a5..4adb8af 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -275,6 +275,7 @@ def process_automodsumm_generation(app): lines, sfn, app=app, builder=app.builder, suffix=suffix, base_path=app.srcdir, inherited_members=app.config.automodsumm_inherited_members) + print('NEW FILES!', new_files) for f in new_files: env.found_docs.add(env.path2doc(f)) From 628299bc1f5967e0941e97b5df361758c142f212 Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Mon, 16 Sep 2019 00:07:44 -0600 Subject: [PATCH 07/19] Debug edit --- sphinx_automodapi/automodsumm.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index 4adb8af..917ca2e 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -268,6 +268,7 @@ def process_automodsumm_generation(app): f.write(l) f.write('\n') + logger = logging.getLogger(__name__) for sfn, lines in zip(filestosearch, liness): suffix = os.path.splitext(sfn)[1] if len(lines) > 0: @@ -275,7 +276,8 @@ def process_automodsumm_generation(app): lines, sfn, app=app, builder=app.builder, suffix=suffix, base_path=app.srcdir, inherited_members=app.config.automodsumm_inherited_members) - print('NEW FILES!', new_files) + logger.info('New files: ' + ', '.join(os.path.basenam(file) + for file in new_files)) for f in new_files: env.found_docs.add(env.path2doc(f)) From e3ce5801781ad3534360235c62bd8534a591f90e Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Mon, 16 Sep 2019 00:11:25 -0600 Subject: [PATCH 08/19] Fix issue with empty new_files Update version Bugfix --- sphinx_automodapi/__init__.py | 2 +- sphinx_automodapi/automodsumm.py | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/sphinx_automodapi/__init__.py b/sphinx_automodapi/__init__.py index 7b4d905..a7af69a 100644 --- a/sphinx_automodapi/__init__.py +++ b/sphinx_automodapi/__init__.py @@ -1 +1 @@ -__version__ = '0.2.1.proplot-mods' +__version__ = '0.3.proplot-mods' diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index 917ca2e..66fe770 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -276,7 +276,7 @@ def process_automodsumm_generation(app): lines, sfn, app=app, builder=app.builder, suffix=suffix, base_path=app.srcdir, inherited_members=app.config.automodsumm_inherited_members) - logger.info('New files: ' + ', '.join(os.path.basenam(file) + logger.info('Files: ' + ', '.join(os.path.basename(file) for file in new_files)) for f in new_files: env.found_docs.add(env.path2doc(f)) @@ -504,11 +504,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: From 7a3d381a18e13194b4c13d83316da8bae1241c17 Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Mon, 16 Sep 2019 00:17:34 -0600 Subject: [PATCH 09/19] Increment version --- sphinx_automodapi/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx_automodapi/__init__.py b/sphinx_automodapi/__init__.py index a7af69a..bceaa25 100644 --- a/sphinx_automodapi/__init__.py +++ b/sphinx_automodapi/__init__.py @@ -1 +1 @@ -__version__ = '0.3.proplot-mods' +__version__ = '0.4.proplot-mods' From 44045ef03575c602236ce73a496064523aa19c33 Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Mon, 16 Sep 2019 00:22:03 -0600 Subject: [PATCH 10/19] Logging --- sphinx_automodapi/automodsumm.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index 66fe770..3a5fdbf 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -276,7 +276,7 @@ def process_automodsumm_generation(app): lines, sfn, app=app, builder=app.builder, suffix=suffix, base_path=app.srcdir, inherited_members=app.config.automodsumm_inherited_members) - logger.info('Files: ' + ', '.join(os.path.basename(file) + logger.info('New files: ' + ', '.join(os.path.basename(file) for file in new_files)) for f in new_files: env.found_docs.add(env.path2doc(f)) From 87a7e9f885a0a87dbe933e6fe68b7494db2aa61f Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Mon, 16 Sep 2019 03:31:46 -0600 Subject: [PATCH 11/19] Stop logging new files Tmp --- sphinx_automodapi/__init__.py | 2 +- sphinx_automodapi/automodsumm.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/sphinx_automodapi/__init__.py b/sphinx_automodapi/__init__.py index bceaa25..251fc0b 100644 --- a/sphinx_automodapi/__init__.py +++ b/sphinx_automodapi/__init__.py @@ -1 +1 @@ -__version__ = '0.4.proplot-mods' +__version__ = '0.5.proplot-mods' diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index 3a5fdbf..5ad9c36 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -276,8 +276,8 @@ def process_automodsumm_generation(app): lines, sfn, app=app, builder=app.builder, suffix=suffix, base_path=app.srcdir, inherited_members=app.config.automodsumm_inherited_members) - logger.info('New files: ' + ', '.join(os.path.basename(file) - for file in new_files)) + # logger.info('New files: ' + ', '.join(os.path.basename(file) + # for file in new_files)) for f in new_files: env.found_docs.add(env.path2doc(f)) From 718d9d37853d46cdbec6c1f4cfce87973ae218dd Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Mon, 16 Sep 2019 19:00:22 -0600 Subject: [PATCH 12/19] Remove unusued autosummary template Tmp Test version increment Version Tag Tag Version Tag New version No version change Test Incr version Test Change Version Version Revert --- sphinx_automodapi/__init__.py | 2 +- .../autosummary_core/autosummary.rst | 22 ------------------- 2 files changed, 1 insertion(+), 23 deletions(-) delete mode 100644 sphinx_automodapi/templates/autosummary_core/autosummary.rst diff --git a/sphinx_automodapi/__init__.py b/sphinx_automodapi/__init__.py index 251fc0b..cd40119 100644 --- a/sphinx_automodapi/__init__.py +++ b/sphinx_automodapi/__init__.py @@ -1 +1 @@ -__version__ = '0.5.proplot-mods' +__version__ = '0.6.proplot-mods' diff --git a/sphinx_automodapi/templates/autosummary_core/autosummary.rst b/sphinx_automodapi/templates/autosummary_core/autosummary.rst deleted file mode 100644 index 5678037..0000000 --- a/sphinx_automodapi/templates/autosummary_core/autosummary.rst +++ /dev/null @@ -1,22 +0,0 @@ -{{ objname }} -{{ underline }} - - -.. currentmodule:: {{ module }} - - -{% if objtype in ['class'] %} -.. auto{{ objtype }}:: {{ objname }} - :show-inheritance: - -{% else %} -.. auto{{ objtype }}:: {{ objname }} - -{% endif %} - -{% if objtype in ['class', 'method', 'function'] %} -.. raw:: html - -
- -{% endif %} From c3b39754181f79a3ca9b83f2c7451ca5ff0e143b Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Sat, 12 Oct 2019 02:10:25 -0600 Subject: [PATCH 13/19] Sync post-commit hook script --- hooks/README.md | 2 ++ hooks/post-commit | 50 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+) create mode 100644 hooks/README.md create mode 100755 hooks/post-commit diff --git a/hooks/README.md b/hooks/README.md new file mode 100644 index 0000000..e6bf4b3 --- /dev/null +++ b/hooks/README.md @@ -0,0 +1,2 @@ +# Git hooks +When you clone this repo, copy the `post-commit` script to `.git/hooks`. This hook tags the commit with a version number if the version string in `__init__.py` was changed. diff --git a/hooks/post-commit b/hooks/post-commit new file mode 100755 index 0000000..b794c25 --- /dev/null +++ b/hooks/post-commit @@ -0,0 +1,50 @@ +#!/usr/bin/env bash +#-----------------------------------------------------------------------------# +# Post commit hook that looks for __version__ variable in __init__.py file, +# compares it to the current tag, and updates the commit if the __version__ was +# also updated. Copy to .git/hooks/post-commit to add this to any project. +# See also: https://stackoverflow.com/a/27332476/4970632 +# See also: https://stackoverflow.com/a/46972376/4970632 +# This is currently very lightweight and assumes workflow where users +# manually increment tag number, which is probably appropriate +#-----------------------------------------------------------------------------# +# Helper +raise() { + echo "Error: $@" + exit 1 +} + +# Bail if we are in middle of rebase +base=$(git rev-parse --show-toplevel) +[ $? -ne 0 ] && raise "Not in git repository." +[ -d $base/.git/rebase-merge ] && exit 0 + +# Get head dir +init=($(git ls-files | grep __init__.py | grep -v 'tests')) +[ ${#init[@]} -eq 0 ] && raise "__init__.py not found." +[ ${#init[@]} -gt 1 ] && raise "Multiple candidates for __init__.py: ${init[@]}" + +# Get version string +version=$(cat $init | grep -E '^version|^__version') +[ -z "$version" ] && raise "$init version string not found." +[ $(echo "$version" | wc -l) -gt 1 ] && raise "Ambiguous version string in $init." +version=$(echo "$version" | awk -F"['\"]" '{print $2}') # first string on line + +# Prompt user action +# NOTE: Currently git suppresses interactivity but that's fine, just means +# default action of adding tag is taken +tag=$(git describe --tags $(git rev-list --tags --max-count=1)) +if [ $? -ne 0 ] || [ "$tag" != "v$version" ]; then + while true; do + read -r -p "Increment tag from $tag --> v$version? ([y]/n) " response + if [ -n "$response" ] && ! [[ "$response" =~ ^[NnYy]$ ]]; then + echo "Invalid response." + continue # invalid, so try again + fi + if ! [[ "$response" =~ ^[Nn]$ ]]; then + git tag "v$version" + [ $? -eq 0 ] && echo "Incremented tag from $tag --> v$version" + fi + break + done +fi From 76e0f51f4416dfbcfa881cc45f39ab5792b7a2a2 Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Sun, 24 Nov 2019 17:37:39 -0700 Subject: [PATCH 14/19] Readme Readme Readme Minor --- README.rst | 8 +++++++- sphinx_automodapi/automodsumm.py | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 1a5661b..afc3c30 100644 --- a/README.rst +++ b/README.rst @@ -9,7 +9,13 @@ available as a standalone package since it can be used for any other package. The documentation can be found on `ReadTheDocs `_. -This extension was forked from the Astropy project for use with the ProPlot project, in order to change a few hard-coded settings that could not be changed with the existing API. ProPlot documentation can also be found on `ReadTheDocs `_. +Proplot modifications +--------------------- +This extension was forked from the Astropy project for use with the `proplot `__ project in order to add some features. The following changes were made: + +* Adds ``__getitem__``, ``__getattr__``, ``__setitem__``, and ``__setattr__`` to the list of builtin methods that are *not* ignored by the documentation generator. +* Skips over class methods that are public, but do *not* have their own ``__doc__`` attributes, to prevent inheriting and displaying documentation from external projects. +* Gives class methods and attributes their own stub pages, instead of putting all class methods and attributes on a single page. This also requires reordering the event hooks so ``sphinx_automodapi`` is called before ``autosummary``, so that ``autosummary`` detects the automatically generated class pages. Running tests diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index 5ad9c36..432a8d4 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -447,7 +447,7 @@ def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst', if builder is not None: # allow the user to override the templates # also add to the templates_path - # TODO: messes up usage for some users? for time being IDGAF + # TODO: messes up usage for some users? local_dir_full = os.path.join(local_dir, 'autosummary_core') templates_path = builder.config.templates_path if local_dir_full not in templates_path: From 3c5889bfe062f646d90ec6678907dba4ade6b6bd Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Sun, 24 Nov 2019 18:30:07 -0700 Subject: [PATCH 15/19] Readme --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index afc3c30..1be7ff7 100644 --- a/README.rst +++ b/README.rst @@ -15,7 +15,7 @@ This extension was forked from the Astropy project for use with the `proplot Date: Sun, 24 Nov 2019 18:32:09 -0700 Subject: [PATCH 16/19] Readme --- README.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 1be7ff7..dae06bd 100644 --- a/README.rst +++ b/README.rst @@ -11,11 +11,11 @@ package. The documentation can be found on Proplot modifications --------------------- -This extension was forked from the Astropy project for use with the `proplot `__ project in order to add some features. The following changes were made: +Not sure if you guys will necessarily want to merge this as it changes some core behavior, but I forked this for use with my `proplot `__ project and added the following features: -* Adds ``__getitem__``, ``__getattr__``, ``__setitem__``, and ``__setattr__`` to the list of builtin methods that are *not* ignored by the documentation generator. -* Skips over class methods that are public, but do *not* have their own ``__doc__`` attributes, to prevent inheriting and displaying documentation from external projects. -* Gives class methods and attributes their own stub pages, instead of putting all class methods and attributes on a single page. This also requires adding the new files to ``env.found_docs`` and reordering the event hooks so ``sphinx_automodapi`` is called before ``autosummary``. This way ``autosummary`` will read the automatically generated class pages and generate the corresponding stubs. +* Skip over class methods that are public, but do *not* have their own ``__doc__`` attributes. This prevents inheriting and displaying documentation from external projects, namely matplotlib. +* Include ``__getitem__``, ``__getattr__``, ``__setitem__``, and ``__setattr__`` in the list of builtin methods that are *not* ignored by the documentation generator. I use these to document some dictionary/list subclasses. +* Give class methods and attributes their own stub pages, instead of putting all class methods and attributes on a single page. This also required adding the new files to ``env.found_docs`` and reordering the event hooks in ``automodsumm.py`` so that ``sphinx_automodapi`` is called before ``autosummary``. This way ``autosummary`` sees the new class pages and can build the appropriate stubs. Running tests From 68094811793c5af7be206669846c772f770aeaf6 Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Sun, 24 Nov 2019 18:34:27 -0700 Subject: [PATCH 17/19] Readme --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index dae06bd..1be3b0d 100644 --- a/README.rst +++ b/README.rst @@ -11,7 +11,7 @@ package. The documentation can be found on Proplot modifications --------------------- -Not sure if you guys will necessarily want to merge this as it changes some core behavior, but I forked this for use with my `proplot `__ project and added the following features: +I forked this repo for use with my `proplot `__ project and added the following features: * Skip over class methods that are public, but do *not* have their own ``__doc__`` attributes. This prevents inheriting and displaying documentation from external projects, namely matplotlib. * Include ``__getitem__``, ``__getattr__``, ``__setitem__``, and ``__setattr__`` in the list of builtin methods that are *not* ignored by the documentation generator. I use these to document some dictionary/list subclasses. From 3c5ec4b6bfd9baaf5d6429d6d65e48da5671e8a7 Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Tue, 5 May 2020 00:47:35 -0600 Subject: [PATCH 18/19] Event insert bugfix --- sphinx_automodapi/automodsumm.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index 432a8d4..5bf8a66 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -699,10 +699,12 @@ def setup(app): # try to use as much of API as possible here from sphinx.ext.autosummary import process_generate_options listener_id = None - for lid, func in app.events.listeners['builder-inited'].items(): - if func is process_generate_options: - listener_id = lid - break + listeners = app.events.listeners['builder-inherited'] + if listeners and isinstance(listeners, dict): # in case API changes + for lid, func in listeners.items(): + if func is process_generate_options: + listener_id = lid + break if listener_id is not None: app.disconnect(listener_id) app.connect('builder-inited', process_generate_options) From f1732dec3aa8a20af4d76cb54cff68e0ea3e6e5c Mon Sep 17 00:00:00 2001 From: Luke Davis Date: Wed, 6 May 2020 02:38:19 -0600 Subject: [PATCH 19/19] Make autmodsumm higher priority than autosummary --- sphinx_automodapi/automodapi.py | 2 +- sphinx_automodapi/automodsumm.py | 20 ++------------------ 2 files changed, 3 insertions(+), 19 deletions(-) diff --git a/sphinx_automodapi/automodapi.py b/sphinx_automodapi/automodapi.py index aad1ec1..a4ddadb 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 5bf8a66..9a41b38 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -692,24 +692,8 @@ def setup(app): app.add_directive('automod-diagram', Automoddiagram) app.add_directive('automodsumm', Automodsumm) - app.connect('builder-inited', process_automodsumm_generation) - - # insert event *before* the autosummary hook so autosummary will read - # from the updated app.builder.env.found_docs attribute - # try to use as much of API as possible here - from sphinx.ext.autosummary import process_generate_options - listener_id = None - listeners = app.events.listeners['builder-inherited'] - if listeners and isinstance(listeners, dict): # in case API changes - for lid, func in listeners.items(): - if func is process_generate_options: - listener_id = lid - break - if listener_id is not None: - app.disconnect(listener_id) - app.connect('builder-inited', process_generate_options) - - # original + app.connect('builder-inited', process_automodsumm_generation, priority=100) + app.add_config_value('automodsumm_writereprocessed', False, True) app.add_config_value('automodsumm_inherited_members', False, 'env')