diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..f715e38 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,17 @@ +# To get started with Dependabot version updates, you'll need to specify which +# package ecosystems to update and where the package manifests are located. +# Please see the documentation for all configuration options: +# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates + +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "monthly" + groups: + actions: + patterns: + - "*" + labels: + - "no-changelog-entry-needed" diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 0000000..9d1e098 --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,5 @@ +changelog: + exclude: + authors: + - dependabot + - pre-commit-ci diff --git a/.github/workflows/check_milestone.yml b/.github/workflows/check_milestone.yml new file mode 100644 index 0000000..e302ddc --- /dev/null +++ b/.github/workflows/check_milestone.yml @@ -0,0 +1,34 @@ +name: Check PR milestone + +on: + # So it cannot be skipped. + pull_request_target: + types: [opened, synchronize, milestoned, demilestoned] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + # https://stackoverflow.com/questions/69434370/how-can-i-get-the-latest-pr-data-specifically-milestones-when-running-yaml-jobs + milestone_checker: + runs-on: ubuntu-latest + steps: + - uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1 + if: github.repository == 'astropy/sphinx-automodapi' + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + script: | + const { data } = await github.request("GET /repos/{owner}/{repo}/pulls/{pr}", { + owner: context.repo.owner, + repo: context.repo.repo, + pr: context.payload.pull_request.number + }); + if (data.milestone) { + core.info(`This pull request has a milestone set: ${data.milestone.title}`); + } else { + core.setFailed(`A maintainer needs to set the milestone for this pull request.`); + } diff --git a/.github/workflows/ci_workflows.yml b/.github/workflows/ci_workflows.yml index 5243ad2..678fdba 100644 --- a/.github/workflows/ci_workflows.yml +++ b/.github/workflows/ci_workflows.yml @@ -4,17 +4,21 @@ on: pull_request: push: branches: [ main ] - tags: + tags: '*' workflow_dispatch: schedule: - # Monthly cron - - cron: '0 8 1 * *' + # Weekly cron + - cron: '0 8 * * 1' + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true jobs: tests: runs-on: ${{ matrix.os }} strategy: - fail-fast: true + fail-fast: false matrix: include: - name: Code style checks @@ -23,58 +27,62 @@ jobs: toxenv: codestyle # Linux - test different Sphinx versions - - os: ubuntu-latest - python-version: 3.7 - toxenv: py37-test-sphinx24 - os: ubuntu-latest python-version: 3.8 - toxenv: py38-test-sphinx35 + toxenv: py38-test-sphinx_oldest - os: ubuntu-latest python-version: 3.8 - toxenv: py38-test-sphinx40 + toxenv: py38-test-sphinx53 - os: ubuntu-latest python-version: 3.9 - toxenv: py39-test-sphinx41 + toxenv: py39-test-sphinx62 - os: ubuntu-latest python-version: 3.9 - toxenv: py39-test-sphinx42 + toxenv: py39-test-sphinx70 - os: ubuntu-latest python-version: '3.10' - toxenv: py310-test-sphinx43-cov-clocale + toxenv: py310-test-sphinx71 - os: ubuntu-latest - python-version: '3.10' - toxenv: py310-test-sphinxdev + python-version: '3.11' + toxenv: py311-test-sphinx72-cov-clocale + - os: ubuntu-latest + python-version: '3.12' + toxenv: py312-test-sphinx80 + - os: ubuntu-latest + python-version: '3.12' + toxenv: py312-test-sphinx81 + - os: ubuntu-latest + python-version: '3.13' + toxenv: py313-test-sphinxdev - # MacOS X - just the oldest, stable, and dev - - os: macos-latest - python-version: 3.7 - toxenv: py37-test-sphinx24 + # MacOS X - just the stable and dev - os: macos-latest - python-version: 3.8 - toxenv: py38-test-sphinx43-clocale + python-version: '3.11' + toxenv: py311-test-sphinx81-clocale - os: macos-latest - python-version: 3.9 - toxenv: py39-test-sphinxdev + python-version: '3.13' + toxenv: py313-test-sphinxdev # Windows - just the oldest, stable, and dev - - os: windows-latest - python-version: 3.7 - toxenv: py37-test-sphinx24 - os: windows-latest python-version: 3.8 - toxenv: py38-test-sphinx43-clocale + toxenv: py38-test-sphinx_oldest - os: windows-latest - python-version: 3.9 - toxenv: py39-test-sphinxdev + python-version: '3.10' + toxenv: py310-test-sphinx81 + - os: windows-latest + python-version: '3.13' + toxenv: py313-test-sphinxdev steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: fetch-depth: 0 - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v2 + uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 with: python-version: ${{ matrix.python-version }} + allow-prereleases: true - name: Install graphviz on Linux if: startsWith(matrix.os, 'ubuntu') run: | @@ -90,13 +98,10 @@ 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 if: ${{ contains(matrix.toxenv,'-cov') }} - uses: codecov/codecov-action@v2 + uses: codecov/codecov-action@ad3126e916f78f00edff4ed0317cf185271ccc2d # v5.4.2 with: file: ./coverage.xml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index ab895a1..aaf879d 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -13,12 +13,12 @@ jobs: if: ((github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) || contains(github.event.pull_request.labels.*.name, 'Build wheels')) steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: fetch-depth: 0 - - uses: actions/setup-python@v2 + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 with: - python-version: 3.8 + python-version: "3.12" - name: Install dependencies run: | @@ -40,12 +40,12 @@ jobs: cd .. python -m venv testenv testenv/bin/pip install pip -U - testenv/bin/pip install pytest cython sphinx-automodapi/dist/*.whl + testenv/bin/pip install $(ls sphinx-automodapi/dist/*.whl)[test] testenv/bin/pytest sphinx-automodapi/sphinx_automodapi/tests - name: Publish distribution 📦 to PyPI if: startsWith(github.ref, 'refs/tags') - uses: pypa/gh-action-pypi-publish@release/v1 + uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4 with: user: __token__ password: ${{ secrets.pypi_password }} diff --git a/.gitignore b/.gitignore index 8f9b3ad..60842bf 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,7 @@ __pycache__ # Other generated files MANIFEST +sphinx_automodapi/version.py # Sphinx _build diff --git a/.mailmap b/.mailmap new file mode 100644 index 0000000..9371398 --- /dev/null +++ b/.mailmap @@ -0,0 +1,12 @@ +Brigitta Sipőcz +Brigitta Sipőcz +David Pérez-Suárez +E. Madison Bray +E. Madison Bray +Kyle D Fawcett <45832007+kylefawcett@users.noreply.github.com> +Hans Moritz Günther +Marco Rossi +Matt Davis +P. L. Lim <2090236+pllim@users.noreply.github.com> +Simon Conseil +Stuart Mumford \ No newline at end of file diff --git a/.readthedocs.yml b/.readthedocs.yml index 6ddecd0..5109e33 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -4,16 +4,25 @@ version: 2 +build: + os: ubuntu-22.04 + tools: + python: "3.12" + jobs: + post_checkout: + - git fetch --shallow-since=2023-01-01 || true + sphinx: builder: html configuration: docs/conf.py fail_on_warning: true python: - version: 3.8 install: - method: pip path: . + extra_requirements: + - rtd # Don't build any extra formats formats: [] diff --git a/CHANGES.rst b/CHANGES.rst index e4ff835..07c5d15 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,9 +1,54 @@ Changes in sphinx-automodapi ============================ -0.15.0 (unreleased) +0.20.0 (unreleased) ------------------- +- No changes yet + +0.19.0 (2025-04-17) +------------------- + +- Add ``automodsumm_properties_are_attributes`` configuration to control if + class properties are treated with ``autoattribute`` or ``autoproperty``. + [#197] + +- Fixes compatibility with Sphinx 8.2. [#196] + +0.18.0 (2024-09-13) +------------------- + +- Fixed an issue where items defined in ``__all__`` but originally imported + from elsewhere, e.g. a private module, were not documented. [#190] + +0.17.0 (2024-02-22) +------------------- + +- Fixes issue where ``__slots__`` hides class variables. [#181] + +- Minimum supported Python version is now 3.8. [#177] + +- Fixed issue with non-ascii characters in object names. [#184] + +0.16.0 (2023-08-17) +------------------- + +- Fixed broken inheritance-diagram links due to the smart resolver. [#172] + +- Compatibility with Sphinx 7.2. [#172] + +- Minimum supported Sphinx version is now 4. [#170] + +0.15.0 (2023-03-13) +------------------- + +- Silenced spurious warnings on configuring ``:nosignatures:``. [#158] + +- Fixed issue with non-ascii characters in object members when the encoding is + not ``utf8``. [#153] + +- Allow use of ``:noindex:``, propagating this flag to autodoc. [#150] + 0.14.1 (2022-01-12) ------------------- diff --git a/LICENSE.rst b/LICENSE.rst index 4f6e337..ecbe4fc 100644 --- a/LICENSE.rst +++ b/LICENSE.rst @@ -1,4 +1,4 @@ -Copyright (c) 2014-2016, Astropy Developers +Copyright (c) 2014-2025, Astropy Developers All rights reserved. diff --git a/MANIFEST.in b/MANIFEST.in index 6f1d2ae..1637fde 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -3,6 +3,7 @@ include CHANGES.rst include LICENSE.rst include setup.cfg +include pyproject.toml exclude *.pyc *.o prune build diff --git a/docs/conf.py b/docs/conf.py index c453cc2..5dafd40 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 = 'en' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. diff --git a/pyproject.toml b/pyproject.toml index 590e0b1..9765e29 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,5 +1,9 @@ [build-system] requires = ["setuptools>=30.3.0", - "setuptools_scm", + "setuptools_scm>=8.0.0", "wheel"] build-backend = 'setuptools.build_meta' + + +[tool.setuptools_scm] +version_file = "sphinx_automodapi/version.py" diff --git a/setup.cfg b/setup.cfg index 0dfbcc6..6f619d9 100644 --- a/setup.cfg +++ b/setup.cfg @@ -8,7 +8,7 @@ author_email = astropy.team@gmail.com license = BSD 3-Clause License url = https://github.com/astropy/sphinx-automodapi classifiers = - Development Status :: 3 - Alpha + Development Status :: 5 - Production/Stable Intended Audience :: Developers Programming Language :: Python Programming Language :: Python :: 3 @@ -18,21 +18,24 @@ classifiers = [options] zip_safe = False packages = find: -python_requires = >=3.7 +python_requires = >=3.8 install_requires = - sphinx>=2 + packaging + sphinx>=4 [options.extras_require] test = pytest pytest-cov cython - codecov coverage + setuptools;python_version>='3.12' +rtd = + sphinx-rtd-theme [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 @@ -44,6 +47,12 @@ filterwarnings = ignore:'contextfunction' is renamed to 'pass_context':DeprecationWarning ignore:'environmentfilter' is renamed to 'pass_environment':DeprecationWarning ignore:distutils Version classes are deprecated:DeprecationWarning + ignore:'imghdr' is deprecated and slated for removal in Python 3.13:DeprecationWarning + ignore:The alias 'sphinx\.util\.SkipProgressMessage' is deprecated + ignore:The alias 'sphinx\.util\.progress_message' is deprecated + ignore:Deprecated call to.*pkg_resources\.declare_namespace:DeprecationWarning + # pip 23.1 issue: + ignore:pkg_resources is deprecated as an API:DeprecationWarning [flake8] max-line-length = 125 diff --git a/setup.py b/setup.py deleted file mode 100644 index 21f6163..0000000 --- a/setup.py +++ /dev/null @@ -1,6 +0,0 @@ -#!/usr/bin/env python - -import os -from setuptools import setup - -setup(use_scm_version={'write_to': os.path.join('sphinx_automodapi', 'version.py')}) diff --git a/sphinx_automodapi/__init__.py b/sphinx_automodapi/__init__.py index b5e195e..e0fcb47 100644 --- a/sphinx_automodapi/__init__.py +++ b/sphinx_automodapi/__init__.py @@ -1 +1 @@ -__version__ = '0.14.dev0' +from .version import version as __version__ # noqa diff --git a/sphinx_automodapi/autodoc_enhancements.py b/sphinx_automodapi/autodoc_enhancements.py index 7721043..8350638 100644 --- a/sphinx_automodapi/autodoc_enhancements.py +++ b/sphinx_automodapi/autodoc_enhancements.py @@ -1,6 +1,8 @@ """ Miscellaneous enhancements to help autodoc along. """ +import dataclasses + from sphinx.ext.autodoc import AttributeDocumenter __all__ = [] @@ -58,7 +60,14 @@ def type_object_attrgetter(obj, attr, *defargs): return base.__dict__[attr] break - return getattr(obj, attr, *defargs) + try: + return getattr(obj, attr, *defargs) + except AttributeError: + # for dataclasses, get the attribute from the __dataclass_fields__ + if dataclasses.is_dataclass(obj) and attr in obj.__dataclass_fields__: + return obj.__dataclass_fields__[attr].default + else: + raise def setup(app): diff --git a/sphinx_automodapi/automodapi.py b/sphinx_automodapi/automodapi.py index 28cff8a..fdb49d5 100644 --- a/sphinx_automodapi/automodapi.py +++ b/sphinx_automodapi/automodapi.py @@ -63,8 +63,17 @@ 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: + * ``:sort:`` + If the module contains ``__all__``, sort the module's objects + alphabetically (if ``__all__`` is not present, the objects are found + using `dir`, which always gives a sorted list). + + +This extension also adds five sphinx configuration options: * ``automodapi_inheritance_diagram`` Should be a boolean that indicates whether to show inheritance diagrams @@ -89,6 +98,17 @@ Should be a bool and if ``True`` members that a class inherits from a base class are included in the generated documentation. Defaults to ``False``. +* ``automodsumm_included_members`` + A list of strings containing the names of hidden class members that should be + included in the documentation. This is most commonly used to add special class + methods like ``__getitem__`` and ``__setitem__``. Defaults to + ``['__init__', '__call__']``. + +* ``automodsumm_properties_are_attributes`` + Should be a bool and if ``True`` properties are treated as attributes in the + documentation meaning that no property specific documentation is generated. + Defaults to ``True``. + .. _automodule: http://sphinx-doc.org/latest/ext/autodoc.html?highlight=automodule#directive-automodule """ @@ -101,7 +121,6 @@ class are included in the generated documentation. Defaults to ``False``. # actually built. import inspect -import io import os import re import sys @@ -112,11 +131,6 @@ class are included in the generated documentation. Defaults to ``False``. __all__ = [] -if sys.version_info[0] == 3: - text_type = str -else: - text_type = unicode # noqa - automod_templ_modheader = """ {modname} {pkgormod} {modhds}{pkgormodhds} @@ -245,6 +259,8 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None, hds = '-^' allowedpkgnms = [] allowothers = False + noindex = False + sort = False # look for actual options unknownops = [] @@ -272,6 +288,10 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None, inherited_members = False elif opname == 'include-all-objects': allowothers = True + elif opname == 'noindex': + noindex = True + elif opname == 'sort': + sort = True else: unknownops.append(opname) @@ -327,6 +347,10 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None, clsfuncoptions = [] if toctreestr: clsfuncoptions.append(toctreestr) + if noindex: + clsfuncoptions.append(':noindex:') + if sort: + clsfuncoptions.append(':sort:') if toskip: clsfuncoptions.append(':skip: ' + ','.join(toskip)) if allowedpkgnms: @@ -377,14 +401,14 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None, if app.config.automodapi_writereprocessed: # sometimes they are unicode, sometimes not, depending on how # sphinx has processed things - if isinstance(newsourcestr, text_type): + if isinstance(newsourcestr, str): ustr = newsourcestr else: ustr = newsourcestr.decode(app.config.source_encoding) if docname is None: - with io.open(os.path.join(app.srcdir, 'unknown.automodapi'), - 'a', encoding='utf8') as f: + with open(os.path.join(app.srcdir, 'unknown.automodapi'), + 'a', encoding='utf8') as f: f.write(u'\n**NEW DOC**\n\n') f.write(ustr) else: @@ -394,8 +418,8 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None, filename = docname + os.path.splitext(env.doc2path(docname))[1] filename += '.automodapi' - with io.open(os.path.join(app.srcdir, filename), 'w', - encoding='utf8') as f: + with open(os.path.join(app.srcdir, filename), 'w', + encoding='utf8') as f: f.write(ustr) return newsourcestr diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index 30979cc..a98bd20 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -46,7 +46,13 @@ 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: + * ``:sort:`` + If the module contains ``__all__``, sort the module's objects + alphabetically (if ``__all__`` is not present, the objects are found + using `dir`, which always gives a sorted list). + + +This extension also adds three sphinx configuration options: * ``automodsumm_writereprocessed`` Should be a bool, and if ``True``, will cause `automodsumm`_ to write files @@ -62,6 +68,17 @@ class members that are inherited from a base class. This value can be ``:inherited-members:`` or ``:no-inherited-members:`` options. Defaults to ``False``. +* ``automodsumm_included_members`` + A list of strings containing the names of hidden class members that should be + included in the documentation. This is most commonly used to add special class + methods like ``__getitem__`` and ``__setitem__``. Defaults to + ``['__init__', '__call__']``. + +* ``automodsumm_properties_are_attributes`` + Should be a bool and if ``True`` properties are treated as attributes in the + documentation meaning that no property specific documentation is generated. + Defaults to ``True``. + .. _sphinx.ext.autosummary: http://sphinx-doc.org/latest/ext/autosummary.html .. _autosummary: http://sphinx-doc.org/latest/ext/autosummary.html#directive-autosummary @@ -83,22 +100,24 @@ class members that are inherited from a base class. This value can be .. _sphinx.ext.inheritance_diagram: http://sphinx-doc.org/latest/ext/inheritance.html """ -import abc import inspect import os import re -import io +import dataclasses +import sphinx +from docutils.parsers.rst.directives import flag +from packaging.version import Version from sphinx.util import logging from sphinx.ext.autosummary import Autosummary -from sphinx.ext.inheritance_diagram import InheritanceDiagram -from docutils.parsers.rst.directives import flag +from sphinx.ext.inheritance_diagram import InheritanceDiagram, InheritanceGraph, try_import from .utils import find_mod_objs, cleanup_whitespace __all__ = ['Automoddiagram', 'Automodsumm', 'automodsumm_to_autosummary_lines', 'generate_automodsumm_docs', 'process_automodsumm_generation'] logger = logging.getLogger(__name__) +SPHINX_LT_8_2 = Version(sphinx.__version__) < Version("8.2.dev") def _str_list_converter(argument): @@ -125,6 +144,8 @@ 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 + option_spec['sort'] = flag def run(self): env = self.state.document.settings.env @@ -133,7 +154,7 @@ def run(self): nodelist = [] try: - localnames, fqns, objs = find_mod_objs(modname) + localnames, fqns, objs = find_mod_objs(modname, sort='sort' in self.options) except ImportError: logger.warning("Couldn't import module " + modname) return [] @@ -242,6 +263,42 @@ def run(self): self.arguments = oldargs +# sphinx.ext.inheritance_diagram generates a list of class full names and +# generates a mapping from class full names to documentation URLs. However, the +# smart resolver in sphinx-automodapi causes the generated mapping to be instead +# from class documented name to documentation URLs. The class documented name +# can be different from the class full name if the class is not documented where +# it is defined, but rather at some other location where it is imported. In +# such situations, the code will fail to find the URL that for the class. + +# The following code monkey-patches the method that receives the mapping and +# converts the keys from class documented names to class full names. + +old_generate_dot = InheritanceGraph.generate_dot + +if SPHINX_LT_8_2: + def patched_generate_dot(self, name, urls={}, env=None, + graph_attrs={}, node_attrs={}, edge_attrs={}): + # Make a new mapping dictionary that uses class full names by importing each + # class documented name + fullname_urls = {self.class_name(try_import(name), 0, None): url + for name, url in urls.items() if try_import(name) is not None} + return old_generate_dot(self, name, urls=fullname_urls, env=env, + graph_attrs=graph_attrs, node_attrs=node_attrs, edge_attrs=edge_attrs) +else: + def patched_generate_dot(self, name, urls={}, config=None, + graph_attrs={}, node_attrs={}, edge_attrs={}): + # Make a new mapping dictionary that uses class full names by importing each + # class documented name + fullname_urls = {self.class_name(try_import(name), 0, None): url + for name, url in urls.items() if try_import(name) is not None} + return old_generate_dot(self, name, urls=fullname_urls, config=config, + graph_attrs=graph_attrs, node_attrs=node_attrs, edge_attrs=edge_attrs) + + +InheritanceGraph.generate_dot = patched_generate_dot + + # <---------------------automodsumm generation stuff--------------------------> def process_automodsumm_generation(app): env = app.builder.env @@ -259,7 +316,7 @@ def process_automodsumm_generation(app): if app.config.automodsumm_writereprocessed: if lines: # empty list means no automodsumm entry is in the file outfn = os.path.join(app.srcdir, sfn) + '.automodsumm' - with open(outfn, 'w') as f: + with open(outfn, 'w', encoding='utf8') as f: for l in lines: # noqa: E741 f.write(l) f.write('\n') @@ -269,7 +326,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, + included_members=app.config.automodsumm_included_members, + properties_are_attributes=app.config.automodsumm_properties_are_attributes) # _automodsummrex = re.compile(r'^(\s*)\.\. automodsumm::\s*([A-Za-z0-9_.]+)\s*' @@ -312,7 +371,7 @@ def automodsumm_to_autosummary_lines(fn, app): fullfn = os.path.join(app.builder.env.srcdir, fn) - with io.open(fullfn, encoding='utf8') as fr: + with open(fullfn, encoding='utf8') as fr: # Note: we use __name__ here instead of just writing the module name in # case this extension is bundled into another package from . import automodapi @@ -347,12 +406,12 @@ def automodsumm_to_autosummary_lines(fn, app): opssecs, remainders)): allindent = i1 + (' ' if i2 is None else i2) - # filter out functions-only, classes-only, and ariables-only + # filter out functions-only, classes-only, variables-only, and sort # options if present. oplines = ops.split('\n') toskip = [] allowedpkgnms = [] - funcsonly = clssonly = varsonly = False + funcsonly = clssonly = varsonly = sort = False for i, ln in reversed(list(enumerate(oplines))): if ':functions-only:' in ln: funcsonly = True @@ -369,6 +428,9 @@ def automodsumm_to_autosummary_lines(fn, app): if ':allowed-package-names:' in ln: allowedpkgnms.extend(_str_list_converter(ln.replace(':allowed-package-names:', ''))) del oplines[i] + if ':sort:' in ln: + sort = True + del oplines[i] if [funcsonly, clssonly, varsonly].count(True) > 1: msg = ('Defined more than one of functions-only, classes-only, ' 'and variables-only. Skipping this directive.') @@ -386,7 +448,7 @@ def automodsumm_to_autosummary_lines(fn, app): newlines.extend(oplines) ols = True if len(allowedpkgnms) == 0 else allowedpkgnms - for nm, fqn, obj in zip(*find_mod_objs(modnm, onlylocals=ols)): + for nm, fqn, obj in zip(*find_mod_objs(modnm, onlylocals=ols, sort=sort)): if nm in toskip: continue if funcsonly and not inspect.isroutine(obj): @@ -406,7 +468,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, + included_members=('__init__', '__call__'), + *, properties_are_attributes=True): """ This function is adapted from `sphinx.ext.autosummary.generate.generate_autosummmary_docs` to @@ -458,7 +522,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 @@ -488,9 +552,7 @@ def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst', new_files.append(fn) - f = open(fn, 'w') - - try: + with open(fn, 'w', encoding='utf8') as f: doc = get_documenter(app, obj, parent) @@ -528,37 +590,34 @@ def get_members_class(obj, typ, include_public=[], items = [] # using dir gets all of the attributes, including the elements - # from the base class, otherwise use __slots__ or __dict__ + # from the base class, otherwise use __dict__ if include_base: names = dir(obj) else: - # Classes deriving from an ABC using the `abc` module will - # have an empty `__slots__` attribute in Python 3, unless - # other slots were declared along the inheritance chain. If - # the ABC-derived class has empty slots, we'll use the - # class `__dict__` instead. - declares_slots = ( - hasattr(obj, '__slots__') and - not (issubclass(type(obj), abc.ABCMeta) and - len(obj.__slots__) == 0) - ) - - if declares_slots: - names = tuple(getattr(obj, '__slots__')) - else: - names = getattr(obj, '__dict__').keys() + names = getattr(obj, '__dict__').keys() + + # add dataclass_field names for dataclass classes + if dataclasses.is_dataclass(obj): + dataclass_fieldnames = getattr(obj, '__dataclass_fields__').keys() + names = list(set(list(names) + list(dataclass_fieldnames))) for name in names: try: documenter = get_documenter(app, safe_getattr(obj, name), obj) except AttributeError: - continue + # for dataclasses try to get the attribute from the __dataclass_fields__ + if dataclasses.is_dataclass(obj): + try: + attr = obj.__dataclass_fields__[name] + documenter = get_documenter(app, attr, obj) + except KeyError: + 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) + # 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('_')] return public, items @@ -581,15 +640,23 @@ 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', included_members, include_base=include_base) ns['attributes'], ns['all_attributes'] = \ get_members_class(obj, 'attribute', include_base=include_base) + public_properties, all_properties = \ + get_members_class(obj, 'property', + include_base=include_base) + if properties_are_attributes: + ns['attributes'].extend(public_properties) + ns['all_attributes'].extend(all_properties) + else: + ns['properties'] = public_properties + ns['all_properties'] = all_properties ns['methods'].sort() ns['attributes'].sort() @@ -602,6 +669,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 @@ -634,7 +702,7 @@ def get_members_class(obj, typ, include_public=[], # An important subtlety here is that the path we pass in has # to be relative to the file being generated, so we have to # figure out the right number of '..'s - ndirsback = path.replace(base_path, '').count(os.sep) + ndirsback = path.replace(str(base_path), '').count(os.sep) ref_file_rel_segments = ['..'] * ndirsback ref_file_rel_segments.append(mod_name_dir) ref_file_rel_segments.append('references.txt') @@ -642,8 +710,6 @@ def get_members_class(obj, typ, include_public=[], rendered = template.render(**ns) f.write(cleanup_whitespace(rendered)) - finally: - f.close() def setup(app): @@ -663,6 +729,9 @@ 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_included_members', ['__init__', '__call__'], 'env') + app.add_config_value('automodsumm_properties_are_attributes', True, 'env') return {'parallel_read_safe': True, 'parallel_write_safe': True} diff --git a/sphinx_automodapi/templates/autosummary_core/class.rst b/sphinx_automodapi/templates/autosummary_core/class.rst index 85105fa..0c0c57f 100644 --- a/sphinx_automodapi/templates/autosummary_core/class.rst +++ b/sphinx_automodapi/templates/autosummary_core/class.rst @@ -9,13 +9,16 @@ .. autoclass:: {{ objname }} :show-inheritance: + {% if noindex -%} + :noindex: + {%- endif %} {% if '__init__' in methods %} {% set caught_result = methods.remove('__init__') %} {% endif %} {% block attributes_summary %} - {% if attributes %} + {% if attributes or properties %} .. rubric:: Attributes Summary @@ -24,6 +27,10 @@ ~{{ name }}.{{ item }} {%- endfor %} + {% for item in properties %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} {% endblock %} @@ -41,7 +48,7 @@ {% endblock %} {% block attributes_documentation %} - {% if attributes %} + {% if attributes or properties%} .. rubric:: Attributes Documentation @@ -49,6 +56,10 @@ .. autoattribute:: {{ item }} {%- endfor %} + {% for item in properties %} + .. autoproperty:: {{ item }} + {%- endfor %} + {% endif %} {% endblock %} diff --git a/sphinx_automodapi/tests/cases/abstract_classes/output/api/sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst b/sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst similarity index 100% rename from sphinx_automodapi/tests/cases/abstract_classes/output/api/sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst rename to sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst diff --git a/sphinx_automodapi/tests/cases/abstract_classes/output/index.rst.automodapi b/sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/index.rst.automodapi similarity index 100% rename from sphinx_automodapi/tests/cases/abstract_classes/output/index.rst.automodapi rename to sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/index.rst.automodapi diff --git a/sphinx_automodapi/tests/cases/abstract_classes/output/index.rst.automodsumm b/sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/index.rst.automodsumm similarity index 100% rename from sphinx_automodapi/tests/cases/abstract_classes/output/index.rst.automodsumm rename to sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/index.rst.automodsumm diff --git a/sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst b/sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst new file mode 100644 index 0000000..d9ec7cf --- /dev/null +++ b/sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst @@ -0,0 +1,27 @@ +SequenceSubclass +================ + +.. currentmodule:: sphinx_automodapi.tests.example_module.abstract_classes + +.. autoclass:: SequenceSubclass + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~SequenceSubclass.my_property + + .. rubric:: Methods Summary + + .. autosummary:: + + ~SequenceSubclass.my_method + + .. rubric:: Attributes Documentation + + .. autoproperty:: my_property + + .. rubric:: Methods Documentation + + .. automethod:: my_method diff --git a/sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/index.rst.automodapi b/sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/index.rst.automodapi new file mode 100644 index 0000000..4bdc13b --- /dev/null +++ b/sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/index.rst.automodapi @@ -0,0 +1,19 @@ + +sphinx_automodapi.tests.example_module.abstract_classes Module +-------------------------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module.abstract_classes + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module.abstract_classes + :classes-only: + :toctree: api + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module.abstract_classes + :private-bases: + :parts: 1 diff --git a/sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/index.rst.automodsumm b/sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/index.rst.automodsumm new file mode 100644 index 0000000..b280f1d --- /dev/null +++ b/sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/index.rst.automodsumm @@ -0,0 +1,6 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module.abstract_classes + +.. autosummary:: + :toctree: api + + SequenceSubclass diff --git a/sphinx_automodapi/tests/cases/allowed_names/output/api/sphinx_automodapi.tests.example_module.Egg.rst b/sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Egg.rst similarity index 100% rename from sphinx_automodapi/tests/cases/allowed_names/output/api/sphinx_automodapi.tests.example_module.Egg.rst rename to sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Egg.rst diff --git a/sphinx_automodapi/tests/cases/allowed_names/output/api/sphinx_automodapi.tests.example_module.Spam.rst b/sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst similarity index 100% rename from sphinx_automodapi/tests/cases/allowed_names/output/api/sphinx_automodapi.tests.example_module.Spam.rst rename to sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst diff --git a/sphinx_automodapi/tests/cases/allowed_names/output/index.rst.automodapi b/sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/index.rst.automodapi similarity index 100% rename from sphinx_automodapi/tests/cases/allowed_names/output/index.rst.automodapi rename to sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/index.rst.automodapi diff --git a/sphinx_automodapi/tests/cases/allowed_names/output/index.rst.automodsumm b/sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/index.rst.automodsumm similarity index 100% rename from sphinx_automodapi/tests/cases/allowed_names/output/index.rst.automodsumm rename to sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/index.rst.automodsumm diff --git a/sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst b/sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst new file mode 100644 index 0000000..f8d762a --- /dev/null +++ b/sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst @@ -0,0 +1,29 @@ +Egg +=== + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autoclass:: Egg + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Egg.weight + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Egg.buy + ~Egg.eat + + .. rubric:: Attributes Documentation + + .. autoproperty:: weight + + .. rubric:: Methods Documentation + + .. automethod:: buy + .. automethod:: eat diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel/output/api/sphinx_automodapi.tests.example_module.Spam.rst b/sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel/output/api/sphinx_automodapi.tests.example_module.Spam.rst rename to sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst diff --git a/sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/index.rst.automodapi b/sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/index.rst.automodapi new file mode 100644 index 0000000..aed3523 --- /dev/null +++ b/sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/index.rst.automodapi @@ -0,0 +1,21 @@ + +sphinx_automodapi.tests.example_module Package +---------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module + :classes-only: + :toctree: api + :allowed-package-names: sphinx_automodapi.tests.example_module.classes + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module + :private-bases: + :parts: 1 + :allowed-package-names: sphinx_automodapi.tests.example_module.classes diff --git a/sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/index.rst.automodsumm b/sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/index.rst.automodsumm new file mode 100644 index 0000000..1710307 --- /dev/null +++ b/sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/index.rst.automodsumm @@ -0,0 +1,7 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autosummary:: + :toctree: api + + Egg + Spam diff --git a/sphinx_automodapi/tests/cases/attribute_class/README.md b/sphinx_automodapi/tests/cases/attribute_class/README.md new file mode 100644 index 0000000..36c45c6 --- /dev/null +++ b/sphinx_automodapi/tests/cases/attribute_class/README.md @@ -0,0 +1,2 @@ +This example is to make sure that classes can have attributes and properties +and they can be distiguished if ``automodsumm_properties_are_attributes = False`` diff --git a/sphinx_automodapi/tests/cases/attribute_class/input/index.rst b/sphinx_automodapi/tests/cases/attribute_class/input/index.rst new file mode 100644 index 0000000..aaea6f9 --- /dev/null +++ b/sphinx_automodapi/tests/cases/attribute_class/input/index.rst @@ -0,0 +1 @@ +.. automodapi:: sphinx_automodapi.tests.example_module.attribute_class diff --git a/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.attribute_class.ClassWithAttribute.rst b/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.attribute_class.ClassWithAttribute.rst new file mode 100644 index 0000000..45e84a5 --- /dev/null +++ b/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.attribute_class.ClassWithAttribute.rst @@ -0,0 +1,29 @@ +ClassWithAttribute +================== + +.. currentmodule:: sphinx_automodapi.tests.example_module.attribute_class + +.. autoclass:: ClassWithAttribute + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~ClassWithAttribute.my_attribute + ~ClassWithAttribute.my_property + + .. rubric:: Methods Summary + + .. autosummary:: + + ~ClassWithAttribute.my_method + + .. rubric:: Attributes Documentation + + .. autoattribute:: my_attribute + .. autoattribute:: my_property + + .. rubric:: Methods Documentation + + .. automethod:: my_method diff --git a/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/index.rst.automodapi b/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/index.rst.automodapi new file mode 100644 index 0000000..941dcac --- /dev/null +++ b/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/index.rst.automodapi @@ -0,0 +1,19 @@ + +sphinx_automodapi.tests.example_module.attribute_class Module +------------------------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module.attribute_class + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module.attribute_class + :classes-only: + :toctree: api + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module.attribute_class + :private-bases: + :parts: 1 diff --git a/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/index.rst.automodsumm b/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/index.rst.automodsumm new file mode 100644 index 0000000..9aafd6b --- /dev/null +++ b/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/index.rst.automodsumm @@ -0,0 +1,6 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module.attribute_class + +.. autosummary:: + :toctree: api + + ClassWithAttribute diff --git a/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.attribute_class.ClassWithAttribute.rst b/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.attribute_class.ClassWithAttribute.rst new file mode 100644 index 0000000..3a418d4 --- /dev/null +++ b/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.attribute_class.ClassWithAttribute.rst @@ -0,0 +1,31 @@ +ClassWithAttribute +================== + +.. currentmodule:: sphinx_automodapi.tests.example_module.attribute_class + +.. autoclass:: ClassWithAttribute + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~ClassWithAttribute.my_attribute + + ~ClassWithAttribute.my_property + + .. rubric:: Methods Summary + + .. autosummary:: + + ~ClassWithAttribute.my_method + + .. rubric:: Attributes Documentation + + .. autoattribute:: my_attribute + + .. autoproperty:: my_property + + .. rubric:: Methods Documentation + + .. automethod:: my_method diff --git a/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/index.rst.automodapi b/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/index.rst.automodapi new file mode 100644 index 0000000..941dcac --- /dev/null +++ b/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/index.rst.automodapi @@ -0,0 +1,19 @@ + +sphinx_automodapi.tests.example_module.attribute_class Module +------------------------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module.attribute_class + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module.attribute_class + :classes-only: + :toctree: api + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module.attribute_class + :private-bases: + :parts: 1 diff --git a/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/index.rst.automodsumm b/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/index.rst.automodsumm new file mode 100644 index 0000000..9aafd6b --- /dev/null +++ b/sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/index.rst.automodsumm @@ -0,0 +1,6 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module.attribute_class + +.. autosummary:: + :toctree: api + + ClassWithAttribute diff --git a/sphinx_automodapi/tests/cases/classes_no_inherit/output/api/sphinx_automodapi.tests.example_module.classes.Egg.rst b/sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst similarity index 100% rename from sphinx_automodapi/tests/cases/classes_no_inherit/output/api/sphinx_automodapi.tests.example_module.classes.Egg.rst rename to sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst diff --git a/sphinx_automodapi/tests/cases/classes_no_inherit/output/index.rst.automodapi b/sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_attr/index.rst.automodapi similarity index 100% rename from sphinx_automodapi/tests/cases/classes_no_inherit/output/index.rst.automodapi rename to sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_attr/index.rst.automodapi diff --git a/sphinx_automodapi/tests/cases/classes_no_inherit/output/index.rst.automodsumm b/sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_attr/index.rst.automodsumm similarity index 100% rename from sphinx_automodapi/tests/cases/classes_no_inherit/output/index.rst.automodsumm rename to sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_attr/index.rst.automodsumm diff --git a/sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst b/sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst new file mode 100644 index 0000000..07638af --- /dev/null +++ b/sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst @@ -0,0 +1,29 @@ +Egg +=== + +.. currentmodule:: sphinx_automodapi.tests.example_module.classes + +.. autoclass:: Egg + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Egg.weight + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Egg.buy + ~Egg.eat + + .. rubric:: Attributes Documentation + + .. autoproperty:: weight + + .. rubric:: Methods Documentation + + .. automethod:: buy + .. automethod:: eat diff --git a/sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_not_attr/index.rst.automodapi b/sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_not_attr/index.rst.automodapi new file mode 100644 index 0000000..79a2621 --- /dev/null +++ b/sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_not_attr/index.rst.automodapi @@ -0,0 +1,21 @@ + +sphinx_automodapi.tests.example_module.classes Module +----------------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module.classes + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module.classes + :classes-only: + :toctree: api + :skip: Spam + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module.classes + :private-bases: + :parts: 1 + :skip: Spam diff --git a/sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_not_attr/index.rst.automodsumm b/sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_not_attr/index.rst.automodsumm new file mode 100644 index 0000000..966572f --- /dev/null +++ b/sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_not_attr/index.rst.automodsumm @@ -0,0 +1,6 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module.classes + +.. autosummary:: + :toctree: api + + Egg diff --git a/sphinx_automodapi/tests/cases/classes_with_inherit/output/api/sphinx_automodapi.tests.example_module.classes.Egg.rst b/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst similarity index 100% rename from sphinx_automodapi/tests/cases/classes_with_inherit/output/api/sphinx_automodapi.tests.example_module.classes.Egg.rst rename to sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst diff --git a/sphinx_automodapi/tests/cases/classes_with_inherit/output/api/sphinx_automodapi.tests.example_module.classes.Spam.rst b/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Spam.rst similarity index 100% rename from sphinx_automodapi/tests/cases/classes_with_inherit/output/api/sphinx_automodapi.tests.example_module.classes.Spam.rst rename to sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Spam.rst diff --git a/sphinx_automodapi/tests/cases/classes_with_inherit/output/index.rst.automodapi b/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_attr/index.rst.automodapi similarity index 100% rename from sphinx_automodapi/tests/cases/classes_with_inherit/output/index.rst.automodapi rename to sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_attr/index.rst.automodapi diff --git a/sphinx_automodapi/tests/cases/classes_with_inherit/output/index.rst.automodsumm b/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_attr/index.rst.automodsumm similarity index 100% rename from sphinx_automodapi/tests/cases/classes_with_inherit/output/index.rst.automodsumm rename to sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_attr/index.rst.automodsumm diff --git a/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst b/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst new file mode 100644 index 0000000..07638af --- /dev/null +++ b/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst @@ -0,0 +1,29 @@ +Egg +=== + +.. currentmodule:: sphinx_automodapi.tests.example_module.classes + +.. autoclass:: Egg + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Egg.weight + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Egg.buy + ~Egg.eat + + .. rubric:: Attributes Documentation + + .. autoproperty:: weight + + .. rubric:: Methods Documentation + + .. automethod:: buy + .. automethod:: eat diff --git a/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Spam.rst b/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Spam.rst new file mode 100644 index 0000000..b635876 --- /dev/null +++ b/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Spam.rst @@ -0,0 +1,7 @@ +Spam +==== + +.. currentmodule:: sphinx_automodapi.tests.example_module.classes + +.. autoclass:: Spam + :show-inheritance: diff --git a/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/index.rst.automodapi b/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/index.rst.automodapi new file mode 100644 index 0000000..467c878 --- /dev/null +++ b/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/index.rst.automodapi @@ -0,0 +1,19 @@ + +sphinx_automodapi.tests.example_module.classes Module +----------------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module.classes + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module.classes + :classes-only: + :toctree: api + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module.classes + :private-bases: + :parts: 1 diff --git a/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/index.rst.automodsumm b/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/index.rst.automodsumm new file mode 100644 index 0000000..22da840 --- /dev/null +++ b/sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/index.rst.automodsumm @@ -0,0 +1,7 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module.classes + +.. autosummary:: + :toctree: api + + Spam + Egg diff --git a/sphinx_automodapi/tests/cases/inherited_members/output/api/sphinx_automodapi.tests.example_module.classes.Egg.rst b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst similarity index 100% rename from sphinx_automodapi/tests/cases/inherited_members/output/api/sphinx_automodapi.tests.example_module.classes.Egg.rst rename to sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst diff --git a/sphinx_automodapi/tests/cases/inherited_members/output/api/sphinx_automodapi.tests.example_module.classes.Spam.rst b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Spam.rst similarity index 100% rename from sphinx_automodapi/tests/cases/inherited_members/output/api/sphinx_automodapi.tests.example_module.classes.Spam.rst rename to sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Spam.rst diff --git a/sphinx_automodapi/tests/cases/inherited_members/output/api/sphinx_automodapi.tests.example_module.other_classes.Foo.rst b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.other_classes.Foo.rst similarity index 100% rename from sphinx_automodapi/tests/cases/inherited_members/output/api/sphinx_automodapi.tests.example_module.other_classes.Foo.rst rename to sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.other_classes.Foo.rst diff --git a/sphinx_automodapi/tests/cases/inherited_members/output/index.rst.automodapi b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/index.rst.automodapi similarity index 100% rename from sphinx_automodapi/tests/cases/inherited_members/output/index.rst.automodapi rename to sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/index.rst.automodapi diff --git a/sphinx_automodapi/tests/cases/inherited_members/output/index.rst.automodsumm b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/index.rst.automodsumm similarity index 100% rename from sphinx_automodapi/tests/cases/inherited_members/output/index.rst.automodsumm rename to sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/index.rst.automodsumm diff --git a/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst new file mode 100644 index 0000000..07638af --- /dev/null +++ b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst @@ -0,0 +1,29 @@ +Egg +=== + +.. currentmodule:: sphinx_automodapi.tests.example_module.classes + +.. autoclass:: Egg + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Egg.weight + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Egg.buy + ~Egg.eat + + .. rubric:: Attributes Documentation + + .. autoproperty:: weight + + .. rubric:: Methods Documentation + + .. automethod:: buy + .. automethod:: eat diff --git a/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Spam.rst b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Spam.rst new file mode 100644 index 0000000..e37d6b2 --- /dev/null +++ b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Spam.rst @@ -0,0 +1,19 @@ +Spam +==== + +.. currentmodule:: sphinx_automodapi.tests.example_module.classes + +.. autoclass:: Spam + :show-inheritance: + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Spam.buy + ~Spam.eat + + .. rubric:: Methods Documentation + + .. automethod:: buy + .. automethod:: eat diff --git a/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.other_classes.Foo.rst b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.other_classes.Foo.rst new file mode 100644 index 0000000..80e8330 --- /dev/null +++ b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.other_classes.Foo.rst @@ -0,0 +1,17 @@ +Foo +=== + +.. currentmodule:: sphinx_automodapi.tests.example_module.other_classes + +.. autoclass:: Foo + :show-inheritance: + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Foo.hmm + + .. rubric:: Methods Documentation + + .. automethod:: hmm diff --git a/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/index.rst.automodapi b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/index.rst.automodapi new file mode 100644 index 0000000..dc0e6ff --- /dev/null +++ b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/index.rst.automodapi @@ -0,0 +1,41 @@ + +sphinx_automodapi.tests.example_module.classes Module +----------------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module.classes + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module.classes + :classes-only: + :toctree: api + :inherited-members: + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module.classes + :private-bases: + :parts: 1 + + + +sphinx_automodapi.tests.example_module.other_classes Module +----------------------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module.other_classes + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module.other_classes + :classes-only: + :toctree: api + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module.other_classes + :private-bases: + :parts: 1 diff --git a/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/index.rst.automodsumm b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/index.rst.automodsumm new file mode 100644 index 0000000..51a0974 --- /dev/null +++ b/sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/index.rst.automodsumm @@ -0,0 +1,14 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module.classes + +.. autosummary:: + :toctree: api + :inherited-members: + + Spam + Egg +.. currentmodule:: sphinx_automodapi.tests.example_module.other_classes + +.. autosummary:: + :toctree: api + + Foo diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel/output/api/sphinx_automodapi.tests.example_module.Egg.rst b/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Egg.rst similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel/output/api/sphinx_automodapi.tests.example_module.Egg.rst rename to sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Egg.rst diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.Spam.rst b/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.Spam.rst rename to sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel/output/api/sphinx_automodapi.tests.example_module.add.rst b/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.add.rst similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel/output/api/sphinx_automodapi.tests.example_module.add.rst rename to sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.add.rst diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel/output/api/sphinx_automodapi.tests.example_module.multiply.rst b/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.multiply.rst similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel/output/api/sphinx_automodapi.tests.example_module.multiply.rst rename to sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.multiply.rst diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel/output/index.rst.automodapi b/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/index.rst.automodapi similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel/output/index.rst.automodapi rename to sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/index.rst.automodapi diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel/output/index.rst.automodsumm b/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/index.rst.automodsumm similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel/output/index.rst.automodsumm rename to sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/index.rst.automodsumm diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst b/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst new file mode 100644 index 0000000..f8d762a --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst @@ -0,0 +1,29 @@ +Egg +=== + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autoclass:: Egg + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Egg.weight + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Egg.buy + ~Egg.eat + + .. rubric:: Attributes Documentation + + .. autoproperty:: weight + + .. rubric:: Methods Documentation + + .. automethod:: buy + .. automethod:: eat diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output/api/sphinx_automodapi.tests.example_module.Spam.rst b/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output/api/sphinx_automodapi.tests.example_module.Spam.rst rename to sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.add.rst b/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.add.rst similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.add.rst rename to sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.add.rst diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.multiply.rst b/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.multiply.rst similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.multiply.rst rename to sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.multiply.rst diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/index.rst.automodapi b/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/index.rst.automodapi new file mode 100644 index 0000000..2821ea1 --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/index.rst.automodapi @@ -0,0 +1,26 @@ + +sphinx_automodapi.tests.example_module Package +---------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module + +Functions +^^^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module + :functions-only: + :toctree: api + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module + :classes-only: + :toctree: api + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module + :private-bases: + :parts: 1 diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output/index.rst.automodsumm b/sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/index.rst.automodsumm similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output/index.rst.automodsumm rename to sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/index.rst.automodsumm diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.Egg.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Egg.rst similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.Egg.rst rename to sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Egg.rst diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.FUNNY_WALK_STEPS.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.FUNNY_WALK_STEPS.rst similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.FUNNY_WALK_STEPS.rst rename to sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.FUNNY_WALK_STEPS.rst diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.PARROT_STATE.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.PARROT_STATE.rst similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.PARROT_STATE.rst rename to sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.PARROT_STATE.rst diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst new file mode 100644 index 0000000..6d769e7 --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst @@ -0,0 +1,7 @@ +Spam +==== + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autoclass:: Spam + :show-inheritance: diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output/api/sphinx_automodapi.tests.example_module.add.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.add.rst similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output/api/sphinx_automodapi.tests.example_module.add.rst rename to sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.add.rst diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output/api/sphinx_automodapi.tests.example_module.multiply.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.multiply.rst similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output/api/sphinx_automodapi.tests.example_module.multiply.rst rename to sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.multiply.rst diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/index.rst.automodapi b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/index.rst.automodapi similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/index.rst.automodapi rename to sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/index.rst.automodapi diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/index.rst.automodsumm b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/index.rst.automodsumm similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/index.rst.automodsumm rename to sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/index.rst.automodsumm diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst new file mode 100644 index 0000000..f8d762a --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst @@ -0,0 +1,29 @@ +Egg +=== + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autoclass:: Egg + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Egg.weight + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Egg.buy + ~Egg.eat + + .. rubric:: Attributes Documentation + + .. autoproperty:: weight + + .. rubric:: Methods Documentation + + .. automethod:: buy + .. automethod:: eat diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.FUNNY_WALK_STEPS.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.FUNNY_WALK_STEPS.rst new file mode 100644 index 0000000..11fa366 --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.FUNNY_WALK_STEPS.rst @@ -0,0 +1,6 @@ +FUNNY_WALK_STEPS +================ + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autodata:: FUNNY_WALK_STEPS diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.PARROT_STATE.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.PARROT_STATE.rst new file mode 100644 index 0000000..f720dbd --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.PARROT_STATE.rst @@ -0,0 +1,6 @@ +PARROT_STATE +============ + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autodata:: PARROT_STATE diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst new file mode 100644 index 0000000..6d769e7 --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst @@ -0,0 +1,7 @@ +Spam +==== + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autoclass:: Spam + :show-inheritance: diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.add.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.add.rst new file mode 100644 index 0000000..7b2b01a --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.add.rst @@ -0,0 +1,6 @@ +add +=== + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autofunction:: add diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.multiply.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.multiply.rst new file mode 100644 index 0000000..41e5e00 --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.multiply.rst @@ -0,0 +1,6 @@ +multiply +======== + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autofunction:: multiply diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/index.rst.automodapi b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/index.rst.automodapi new file mode 100644 index 0000000..76ea9e4 --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/index.rst.automodapi @@ -0,0 +1,33 @@ + +sphinx_automodapi.tests.example_module Package +---------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module + +Functions +^^^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module + :functions-only: + :toctree: api + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module + :classes-only: + :toctree: api + +Variables +^^^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module + :variables-only: + :toctree: api + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module + :private-bases: + :parts: 1 diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/index.rst.automodsumm b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/index.rst.automodsumm new file mode 100644 index 0000000..cc706fe --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/index.rst.automodsumm @@ -0,0 +1,22 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autosummary:: + :toctree: api + + add + multiply + subtract +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autosummary:: + :toctree: api + + Egg + Spam +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autosummary:: + :toctree: api + + FUNNY_WALK_STEPS + PARROT_STATE diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output/api/sphinx_automodapi.tests.example_module.Egg.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Egg.rst similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output/api/sphinx_automodapi.tests.example_module.Egg.rst rename to sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Egg.rst diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst new file mode 100644 index 0000000..6d769e7 --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst @@ -0,0 +1,7 @@ +Spam +==== + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autoclass:: Spam + :show-inheritance: diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.add.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.add.rst new file mode 100644 index 0000000..7b2b01a --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.add.rst @@ -0,0 +1,6 @@ +add +=== + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autofunction:: add diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.multiply.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.multiply.rst new file mode 100644 index 0000000..41e5e00 --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.multiply.rst @@ -0,0 +1,6 @@ +multiply +======== + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autofunction:: multiply diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output/index.rst.automodapi b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/index.rst.automodapi similarity index 100% rename from sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output/index.rst.automodapi rename to sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/index.rst.automodapi diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/index.rst.automodsumm b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/index.rst.automodsumm new file mode 100644 index 0000000..86235af --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/index.rst.automodsumm @@ -0,0 +1,15 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autosummary:: + :toctree: api + + add + multiply + subtract +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autosummary:: + :toctree: api + + Egg + Spam diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst new file mode 100644 index 0000000..f8d762a --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst @@ -0,0 +1,29 @@ +Egg +=== + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autoclass:: Egg + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Egg.weight + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Egg.buy + ~Egg.eat + + .. rubric:: Attributes Documentation + + .. autoproperty:: weight + + .. rubric:: Methods Documentation + + .. automethod:: buy + .. automethod:: eat diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst new file mode 100644 index 0000000..6d769e7 --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst @@ -0,0 +1,7 @@ +Spam +==== + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autoclass:: Spam + :show-inheritance: diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.add.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.add.rst new file mode 100644 index 0000000..7b2b01a --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.add.rst @@ -0,0 +1,6 @@ +add +=== + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autofunction:: add diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.multiply.rst b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.multiply.rst new file mode 100644 index 0000000..41e5e00 --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.multiply.rst @@ -0,0 +1,6 @@ +multiply +======== + +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autofunction:: multiply diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/index.rst.automodapi b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/index.rst.automodapi new file mode 100644 index 0000000..f602813 --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/index.rst.automodapi @@ -0,0 +1,19 @@ + +sphinx_automodapi.tests.example_module Package +---------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module + +Functions +^^^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module + :functions-only: + :toctree: api + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module + :classes-only: + :toctree: api diff --git a/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/index.rst.automodsumm b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/index.rst.automodsumm new file mode 100644 index 0000000..86235af --- /dev/null +++ b/sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/index.rst.automodsumm @@ -0,0 +1,15 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autosummary:: + :toctree: api + + add + multiply + subtract +.. currentmodule:: sphinx_automodapi.tests.example_module + +.. autosummary:: + :toctree: api + + Egg + Spam diff --git a/sphinx_automodapi/tests/cases/non_ascii/input/index.rst b/sphinx_automodapi/tests/cases/non_ascii/input/index.rst index a0275eb..dc7cf3b 100644 --- a/sphinx_automodapi/tests/cases/non_ascii/input/index.rst +++ b/sphinx_automodapi/tests/cases/non_ascii/input/index.rst @@ -1,3 +1,4 @@ Ceçi est un exemple qui inclus des charactères non-ASCII .. automodapi:: sphinx_automodapi.tests.example_module.functions +.. automodapi:: sphinx_automodapi.tests.example_module.nonascii diff --git "a/sphinx_automodapi/tests/cases/non_ascii/output/api/sphinx_automodapi.tests.example_module.nonascii.NonAscii\303\204\303\266\303\274\303\237\305\221.rst" "b/sphinx_automodapi/tests/cases/non_ascii/output/api/sphinx_automodapi.tests.example_module.nonascii.NonAscii\303\204\303\266\303\274\303\237\305\221.rst" new file mode 100644 index 0000000..caab61b --- /dev/null +++ "b/sphinx_automodapi/tests/cases/non_ascii/output/api/sphinx_automodapi.tests.example_module.nonascii.NonAscii\303\204\303\266\303\274\303\237\305\221.rst" @@ -0,0 +1,19 @@ +NonAsciiÄöüßő +============= + +.. currentmodule:: sphinx_automodapi.tests.example_module.nonascii + +.. autoclass:: NonAsciiÄöüßő + :show-inheritance: + + .. rubric:: Methods Summary + + .. autosummary:: + + ~NonAsciiÄöüßő.get_ß + ~NonAsciiÄöüßő.get_äöü + + .. rubric:: Methods Documentation + + .. automethod:: get_ß + .. automethod:: get_äöü diff --git a/sphinx_automodapi/tests/cases/non_ascii/output/index.rst.automodapi b/sphinx_automodapi/tests/cases/non_ascii/output/index.rst.automodapi index a80b228..f7e71cd 100644 --- a/sphinx_automodapi/tests/cases/non_ascii/output/index.rst.automodapi +++ b/sphinx_automodapi/tests/cases/non_ascii/output/index.rst.automodapi @@ -12,3 +12,23 @@ Functions .. automodsumm:: sphinx_automodapi.tests.example_module.functions :functions-only: :toctree: api + + +sphinx_automodapi.tests.example_module.nonascii Module +------------------------------------------------------ + +.. automodule:: sphinx_automodapi.tests.example_module.nonascii + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module.nonascii + :classes-only: + :toctree: api + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module.nonascii + :private-bases: + :parts: 1 diff --git a/sphinx_automodapi/tests/cases/non_ascii/output/index.rst.automodsumm b/sphinx_automodapi/tests/cases/non_ascii/output/index.rst.automodsumm index 8aa64a3..1d99fca 100644 --- a/sphinx_automodapi/tests/cases/non_ascii/output/index.rst.automodsumm +++ b/sphinx_automodapi/tests/cases/non_ascii/output/index.rst.automodsumm @@ -6,3 +6,10 @@ add subtract multiply +.. currentmodule:: sphinx_automodapi.tests.example_module.nonascii + +.. autosummary:: + :toctree: api + + NonAsciiÄöüßő + diff --git a/sphinx_automodapi/tests/cases/public_from_private/README.md b/sphinx_automodapi/tests/cases/public_from_private/README.md new file mode 100644 index 0000000..0381ea2 --- /dev/null +++ b/sphinx_automodapi/tests/cases/public_from_private/README.md @@ -0,0 +1,2 @@ +Importing a class from a private submodule to a public submodule +at the same level of hierarchy in the module. diff --git a/sphinx_automodapi/tests/cases/public_from_private/input/index.rst b/sphinx_automodapi/tests/cases/public_from_private/input/index.rst new file mode 100644 index 0000000..37d01fa --- /dev/null +++ b/sphinx_automodapi/tests/cases/public_from_private/input/index.rst @@ -0,0 +1 @@ +.. automodapi:: sphinx_automodapi.tests.example_module.public diff --git a/sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Camelot.rst b/sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Camelot.rst new file mode 100644 index 0000000..becaa5a --- /dev/null +++ b/sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Camelot.rst @@ -0,0 +1,7 @@ +Camelot +======= + +.. currentmodule:: sphinx_automodapi.tests.example_module.public + +.. autoclass:: Camelot + :show-inheritance: diff --git a/sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Spam.rst b/sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Spam.rst new file mode 100644 index 0000000..bf19304 --- /dev/null +++ b/sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Spam.rst @@ -0,0 +1,7 @@ +Spam +==== + +.. currentmodule:: sphinx_automodapi.tests.example_module.public + +.. autoclass:: Spam + :show-inheritance: diff --git a/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodapi b/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodapi new file mode 100644 index 0000000..d285595 --- /dev/null +++ b/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodapi @@ -0,0 +1,19 @@ + +sphinx_automodapi.tests.example_module.public Module +---------------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module.public + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module.public + :classes-only: + :toctree: api + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module.public + :private-bases: + :parts: 1 diff --git a/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodsumm b/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodsumm new file mode 100644 index 0000000..7eade32 --- /dev/null +++ b/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodsumm @@ -0,0 +1,7 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module.public + +.. autosummary:: + :toctree: api + + Camelot + Spam diff --git a/sphinx_automodapi/tests/cases/slots/README.md b/sphinx_automodapi/tests/cases/slots/README.md new file mode 100644 index 0000000..1b95d31 --- /dev/null +++ b/sphinx_automodapi/tests/cases/slots/README.md @@ -0,0 +1 @@ +Test classes that put attributes in `__slots__`. \ No newline at end of file diff --git a/sphinx_automodapi/tests/cases/slots/input/index.rst b/sphinx_automodapi/tests/cases/slots/input/index.rst new file mode 100644 index 0000000..fdf9586 --- /dev/null +++ b/sphinx_automodapi/tests/cases/slots/input/index.rst @@ -0,0 +1 @@ +.. automodapi:: sphinx_automodapi.tests.example_module.slots diff --git a/sphinx_automodapi/tests/cases/slots/output/api/sphinx_automodapi.tests.example_module.slots.DerivedParam.rst b/sphinx_automodapi/tests/cases/slots/output/api/sphinx_automodapi.tests.example_module.slots.DerivedParam.rst new file mode 100644 index 0000000..bf65bf4 --- /dev/null +++ b/sphinx_automodapi/tests/cases/slots/output/api/sphinx_automodapi.tests.example_module.slots.DerivedParam.rst @@ -0,0 +1,17 @@ +DerivedParam +============ + +.. currentmodule:: sphinx_automodapi.tests.example_module.slots + +.. autoclass:: DerivedParam + :show-inheritance: + + .. rubric:: Methods Summary + + .. autosummary:: + + ~DerivedParam.derived_from_slot_class_method + + .. rubric:: Methods Documentation + + .. automethod:: derived_from_slot_class_method diff --git a/sphinx_automodapi/tests/cases/slots/output/api/sphinx_automodapi.tests.example_module.slots.DerivedSlotParam.rst b/sphinx_automodapi/tests/cases/slots/output/api/sphinx_automodapi.tests.example_module.slots.DerivedSlotParam.rst new file mode 100644 index 0000000..3a2438c --- /dev/null +++ b/sphinx_automodapi/tests/cases/slots/output/api/sphinx_automodapi.tests.example_module.slots.DerivedSlotParam.rst @@ -0,0 +1,27 @@ +DerivedSlotParam +================ + +.. currentmodule:: sphinx_automodapi.tests.example_module.slots + +.. autoclass:: DerivedSlotParam + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~DerivedSlotParam.extra_attr + + .. rubric:: Methods Summary + + .. autosummary:: + + ~DerivedSlotParam.derived_from_slot_class_method + + .. rubric:: Attributes Documentation + + .. autoattribute:: extra_attr + + .. rubric:: Methods Documentation + + .. automethod:: derived_from_slot_class_method diff --git a/sphinx_automodapi/tests/cases/slots/output/api/sphinx_automodapi.tests.example_module.slots.SlotDict.rst b/sphinx_automodapi/tests/cases/slots/output/api/sphinx_automodapi.tests.example_module.slots.SlotDict.rst new file mode 100644 index 0000000..ccdf348 --- /dev/null +++ b/sphinx_automodapi/tests/cases/slots/output/api/sphinx_automodapi.tests.example_module.slots.SlotDict.rst @@ -0,0 +1,29 @@ +SlotDict +======== + +.. currentmodule:: sphinx_automodapi.tests.example_module.slots + +.. autoclass:: SlotDict + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~SlotDict.class_attr + ~SlotDict.instance_attr + + .. rubric:: Methods Summary + + .. autosummary:: + + ~SlotDict.my_method + + .. rubric:: Attributes Documentation + + .. autoattribute:: class_attr + .. autoattribute:: instance_attr + + .. rubric:: Methods Documentation + + .. automethod:: my_method diff --git a/sphinx_automodapi/tests/cases/slots/output/index.rst.automodapi b/sphinx_automodapi/tests/cases/slots/output/index.rst.automodapi new file mode 100644 index 0000000..487ab9f --- /dev/null +++ b/sphinx_automodapi/tests/cases/slots/output/index.rst.automodapi @@ -0,0 +1,19 @@ + +sphinx_automodapi.tests.example_module.slots Module +--------------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module.slots + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module.slots + :classes-only: + :toctree: api + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module.slots + :private-bases: + :parts: 1 diff --git a/sphinx_automodapi/tests/cases/slots/output/index.rst.automodsumm b/sphinx_automodapi/tests/cases/slots/output/index.rst.automodsumm new file mode 100644 index 0000000..83b7aa7 --- /dev/null +++ b/sphinx_automodapi/tests/cases/slots/output/index.rst.automodsumm @@ -0,0 +1,8 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module.slots + +.. autosummary:: + :toctree: api + + SlotDict + DerivedParam + DerivedSlotParam 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 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..b3a40ef --- /dev/null +++ b/sphinx_automodapi/tests/duplicated_warning/docs/conf.py @@ -0,0 +1,11 @@ +project = 'duplicated' +copyright = '2022, Maximilian Linhoff' +author = 'Maximilian Linhoff' +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..c706ea3 --- /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(): + '''Awesome baz function''' diff --git a/sphinx_automodapi/tests/example_module/_private.py b/sphinx_automodapi/tests/example_module/_private.py new file mode 100644 index 0000000..d10c9db --- /dev/null +++ b/sphinx_automodapi/tests/example_module/_private.py @@ -0,0 +1,4 @@ +class Camelot: + """ + It's a silly place anyway + """ 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'] diff --git a/sphinx_automodapi/tests/example_module/attribute_class.py b/sphinx_automodapi/tests/example_module/attribute_class.py new file mode 100644 index 0000000..cc625f7 --- /dev/null +++ b/sphinx_automodapi/tests/example_module/attribute_class.py @@ -0,0 +1,12 @@ +class ClassWithAttribute(object): + """A class with an attribute.""" + my_attribute = 1 + + def my_method(self): + """A method.""" + pass + + @property + def my_property(self): + """A property.""" + return 1 diff --git a/sphinx_automodapi/tests/example_module/nonascii.py b/sphinx_automodapi/tests/example_module/nonascii.py new file mode 100644 index 0000000..4928b78 --- /dev/null +++ b/sphinx_automodapi/tests/example_module/nonascii.py @@ -0,0 +1,15 @@ +__all__ = ['NonAsciiÄöüßő'] + + +class NonAsciiÄöüßő(object): + def get_äöü(self): + """ + Return a string with common umlauts like äöüß + """ + return 'äöü' + + def get_ß(self): + """ + Return a string with the eszett symbol + """ + return 'ß' diff --git a/sphinx_automodapi/tests/example_module/public.py b/sphinx_automodapi/tests/example_module/public.py new file mode 100644 index 0000000..035a9b2 --- /dev/null +++ b/sphinx_automodapi/tests/example_module/public.py @@ -0,0 +1,7 @@ +from ._private import Camelot +from .classes import Spam + +__all__ = [ + 'Camelot', + 'Spam' +] diff --git a/sphinx_automodapi/tests/example_module/slots.py b/sphinx_automodapi/tests/example_module/slots.py new file mode 100644 index 0000000..ee9e0fd --- /dev/null +++ b/sphinx_automodapi/tests/example_module/slots.py @@ -0,0 +1,116 @@ +"""Test classes containing __slots__ + +Instance attributes named in ``__slots__`` can be introspected and are listed +in the Attributes section of the class documentation. Class attributes are +listed in the same section of the generated docs so docstrings should be used +to distinguish class attributes vs instance attributes. Regular instance +attributes are dynamically inserted into ``__dict__`` and cannot be reliably +introspected so they're not included in the documentation. +""" +from __future__ import annotations + +__all__ = ['SlotDict', 'DerivedParam', 'DerivedSlotParam',] + + +class SlotDict(object): + """ + A class that uses __slots__ and __dict__ for its attribute namespace. + """ + __slots__ = { + "instance_attr": "instance attribute docstring can be added here", + "__dict__": None, # Allows additional instance attributes to be added + } + + class_attr = "class attribute value" + """(class attr) this is a class attribute.""" + + def __init__(self, param: str, other_param: str): + """ + Initializes a SlotDict object. + + Parameters + ---------- + param : str + A parameter + other_param : str + Another parameter + """ + + self.instance_attr = param + """Instance attributes declared in slots can also define their docstring + here + """ + + if other_param is not None: + self.other_attr = other_param + """This instance attribute is dynamic (not declared in a slot) so + it's not included in the docs + """ + + def my_method(self): + """ + Prints the SlotDict parameters. + """ + print(f"instance_attr: {self.instance_attr}") + print(f"other_attr: {self.other_attr}") + + +class DerivedParam(SlotDict): + """ + Extends SlotDict by adding an extra parameter + """ + def __init__(self, param: str, other_param: str, extra_param: str): + """ + Initializes a DerivedParam object. + + Parameters + ---------- + param : str + A parameter + other_param : str + Another parameter + extra_param : str + An extra parameter + """ + super(DerivedParam, self).__init__(param, other_param) + self.extra_attr = extra_param + + def derived_from_slot_class_method(self): + """ + Prints the DerivedParam parameters. + """ + print(f"instance_attr: {self.instance_attr}") + print(f"other_attr: {self.other_attr}") + print(f"extra_attr: {self.extra_attr}") + + +class DerivedSlotParam(SlotDict): + """ + Extends SlotDict by adding a slot parameter + """ + + __slots__ = ('extra_attr',) + + def __init__(self, param: str, other_param: str, extra_param: str): + """ + Initializes a DerivedSlotParam object. + + Parameters + ---------- + param : str + A parameter + other_param : str + Another parameter + extra_param : str + An extra parameter + """ + super(DerivedSlotParam, self).__init__(param, other_param) + self.extra_attr = extra_param + + def derived_from_slot_class_method(self): + """ + Prints the DerivedSlotParam parameters. + """ + print(f"instance_attr: {self.instance_attr}") + print(f"other_attr: {self.other_attr}") + print(f"extra_attr: {self.extra_attr}") diff --git a/sphinx_automodapi/tests/helpers.py b/sphinx_automodapi/tests/helpers.py index 01b3510..5fb34a0 100644 --- a/sphinx_automodapi/tests/helpers.py +++ b/sphinx_automodapi/tests/helpers.py @@ -2,7 +2,6 @@ # Licensed under a 3-clause BSD style license - see LICENSE.rst import os -import sys from copy import deepcopy from sphinx.cmd.build import build_main @@ -13,8 +12,8 @@ intersphinx_mapping = { - 'python': ('https://docs.python.org/{0}/'.format(sys.version_info[0]), None) - } + 'python': ('https://docs.python.org/3/', None) +} DEFAULT_CONF = {'source_suffix': '.rst', 'master_doc': 'index', diff --git a/sphinx_automodapi/tests/test_autodoc_enhancements.py b/sphinx_automodapi/tests/test_autodoc_enhancements.py index 3f3860c..bd1fc36 100644 --- a/sphinx_automodapi/tests/test_autodoc_enhancements.py +++ b/sphinx_automodapi/tests/test_autodoc_enhancements.py @@ -1,5 +1,3 @@ -import sys - from textwrap import dedent import pytest @@ -15,23 +13,11 @@ def foo(cls): return 'foo' -if sys.version_info[0] < 3: - exec(dedent(""" - class MyClass(object): - __metaclass__ = Meta - @property - def foo(self): - \"\"\"Docstring for MyClass.foo property.\"\"\" - return 'myfoo' - """)) -else: - exec(dedent(""" - class MyClass(metaclass=Meta): - @property - def foo(self): - \"\"\"Docstring for MyClass.foo property.\"\"\" - return 'myfoo' - """)) +class MyClass(metaclass=Meta): + @property + def foo(self): + """Docstring for MyClass.foo property.""" + return 'myfoo' def test_type_attrgetter(): @@ -55,3 +41,20 @@ def test_type_attrgetter(): assert type_object_attrgetter(MyClass, 'susy', 'default') == 'default' assert type_object_attrgetter(MyClass, '__dict__') == MyClass.__dict__ + + +def test_type_attrgetter_for_dataclass(): + """ + This tests the attribute getter for non-default dataclass fields + """ + import dataclasses + + @dataclasses.dataclass + class MyDataclass: + foo: int + bar: str = "bar value" + + with pytest.raises(AttributeError): + getattr(MyDataclass, 'foo') + assert type_object_attrgetter(MyDataclass, 'foo') == dataclasses.MISSING + assert getattr(MyDataclass, 'bar') == 'bar value' diff --git a/sphinx_automodapi/tests/test_automodapi.py b/sphinx_automodapi/tests/test_automodapi.py index 72e52fd..1cf21e2 100644 --- a/sphinx_automodapi/tests/test_automodapi.py +++ b/sphinx_automodapi/tests/test_automodapi.py @@ -1,7 +1,6 @@ # -*- coding: utf-8 -*- # Licensed under a 3-clause BSD style license - see LICENSE.rst -import sys from copy import copy import pytest @@ -10,11 +9,6 @@ from . import cython_testpackage # noqa from .helpers import run_sphinx_in_tmpdir -if sys.version_info[0] == 2: - from io import open as io_open -else: - io_open = open - def setup_function(func): # This can be replaced with the docutils_namespace context manager once @@ -104,7 +98,7 @@ def test_am_replacer_writereprocessed(tmpdir, writereprocessed): Tests the automodapi_writereprocessed option """ - with io_open(tmpdir.join('index.rst').strpath, 'w', encoding='utf-8') as f: + with open(tmpdir.join('index.rst').strpath, 'w', encoding='utf-8') as f: f.write(am_replacer_repr_str.format(options='')) run_sphinx_in_tmpdir(tmpdir, additional_conf={'automodapi_writereprocessed': writereprocessed}) diff --git a/sphinx_automodapi/tests/test_automodsumm.py b/sphinx_automodapi/tests/test_automodsumm.py index fe14e9f..3922faa 100644 --- a/sphinx_automodapi/tests/test_automodsumm.py +++ b/sphinx_automodapi/tests/test_automodsumm.py @@ -201,3 +201,51 @@ def test_ams_cython(tmpdir, cython_testpackage): # noqa result = f.read() assert result == ams_cython_expected + + +# ============================================================================= + +CLASS_RST = """ +:orphan: + +.. currentmodule:: {mod} + +.. autoclass:: {cls} +""".strip() + +sorted_str = """ +Before + +.. automodsumm:: sphinx_automodapi.tests.example_module.classes + :sort: + +And After +""" + +sorted_expected = """\ +.. currentmodule:: sphinx_automodapi.tests.example_module.classes + +.. autosummary:: + + Egg + Spam + +""" + + +def test_sort(tmpdir): + with open(tmpdir.join("index.rst").strpath, "w") as f: + f.write(sorted_str) + + apidir = tmpdir.mkdir('api') + mod = 'sphinx_automodapi.tests.example_module.classes' + for cls in "Spam", "Egg": + with open(apidir.join(f'{mod}.{cls}.rst').strpath, 'w') as f: + f.write(CLASS_RST.format(mod=mod, cls=cls)) + + run_sphinx_in_tmpdir(tmpdir) + + with open(tmpdir.join("index.rst.automodsumm").strpath) as f: + result = f.read() + + assert result == sorted_expected diff --git a/sphinx_automodapi/tests/test_cases.py b/sphinx_automodapi/tests/test_cases.py index 72f6140..487c904 100644 --- a/sphinx_automodapi/tests/test_cases.py +++ b/sphinx_automodapi/tests/test_cases.py @@ -4,8 +4,6 @@ # We store different cases in the cases sub-directory of the tests directory import os -import io -import sys import glob import shutil from itertools import product @@ -23,11 +21,12 @@ CASES_DIRS = glob.glob(os.path.join(CASES_ROOT, '*')) PARALLEL = {False, True} +PROP_ATTR = {True, False} intersphinx_mapping = { - 'python': ('https://docs.python.org/{0}/'.format(sys.version_info[0]), None) - } + 'python': ('https://docs.python.org/3/', None) +} DEFAULT_CONF = {'source_suffix': '.rst', 'master_doc': 'index', @@ -60,18 +59,23 @@ def teardown_function(func): roles._roles = func._roles -@pytest.mark.parametrize(('case_dir', 'parallel'), product(CASES_DIRS, PARALLEL)) -def test_run_full_case(tmpdir, case_dir, parallel): +@pytest.mark.parametrize(('case_dir', 'parallel', 'prop_attr'), product(CASES_DIRS, PARALLEL, PROP_ATTR)) +def test_run_full_case(tmpdir, case_dir, parallel, prop_attr): input_dir = os.path.join(case_dir, 'input') - output_dir = os.path.join(case_dir, 'output') + + output_folder = "output_prop_is_attr" if prop_attr else "output_prop_is_not_attr" + output_dir = os.path.join(case_dir, output_folder) + if not os.path.isdir(output_dir): + output_dir = os.path.join(case_dir, 'output') docs_dir = tmpdir.mkdir('docs').strpath conf = deepcopy(DEFAULT_CONF) conf.update({'automodapi_toctreedirnm': 'api', 'automodapi_writereprocessed': True, - 'automodsumm_writereprocessed': True}) + 'automodsumm_writereprocessed': True, + 'automodsumm_properties_are_attributes': prop_attr}) if os.path.basename(case_dir) in ('mixed_toplevel', 'mixed_toplevel_all_objects', @@ -112,8 +116,43 @@ def test_run_full_case(tmpdir, case_dir, parallel): path_relative = os.path.relpath(path_reference, output_dir) path_actual = os.path.join(docs_dir, path_relative) assert os.path.exists(path_actual) - with io.open(path_actual, encoding='utf8') as f: + with open(path_actual, encoding='utf8') as f: actual = f.read() - with io.open(path_reference, encoding='utf8') as f: + 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 + + 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 + + +def test_slots_example(): + """Basic tests for slots example module""" + from sphinx_automodapi.tests.example_module.slots import ( + SlotDict, DerivedParam, DerivedSlotParam + ) + SlotDict('param', 'other_param').my_method() + DerivedParam('param', 'other_param', 'extra_param').derived_from_slot_class_method() + DerivedSlotParam('param', 'other_param', 'extra_param').derived_from_slot_class_method() diff --git a/sphinx_automodapi/utils.py b/sphinx_automodapi/utils.py index 1716874..38e7be4 100644 --- a/sphinx_automodapi/utils.py +++ b/sphinx_automodapi/utils.py @@ -1,7 +1,7 @@ -import inspect import sys import re import os +from inspect import ismodule from warnings import warn from sphinx.ext.autosummary.generate import find_autosummary_in_docstring @@ -9,13 +9,6 @@ __all__ = ['cleanup_whitespace', 'find_mod_objs', 'find_autosummary_in_lines_for_automodsumm'] -if sys.version_info[0] >= 3: - def iteritems(dictionary): - return dictionary.items() -else: - def iteritems(dictionary): - return dictionary.iteritems() - # We use \n instead of os.linesep because even on Windows, the generated files # use \n as the newline character. SPACE_NEWLINE = ' \n' @@ -44,7 +37,7 @@ def cleanup_whitespace(text): return text -def find_mod_objs(modname, onlylocals=False): +def find_mod_objs(modname, onlylocals=False, sort=False): """ Returns all the public attributes of a module referenced by name. .. note:: @@ -57,9 +50,11 @@ def find_mod_objs(modname, onlylocals=False): modname : str The name of the module to search. onlylocals : bool or list - If True, only attributes that are either members of `modname` OR one of + If `True`, only attributes that are either members of `modname` OR one of its modules or subpackages will be included. If a list, only members of packages in the list are included. If `False`, selection is done. + This option is ignored if a module defines __all__ - in that case, __all__ + is used to determine whether objects are public. Returns ------- @@ -85,11 +80,14 @@ def find_mod_objs(modname, onlylocals=False): # define their own __getattr__ and __dir__. if hasattr(mod, '__all__'): pkgitems = [(k, getattr(mod, k)) for k in mod.__all__] + # Optionally sort the items alphabetically + if sort: + pkgitems.sort() + onlylocals = False else: - pkgitems = [(k, getattr(mod, k)) for k in dir(mod) if k[0] != '_'] + pkgitems = [(k, getattr(mod, k)) for k in dir(mod) if k[0] != "_"] # filter out modules and pull the names and objs out - ismodule = inspect.ismodule localnames = [k for k, v in pkgitems if not ismodule(v)] objs = [v for k, v in pkgitems if not ismodule(v)] @@ -115,7 +113,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), @@ -132,20 +130,23 @@ def find_autosummary_in_lines_for_automodsumm(lines, module=None, filename=None) """ autosummary_re = re.compile(r'^(\s*)\.\.\s+autosummary::\s*') automodule_re = re.compile( - r'^\s*\.\.\s+automodule::\s*([A-Za-z0-9_.]+)\s*$') + r'^\s*\.\.\s+automodule::\s*([A-Za-zäüöÄÜÖßő0-9_.]+)\s*$') module_re = re.compile( - r'^\s*\.\.\s+(current)?module::\s*([a-zA-Z0-9_.]+)\s*$') - autosummary_item_re = re.compile(r'^\s+(~?[_a-zA-Z][a-zA-Z0-9_.]*)\s*.*?') + r'^\s*\.\.\s+(current)?module::\s*([a-zA-ZäüöÄÜÖßő0-9_.]+)\s*$') + autosummary_item_re = re.compile(r'^\s+(~?[_a-zA-ZäüöÄÜÖßő][a-zA-ZäüöÄÜÖßő0-9_.]*)\s*.*?') toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$') 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*$') + other_options_re = re.compile(r'^\s+:nosignatures:\s*$') documented = [] toctree = None template = None inherited_members = None + noindex = None current_module = module in_autosummary = False base_indent = "" @@ -175,9 +176,16 @@ 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 + if other_options_re.match(line): + continue # skip known options + else: + warn(line) # warn about unknown options m = autosummary_item_re.match(line) if m: @@ -188,7 +196,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 + " "): diff --git a/tox.ini b/tox.ini index 7f51209..aa8bf3b 100644 --- a/tox.ini +++ b/tox.ini @@ -1,5 +1,5 @@ [tox] -envlist = py{37,38,39,310}-test-sphinx{24,35,40,41,42,43,dev}{,-cov}{-clocale,} +envlist = py{38,39,310,311,312,313}-test-sphinx{_oldest,53,62,70,71,72,80,81,dev}{-cov}{-clocale} requires = pip >= 18.0 setuptools >= 30.3.0 isolated_build = true @@ -7,21 +7,23 @@ isolated_build = true [testenv] changedir = .tmp/{envname} deps = - sphinx24: sphinx==2.4.* - sphinx35: sphinx==3.5.* - sphinx40: sphinx==4.0.* - sphinx41: sphinx==4.1.* - sphinx42: sphinx==4.2.* - sphinx43: sphinx==4.3.* + sphinx_oldest: sphinx==4.0.0 + sphinx53: sphinx==5.3.* + sphinx62: sphinx==6.2.* + sphinx70: sphinx==7.0.* + sphinx71: sphinx==7.1.* + sphinx72: sphinx==7.2.* + sphinx80: sphinx==8.0.* + sphinx81: sphinx==8.1.* sphinxdev: git+https://github.com/sphinx-doc/sphinx.git extras = test: test commands = pip freeze - !cov: pytest --pyargs sphinx_automodapi + !cov: pytest --pyargs sphinx_automodapi {posargs} cov: pytest --pyargs sphinx_automodapi --cov sphinx_automodapi --cov-config={toxinidir}/setup.cfg {posargs} cov: coverage xml -o {toxinidir}/coverage.xml -passenv = HOME WINDIR LC_ALL LC_CTYPE LANG CC CI +passenv = HOME, WINDIR, LC_ALL, LC_CTYPE, LANG, CC, CI setenv = cov: CFLAGS = --coverage -fno-inline-functions -O0 clocale: LC_CTYPE=C