diff --git a/.github/workflows/ci_workflows.yml b/.github/workflows/ci_workflows.yml index ad69913..9c7adc6 100644 --- a/.github/workflows/ci_workflows.yml +++ b/.github/workflows/ci_workflows.yml @@ -100,9 +100,6 @@ jobs: run: choco install graphviz - name: Install tox run: python -m pip install tox - - name: Install codecov - if: ${{ contains(matrix.toxenv,'-cov') }} - run: python -m pip install codecov - name: Run tox run: tox ${{ matrix.toxargs }} -v -e ${{ matrix.toxenv }} - name: Upload coverage to codecov diff --git a/setup.cfg b/setup.cfg index bcc51c5..db8e168 100644 --- a/setup.cfg +++ b/setup.cfg @@ -27,7 +27,6 @@ test = pytest pytest-cov cython - codecov coverage [options.package_data] diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index 10a71f6..c694e36 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -46,7 +46,7 @@ in the generated documentation. The flags ``:inherited-members:`` or ``:no-inherited-members:`` allows overrriding this global setting. -This extension also adds two sphinx configuration options: +This extension also adds four sphinx configuration options: * ``automodsumm_writereprocessed`` Should be a bool, and if ``True``, will cause `automodsumm`_ to write files @@ -62,6 +62,16 @@ class members that are inherited from a base class. This value can be ``:inherited-members:`` or ``:no-inherited-members:`` options. Defaults to ``False``. +* ``automodsumm_private_methods_of`` + Should be a list of fully qualified names of classes where all of its + private methods (i.e., method names beginning with an underscore, but + not ending with a double underscore) should be documented. Defaults to ``[]``. + +* ``automodsumm_special_methods_of`` + Should be a list of fully qualified names of classes where all of its + special methods (i.e., method names beginning with a double underscore and + ending with a double underscore) should be documented. Defaults to ``[]``. + .. _sphinx.ext.autosummary: http://sphinx-doc.org/latest/ext/autosummary.html .. _autosummary: http://sphinx-doc.org/latest/ext/autosummary.html#directive-autosummary @@ -269,7 +279,9 @@ def process_automodsumm_generation(app): generate_automodsumm_docs( lines, sfn, app=app, builder=app.builder, base_path=app.srcdir, - inherited_members=app.config.automodsumm_inherited_members) + inherited_members=app.config.automodsumm_inherited_members, + private_methods_of=app.config.automodsumm_private_methods_of, + special_methods_of=app.config.automodsumm_special_methods_of) # _automodsummrex = re.compile(r'^(\s*)\.\. automodsumm::\s*([A-Za-z0-9_.]+)\s*' @@ -406,7 +418,9 @@ 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, - inherited_members=False): + inherited_members=False, + private_methods_of=[], + special_methods_of=[]): """ This function is adapted from `sphinx.ext.autosummary.generate.generate_autosummmary_docs` to @@ -520,10 +534,13 @@ def get_members_mod(obj, typ, include_public=[]): return public, items def get_members_class(obj, typ, include_public=[], - include_base=False): + include_base=False, + private_methods=False, special_methods=False): """ typ = None -> all include_base -> include attrs that are from a base class + private_methods -> include all private methods + special_methods -> include all special methods """ items = [] @@ -548,6 +565,7 @@ def get_members_class(obj, typ, include_public=[], else: names = getattr(obj, '__dict__').keys() + methods = [] for name in names: try: documenter = get_documenter(app, safe_getattr(obj, name), obj) @@ -559,8 +577,18 @@ def get_members_class(obj, typ, include_public=[], # In Sphinx 2.0 and above, properties have a separate # objtype, but we treat them the same here. items.append(name) + if typ in (None, 'method') and documenter.objtype == 'method': + methods.append(name) public = [x for x in items if x in include_public or not x.startswith('_')] + if private_methods: # Include all private methods + private = [x for x in methods if x not in public + and x.startswith('_') and not x.endswith('__')] + public.extend(private) + if special_methods: # Include all special methods + special = [x for x in methods if x not in public + and x.startswith('__') and x.endswith('__')] + public.extend(special) return public, items ns = {} @@ -581,12 +609,19 @@ def get_members_class(obj, typ, include_public=[], # use default value include_base = inherited_members + private_methods = True if name in private_methods_of else False + special_methods = True if name in special_methods_of else False + + class_kwargs = { + 'include_base': include_base, + 'private_methods': private_methods, + 'special_methods': special_methods, + } + api_class_methods = ['__init__', '__call__'] - ns['members'] = get_members_class(obj, None, - include_base=include_base) + ns['members'] = get_members_class(obj, None, **class_kwargs) ns['methods'], ns['all_methods'] = \ - get_members_class(obj, 'method', api_class_methods, - include_base=include_base) + get_members_class(obj, 'method', api_class_methods, **class_kwargs) ns['attributes'], ns['all_attributes'] = \ get_members_class(obj, 'attribute', include_base=include_base) @@ -664,6 +699,8 @@ def setup(app): app.add_config_value('automodsumm_writereprocessed', False, True) app.add_config_value('automodsumm_inherited_members', False, 'env') + app.add_config_value('automodsumm_private_methods_of', [], 'env') + app.add_config_value('automodsumm_special_methods_of', [], 'env') return {'parallel_read_safe': True, 'parallel_write_safe': True} diff --git a/sphinx_automodapi/tests/cases/private_methods/README.md b/sphinx_automodapi/tests/cases/private_methods/README.md new file mode 100644 index 0000000..11bf8e6 --- /dev/null +++ b/sphinx_automodapi/tests/cases/private_methods/README.md @@ -0,0 +1,2 @@ +Documenting a module with classes, also including private methods +for a particular list of classes. diff --git a/sphinx_automodapi/tests/cases/private_methods/input/index.rst b/sphinx_automodapi/tests/cases/private_methods/input/index.rst new file mode 100644 index 0000000..341faad --- /dev/null +++ b/sphinx_automodapi/tests/cases/private_methods/input/index.rst @@ -0,0 +1 @@ +.. automodapi:: sphinx_automodapi.tests.example_module.private_classes diff --git a/sphinx_automodapi/tests/cases/private_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Banana.rst b/sphinx_automodapi/tests/cases/private_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Banana.rst new file mode 100644 index 0000000..4840549 --- /dev/null +++ b/sphinx_automodapi/tests/cases/private_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Banana.rst @@ -0,0 +1,19 @@ +Banana +====== + +.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes + +.. autoclass:: Banana + :show-inheritance: + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Banana._energy + ~Banana.eat + + .. rubric:: Methods Documentation + + .. automethod:: _energy + .. automethod:: eat diff --git a/sphinx_automodapi/tests/cases/private_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Fruit.rst b/sphinx_automodapi/tests/cases/private_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Fruit.rst new file mode 100644 index 0000000..c78d455 --- /dev/null +++ b/sphinx_automodapi/tests/cases/private_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Fruit.rst @@ -0,0 +1,31 @@ +Fruit +===== + +.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes + +.. autoclass:: Fruit + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Fruit.weight + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Fruit._out_of_date + ~Fruit.buy + ~Fruit.eat + + .. rubric:: Attributes Documentation + + .. autoattribute:: weight + + .. rubric:: Methods Documentation + + .. automethod:: _out_of_date + .. automethod:: buy + .. automethod:: eat diff --git a/sphinx_automodapi/tests/cases/private_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Orange.rst b/sphinx_automodapi/tests/cases/private_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Orange.rst new file mode 100644 index 0000000..cade2c0 --- /dev/null +++ b/sphinx_automodapi/tests/cases/private_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Orange.rst @@ -0,0 +1,17 @@ +Orange +====== + +.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes + +.. autoclass:: Orange + :show-inheritance: + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Orange.eat + + .. rubric:: Methods Documentation + + .. automethod:: eat diff --git a/sphinx_automodapi/tests/cases/private_methods/output/index.rst.automodapi b/sphinx_automodapi/tests/cases/private_methods/output/index.rst.automodapi new file mode 100644 index 0000000..c381617 --- /dev/null +++ b/sphinx_automodapi/tests/cases/private_methods/output/index.rst.automodapi @@ -0,0 +1,19 @@ + +sphinx_automodapi.tests.example_module.private_classes Module +------------------------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module.private_classes + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module.private_classes + :classes-only: + :toctree: api + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module.private_classes + :private-bases: + :parts: 1 diff --git a/sphinx_automodapi/tests/cases/private_methods/output/index.rst.automodsumm b/sphinx_automodapi/tests/cases/private_methods/output/index.rst.automodsumm new file mode 100644 index 0000000..319a9e4 --- /dev/null +++ b/sphinx_automodapi/tests/cases/private_methods/output/index.rst.automodsumm @@ -0,0 +1,9 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes + +.. autosummary:: + :toctree: api + + Fruit + Banana + Orange + diff --git a/sphinx_automodapi/tests/cases/special_methods/README.md b/sphinx_automodapi/tests/cases/special_methods/README.md new file mode 100644 index 0000000..f9f47e5 --- /dev/null +++ b/sphinx_automodapi/tests/cases/special_methods/README.md @@ -0,0 +1,2 @@ +Documenting a module with classes, also including special methods +for a particular list of classes. diff --git a/sphinx_automodapi/tests/cases/special_methods/input/index.rst b/sphinx_automodapi/tests/cases/special_methods/input/index.rst new file mode 100644 index 0000000..341faad --- /dev/null +++ b/sphinx_automodapi/tests/cases/special_methods/input/index.rst @@ -0,0 +1 @@ +.. automodapi:: sphinx_automodapi.tests.example_module.private_classes diff --git a/sphinx_automodapi/tests/cases/special_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Banana.rst b/sphinx_automodapi/tests/cases/special_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Banana.rst new file mode 100644 index 0000000..188accd --- /dev/null +++ b/sphinx_automodapi/tests/cases/special_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Banana.rst @@ -0,0 +1,17 @@ +Banana +====== + +.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes + +.. autoclass:: Banana + :show-inheritance: + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Banana.eat + + .. rubric:: Methods Documentation + + .. automethod:: eat diff --git a/sphinx_automodapi/tests/cases/special_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Fruit.rst b/sphinx_automodapi/tests/cases/special_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Fruit.rst new file mode 100644 index 0000000..4c65aef --- /dev/null +++ b/sphinx_automodapi/tests/cases/special_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Fruit.rst @@ -0,0 +1,31 @@ +Fruit +===== + +.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes + +.. autoclass:: Fruit + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Fruit.weight + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Fruit.__len__ + ~Fruit.buy + ~Fruit.eat + + .. rubric:: Attributes Documentation + + .. autoattribute:: weight + + .. rubric:: Methods Documentation + + .. automethod:: __len__ + .. automethod:: buy + .. automethod:: eat diff --git a/sphinx_automodapi/tests/cases/special_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Orange.rst b/sphinx_automodapi/tests/cases/special_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Orange.rst new file mode 100644 index 0000000..6870eb4 --- /dev/null +++ b/sphinx_automodapi/tests/cases/special_methods/output/api/sphinx_automodapi.tests.example_module.private_classes.Orange.rst @@ -0,0 +1,19 @@ +Orange +====== + +.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes + +.. autoclass:: Orange + :show-inheritance: + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Orange.__add__ + ~Orange.eat + + .. rubric:: Methods Documentation + + .. automethod:: __add__ + .. automethod:: eat diff --git a/sphinx_automodapi/tests/cases/special_methods/output/index.rst.automodapi b/sphinx_automodapi/tests/cases/special_methods/output/index.rst.automodapi new file mode 100644 index 0000000..c381617 --- /dev/null +++ b/sphinx_automodapi/tests/cases/special_methods/output/index.rst.automodapi @@ -0,0 +1,19 @@ + +sphinx_automodapi.tests.example_module.private_classes Module +------------------------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module.private_classes + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module.private_classes + :classes-only: + :toctree: api + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module.private_classes + :private-bases: + :parts: 1 diff --git a/sphinx_automodapi/tests/cases/special_methods/output/index.rst.automodsumm b/sphinx_automodapi/tests/cases/special_methods/output/index.rst.automodsumm new file mode 100644 index 0000000..319a9e4 --- /dev/null +++ b/sphinx_automodapi/tests/cases/special_methods/output/index.rst.automodsumm @@ -0,0 +1,9 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module.private_classes + +.. autosummary:: + :toctree: api + + Fruit + Banana + Orange + diff --git a/sphinx_automodapi/tests/example_module/private_classes.py b/sphinx_automodapi/tests/example_module/private_classes.py new file mode 100644 index 0000000..023d3f2 --- /dev/null +++ b/sphinx_automodapi/tests/example_module/private_classes.py @@ -0,0 +1,90 @@ +__all__ = ['Fruit', 'Banana', 'Orange'] + + +class Fruit(object): + """ + An fruit + """ + def eat(self, time): + """ + Eat apple. + """ + pass + + def buy(self, price): + """ + Buy apple. + """ + pass + + @property + def weight(self): + """ + The weight of the apple. + """ + return 0 + + @property + def _age(self): + """ + The age of the fruit. + """ + return 0 + + def __len__(self): + """ + The length the fruit. + """ + return 0 + + def _out_of_date(self, date): + """ + Is it out of date? + """ + pass + + +class Banana(Fruit): + """ + A banana + """ + def eat(self, time): + """ + Eat banana. + """ + pass + + def _energy(self, units='kcal'): + """ + The energy in the banana. + """ + pass + + def __add__(self, other): + """ + How to add the banana to something. + """ + pass + + +class Orange(Fruit): + """ + An orange + """ + def eat(self, time): + """ + Eat orange. + """ + pass + + def _energy(self, units='kcal'): + """ + The energy in the orange. + """ + pass + + def __add__(self, other): + """ + How to add the orange to something. + """ + pass diff --git a/sphinx_automodapi/tests/test_cases.py b/sphinx_automodapi/tests/test_cases.py index 63b0171..8d187af 100644 --- a/sphinx_automodapi/tests/test_cases.py +++ b/sphinx_automodapi/tests/test_cases.py @@ -76,6 +76,17 @@ def test_run_full_case(tmpdir, case_dir, parallel): 'allowed_names'): conf['extensions'].append('sphinx_automodapi.smart_resolver') + if os.path.basename(case_dir) == 'private_methods': + conf['automodsumm_private_methods_of'] = [ + 'sphinx_automodapi.tests.example_module.private_classes.Fruit', + 'sphinx_automodapi.tests.example_module.private_classes.Banana', + ] + if os.path.basename(case_dir) == 'special_methods': + conf['automodsumm_special_methods_of'] = [ + 'sphinx_automodapi.tests.example_module.private_classes.Fruit', + 'sphinx_automodapi.tests.example_module.private_classes.Orange', + ] + start_dir = os.path.abspath('.') src_dir = 'src' if 'source_dir' in case_dir else '.'