├── .coveragerc ├── .github ├── dependabot.yml ├── release.yml └── workflows │ ├── check_milestone.yml │ ├── ci_workflows.yml │ └── publish.yml ├── .gitignore ├── .mailmap ├── .readthedocs.yml ├── CHANGES.rst ├── LICENSE.rst ├── MANIFEST.in ├── README.rst ├── docs ├── Makefile ├── automodapi.rst ├── automodsumm.rst ├── conf.py └── index.rst ├── pyproject.toml ├── setup.cfg ├── sphinx_automodapi ├── __init__.py ├── autodoc_enhancements.py ├── automodapi.py ├── automodsumm.py ├── smart_resolver.py ├── templates │ └── autosummary_core │ │ ├── base.rst │ │ ├── class.rst │ │ └── module.rst ├── tests │ ├── __init__.py │ ├── cases │ │ ├── abstract_classes │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ ├── output_prop_is_attr │ │ │ │ ├── api │ │ │ │ │ └── sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ │ └── output_prop_is_not_attr │ │ │ │ ├── api │ │ │ │ └── sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── allowed_names │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ ├── output_prop_is_attr │ │ │ │ ├── api │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.Egg.rst │ │ │ │ │ └── sphinx_automodapi.tests.example_module.Spam.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ │ └── output_prop_is_not_attr │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.Egg.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.Spam.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── attribute_class │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ ├── output_prop_is_attr │ │ │ │ ├── api │ │ │ │ │ └── sphinx_automodapi.tests.example_module.attribute_class.ClassWithAttribute.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ │ └── output_prop_is_not_attr │ │ │ │ ├── api │ │ │ │ └── sphinx_automodapi.tests.example_module.attribute_class.ClassWithAttribute.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── classes_no_inherit │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ ├── output_prop_is_attr │ │ │ │ ├── api │ │ │ │ │ └── sphinx_automodapi.tests.example_module.classes.Egg.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ │ └── output_prop_is_not_attr │ │ │ │ ├── api │ │ │ │ └── sphinx_automodapi.tests.example_module.classes.Egg.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── classes_with_inherit │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ ├── output_prop_is_attr │ │ │ │ ├── api │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.classes.Egg.rst │ │ │ │ │ └── sphinx_automodapi.tests.example_module.classes.Spam.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ │ └── output_prop_is_not_attr │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.classes.Egg.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.classes.Spam.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── func_headings │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ └── output │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.functions.add.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.functions.multiply.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── func_noheading │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ └── output │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.functions.add.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.functions.multiply.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── func_nomaindocstring │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ └── output │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.functions.add.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.functions.multiply.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── func_simple │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ └── output │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.functions.add.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.functions.multiply.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── inherited_members │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ ├── output_prop_is_attr │ │ │ │ ├── api │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.classes.Egg.rst │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.classes.Spam.rst │ │ │ │ │ └── sphinx_automodapi.tests.example_module.other_classes.Foo.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ │ └── output_prop_is_not_attr │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.classes.Egg.rst │ │ │ │ ├── sphinx_automodapi.tests.example_module.classes.Spam.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.other_classes.Foo.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── mixed_toplevel │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ ├── output_prop_is_attr │ │ │ │ ├── api │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.Egg.rst │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.Spam.rst │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.add.rst │ │ │ │ │ └── sphinx_automodapi.tests.example_module.multiply.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ │ └── output_prop_is_not_attr │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.Egg.rst │ │ │ │ ├── sphinx_automodapi.tests.example_module.Spam.rst │ │ │ │ ├── sphinx_automodapi.tests.example_module.add.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.multiply.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── mixed_toplevel_all_objects │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ ├── output_prop_is_attr │ │ │ │ ├── api │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.Egg.rst │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.FUNNY_WALK_STEPS.rst │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.PARROT_STATE.rst │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.Spam.rst │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.add.rst │ │ │ │ │ └── sphinx_automodapi.tests.example_module.multiply.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ │ └── output_prop_is_not_attr │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.Egg.rst │ │ │ │ ├── sphinx_automodapi.tests.example_module.FUNNY_WALK_STEPS.rst │ │ │ │ ├── sphinx_automodapi.tests.example_module.PARROT_STATE.rst │ │ │ │ ├── sphinx_automodapi.tests.example_module.Spam.rst │ │ │ │ ├── sphinx_automodapi.tests.example_module.add.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.multiply.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── mixed_toplevel_nodiagram │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ ├── output_prop_is_attr │ │ │ │ ├── api │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.Egg.rst │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.Spam.rst │ │ │ │ │ ├── sphinx_automodapi.tests.example_module.add.rst │ │ │ │ │ └── sphinx_automodapi.tests.example_module.multiply.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ │ └── output_prop_is_not_attr │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.Egg.rst │ │ │ │ ├── sphinx_automodapi.tests.example_module.Spam.rst │ │ │ │ ├── sphinx_automodapi.tests.example_module.add.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.multiply.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── nested │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ ├── index.rst │ │ │ │ └── tests │ │ │ │ │ └── example_module │ │ │ │ │ ├── index.rst │ │ │ │ │ └── references.txt │ │ │ └── output │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.functions_with_ref.add.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.functions_with_ref.multiply.rst │ │ │ │ └── tests │ │ │ │ └── example_module │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── non_ascii │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ └── output │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.functions.add.rst │ │ │ │ ├── sphinx_automodapi.tests.example_module.functions.multiply.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.nonascii.NonAsciiÄöüßő.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── public_from_private │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ └── output │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.public.Camelot.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.public.Spam.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── slots │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── index.rst │ │ │ └── output │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.slots.DerivedParam.rst │ │ │ │ ├── sphinx_automodapi.tests.example_module.slots.DerivedSlotParam.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.slots.SlotDict.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ ├── source_dir │ │ │ ├── README.md │ │ │ ├── input │ │ │ │ └── src │ │ │ │ │ └── index.rst │ │ │ └── output │ │ │ │ └── src │ │ │ │ ├── api │ │ │ │ ├── sphinx_automodapi.tests.example_module.functions.add.rst │ │ │ │ └── sphinx_automodapi.tests.example_module.functions.multiply.rst │ │ │ │ ├── index.rst.automodapi │ │ │ │ └── index.rst.automodsumm │ │ └── variables │ │ │ ├── README.md │ │ │ ├── input │ │ │ └── index.rst │ │ │ └── output │ │ │ ├── api │ │ │ ├── sphinx_automodapi.tests.example_module.variables.FUNNY_WALK_STEPS.rst │ │ │ └── sphinx_automodapi.tests.example_module.variables.PARROT_STATE.rst │ │ │ ├── index.rst.automodapi │ │ │ └── index.rst.automodsumm │ ├── duplicated_warning │ │ ├── __init__.py │ │ ├── docs │ │ │ ├── conf.py │ │ │ ├── foo.rst │ │ │ └── index.rst │ │ └── duplicated │ │ │ ├── __init__.py │ │ │ └── foo │ │ │ ├── __init__.py │ │ │ └── foo.py │ ├── example_module │ │ ├── __init__.py │ │ ├── _private.py │ │ ├── abstract_classes.py │ │ ├── attribute_class.py │ │ ├── classes.py │ │ ├── functions.py │ │ ├── functions_with_ref.py │ │ ├── mixed.py │ │ ├── noall.py │ │ ├── nonascii.py │ │ ├── other_classes.py │ │ ├── public.py │ │ ├── slots.py │ │ ├── stdlib.py │ │ └── variables.py │ ├── helpers.py │ ├── test_autodoc_enhancements.py │ ├── test_automodapi.py │ ├── test_automodsumm.py │ ├── test_cases.py │ └── test_utils.py └── utils.py └── tox.ini /.coveragerc: -------------------------------------------------------------------------------- 1 | [run] 2 | source = sphinx_automodapi 3 | omit = 4 | sphinx_automodapi/tests/* 5 | */sphinx_automodapi/tests/* 6 | 7 | [report] 8 | exclude_lines = 9 | # Have to re-enable the standard pragma 10 | pragma: no cover 11 | # Don't complain about packages we have installed 12 | except ImportError 13 | # Don't complain if tests don't hit assertions 14 | raise AssertionError 15 | raise NotImplementedError 16 | # Don't complain about script hooks 17 | def main\(.*\): 18 | # Ignore branches that don't pertain to this version of Python 19 | pragma: py{ignore_python_version} 20 | # Don't complain about IPython completion helper 21 | def _ipython_key_completions_ 22 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | # To get started with Dependabot version updates, you'll need to specify which 2 | # package ecosystems to update and where the package manifests are located. 3 | # Please see the documentation for all configuration options: 4 | # https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates 5 | 6 | version: 2 7 | updates: 8 | - package-ecosystem: "github-actions" 9 | directory: "/" 10 | schedule: 11 | interval: "monthly" 12 | groups: 13 | actions: 14 | patterns: 15 | - "*" 16 | labels: 17 | - "no-changelog-entry-needed" 18 | -------------------------------------------------------------------------------- /.github/release.yml: -------------------------------------------------------------------------------- 1 | changelog: 2 | exclude: 3 | authors: 4 | - dependabot 5 | - pre-commit-ci 6 | -------------------------------------------------------------------------------- /.github/workflows/check_milestone.yml: -------------------------------------------------------------------------------- 1 | name: Check PR milestone 2 | 3 | on: 4 | # So it cannot be skipped. 5 | pull_request_target: 6 | types: [opened, synchronize, milestoned, demilestoned] 7 | 8 | concurrency: 9 | group: ${{ github.workflow }}-${{ github.ref }} 10 | cancel-in-progress: true 11 | 12 | permissions: 13 | contents: read 14 | 15 | jobs: 16 | # https://stackoverflow.com/questions/69434370/how-can-i-get-the-latest-pr-data-specifically-milestones-when-running-yaml-jobs 17 | milestone_checker: 18 | runs-on: ubuntu-latest 19 | steps: 20 | - uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1 21 | if: github.repository == 'astropy/sphinx-automodapi' 22 | with: 23 | github-token: ${{ secrets.GITHUB_TOKEN }} 24 | script: | 25 | const { data } = await github.request("GET /repos/{owner}/{repo}/pulls/{pr}", { 26 | owner: context.repo.owner, 27 | repo: context.repo.repo, 28 | pr: context.payload.pull_request.number 29 | }); 30 | if (data.milestone) { 31 | core.info(`This pull request has a milestone set: ${data.milestone.title}`); 32 | } else { 33 | core.setFailed(`A maintainer needs to set the milestone for this pull request.`); 34 | } 35 | -------------------------------------------------------------------------------- /.github/workflows/ci_workflows.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | pull_request: 5 | push: 6 | branches: [ main ] 7 | tags: '*' 8 | workflow_dispatch: 9 | schedule: 10 | # Weekly cron 11 | - cron: '0 8 * * 1' 12 | 13 | concurrency: 14 | group: ${{ github.workflow }}-${{ github.ref }} 15 | cancel-in-progress: true 16 | 17 | jobs: 18 | tests: 19 | runs-on: ${{ matrix.os }} 20 | strategy: 21 | fail-fast: false 22 | matrix: 23 | include: 24 | - name: Code style checks 25 | os: ubuntu-latest 26 | python-version: 3.x 27 | toxenv: codestyle 28 | 29 | # Linux - test different Sphinx versions 30 | - os: ubuntu-latest 31 | python-version: 3.8 32 | toxenv: py38-test-sphinx_oldest 33 | - os: ubuntu-latest 34 | python-version: 3.8 35 | toxenv: py38-test-sphinx53 36 | - os: ubuntu-latest 37 | python-version: 3.9 38 | toxenv: py39-test-sphinx62 39 | - os: ubuntu-latest 40 | python-version: 3.9 41 | toxenv: py39-test-sphinx70 42 | - os: ubuntu-latest 43 | python-version: '3.10' 44 | toxenv: py310-test-sphinx71 45 | - os: ubuntu-latest 46 | python-version: '3.11' 47 | toxenv: py311-test-sphinx72-cov-clocale 48 | - os: ubuntu-latest 49 | python-version: '3.12' 50 | toxenv: py312-test-sphinx80 51 | - os: ubuntu-latest 52 | python-version: '3.12' 53 | toxenv: py312-test-sphinx81 54 | - os: ubuntu-latest 55 | python-version: '3.13' 56 | toxenv: py313-test-sphinxdev 57 | 58 | # MacOS X - just the stable and dev 59 | - os: macos-latest 60 | python-version: '3.11' 61 | toxenv: py311-test-sphinx81-clocale 62 | - os: macos-latest 63 | python-version: '3.13' 64 | toxenv: py313-test-sphinxdev 65 | 66 | # Windows - just the oldest, stable, and dev 67 | - os: windows-latest 68 | python-version: 3.8 69 | toxenv: py38-test-sphinx_oldest 70 | - os: windows-latest 71 | python-version: '3.10' 72 | toxenv: py310-test-sphinx81 73 | - os: windows-latest 74 | python-version: '3.13' 75 | toxenv: py313-test-sphinxdev 76 | 77 | steps: 78 | - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 79 | with: 80 | fetch-depth: 0 81 | - name: Set up Python ${{ matrix.python-version }} 82 | uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 83 | with: 84 | python-version: ${{ matrix.python-version }} 85 | allow-prereleases: true 86 | - name: Install graphviz on Linux 87 | if: startsWith(matrix.os, 'ubuntu') 88 | run: | 89 | sudo apt-get update 90 | sudo apt-get install graphviz 91 | - name: Install graphviz on OSX 92 | if: startsWith(matrix.os, 'macos') 93 | run: | 94 | brew update 95 | brew install graphviz 96 | - name: Install graphviz on Windows 97 | if: startsWith(matrix.os, 'windows') 98 | run: choco install graphviz 99 | - name: Install tox 100 | run: python -m pip install tox 101 | - name: Run tox 102 | run: tox ${{ matrix.toxargs }} -v -e ${{ matrix.toxenv }} 103 | - name: Upload coverage to codecov 104 | if: ${{ contains(matrix.toxenv,'-cov') }} 105 | uses: codecov/codecov-action@18283e04ce6e62d37312384ff67231eb8fd56d24 # v5.4.3 106 | with: 107 | file: ./coverage.xml 108 | -------------------------------------------------------------------------------- /.github/workflows/publish.yml: -------------------------------------------------------------------------------- 1 | name: Release 2 | 3 | on: 4 | pull_request: 5 | push: 6 | tags: 7 | - '*' 8 | 9 | jobs: 10 | build-n-publish: 11 | name: Build and publish Python 🐍 distributions 📦 to PyPI 12 | runs-on: ubuntu-latest 13 | if: ((github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) || contains(github.event.pull_request.labels.*.name, 'Build wheels')) 14 | 15 | steps: 16 | - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 17 | with: 18 | fetch-depth: 0 19 | - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 20 | with: 21 | python-version: "3.12" 22 | 23 | - name: Install dependencies 24 | run: | 25 | sudo apt-get update 26 | sudo apt-get install graphviz 27 | python -m pip install pip build "twine>=3.3" -U 28 | 29 | - name: Build package 30 | run: python -m build --sdist --wheel . 31 | 32 | - name: List result 33 | run: ls -l dist 34 | 35 | - name: Check dist 36 | run: python -m twine check --strict dist/* 37 | 38 | - name: Test package 39 | run: | 40 | cd .. 41 | python -m venv testenv 42 | testenv/bin/pip install pip -U 43 | testenv/bin/pip install $(ls sphinx-automodapi/dist/*.whl)[test] 44 | testenv/bin/pytest sphinx-automodapi/sphinx_automodapi/tests 45 | 46 | - name: Publish distribution 📦 to PyPI 47 | if: startsWith(github.ref, 'refs/tags') 48 | uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4 49 | with: 50 | user: __token__ 51 | password: ${{ secrets.pypi_password }} 52 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Compiled files 2 | *.py[cod] 3 | *.a 4 | *.o 5 | *.so 6 | *.pyd 7 | __pycache__ 8 | 9 | # Ignore .c files by default to avoid including generated code. If you want to 10 | # add a non-generated .c extension, use `git add -f filename.c`. 11 | *.c 12 | 13 | # Other generated files 14 | MANIFEST 15 | sphinx_automodapi/version.py 16 | 17 | # Sphinx 18 | _build 19 | _generated 20 | 21 | 22 | # Packages/installer info 23 | *.egg 24 | *.egg-info 25 | dist 26 | build 27 | eggs 28 | parts 29 | bin 30 | var 31 | sdist 32 | develop-eggs 33 | .installed.cfg 34 | distribute-*.tar.gz 35 | 36 | # Other 37 | .cache 38 | .tox 39 | .*.swp 40 | *~ 41 | .project 42 | .pydevproject 43 | .settings 44 | .coverage 45 | cover 46 | htmlcov 47 | 48 | # Mac OSX 49 | .DS_Store 50 | 51 | # PyCharm 52 | .idea 53 | -------------------------------------------------------------------------------- /.mailmap: -------------------------------------------------------------------------------- 1 | Brigitta Sipőcz 2 | Brigitta Sipőcz 3 | David Pérez-Suárez 4 | E. Madison Bray 5 | E. Madison Bray 6 | Kyle D Fawcett <45832007+kylefawcett@users.noreply.github.com> 7 | Hans Moritz Günther 8 | Marco Rossi 9 | Matt Davis 10 | P. L. Lim <2090236+pllim@users.noreply.github.com> 11 | Simon Conseil 12 | Stuart Mumford -------------------------------------------------------------------------------- /.readthedocs.yml: -------------------------------------------------------------------------------- 1 | # .readthedocs.yml 2 | # Read the Docs configuration file 3 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 4 | 5 | version: 2 6 | 7 | build: 8 | os: ubuntu-22.04 9 | tools: 10 | python: "3.12" 11 | jobs: 12 | post_checkout: 13 | - git fetch --shallow-since=2023-01-01 || true 14 | 15 | sphinx: 16 | builder: html 17 | configuration: docs/conf.py 18 | fail_on_warning: true 19 | 20 | python: 21 | install: 22 | - method: pip 23 | path: . 24 | extra_requirements: 25 | - rtd 26 | 27 | # Don't build any extra formats 28 | formats: [] 29 | -------------------------------------------------------------------------------- /CHANGES.rst: -------------------------------------------------------------------------------- 1 | Changes in sphinx-automodapi 2 | ============================ 3 | 4 | 0.20.0 (unreleased) 5 | ------------------- 6 | 7 | - No changes yet 8 | 9 | 0.19.0 (2025-04-17) 10 | ------------------- 11 | 12 | - Add ``automodsumm_properties_are_attributes`` configuration to control if 13 | class properties are treated with ``autoattribute`` or ``autoproperty``. 14 | [#197] 15 | 16 | - Fixes compatibility with Sphinx 8.2. [#196] 17 | 18 | 0.18.0 (2024-09-13) 19 | ------------------- 20 | 21 | - Fixed an issue where items defined in ``__all__`` but originally imported 22 | from elsewhere, e.g. a private module, were not documented. [#190] 23 | 24 | 0.17.0 (2024-02-22) 25 | ------------------- 26 | 27 | - Fixes issue where ``__slots__`` hides class variables. [#181] 28 | 29 | - Minimum supported Python version is now 3.8. [#177] 30 | 31 | - Fixed issue with non-ascii characters in object names. [#184] 32 | 33 | 0.16.0 (2023-08-17) 34 | ------------------- 35 | 36 | - Fixed broken inheritance-diagram links due to the smart resolver. [#172] 37 | 38 | - Compatibility with Sphinx 7.2. [#172] 39 | 40 | - Minimum supported Sphinx version is now 4. [#170] 41 | 42 | 0.15.0 (2023-03-13) 43 | ------------------- 44 | 45 | - Silenced spurious warnings on configuring ``:nosignatures:``. [#158] 46 | 47 | - Fixed issue with non-ascii characters in object members when the encoding is 48 | not ``utf8``. [#153] 49 | 50 | - Allow use of ``:noindex:``, propagating this flag to autodoc. [#150] 51 | 52 | 0.14.1 (2022-01-12) 53 | ------------------- 54 | 55 | - Fixed issue with ``:skip:`` introduced by ``:include:`` feature. [#142] 56 | 57 | 0.14.0 (2021-12-22) 58 | ------------------- 59 | 60 | - Set default value for ``env.intersphinx_named_inventory``. [#136] 61 | 62 | - Sphinx 4 compatibility w.r.t. logger warning. [#129] 63 | 64 | - Add ``:include:`` option to do the opposite of ``:skip:``. [#127] 65 | 66 | - Various infrastructure/packaging updates and code clean-ups. 67 | Minimum supported Python version is now 3.7 and Sphinx 2. 68 | [#120, #124, #126, #133, #139] 69 | 70 | 0.13 (2020-09-24) 71 | ----------------- 72 | 73 | - Fixed implementation of ``allowed-package-names`` option (which did 74 | not work at all). [#111] 75 | 76 | - Ensure that generated files are always in .rst. [#112] 77 | 78 | - Update minimum required Python version to 3.6. [#117] 79 | 80 | - Fixed compatibility with Sphinx 3.0 and later. [#100] 81 | 82 | 0.12 (2019-08-15) 83 | ----------------- 84 | 85 | - Fixed compatibility with Sphinx 2.0 and later. [#86] 86 | 87 | - Updated required version of Sphinx to 1.7 and later. [#88] 88 | 89 | 0.11 (2019-05-29) 90 | ----------------- 91 | 92 | - Added a global configuration option ``automodapi_inheritance_diagram`` to 93 | control whether inheritance diagrams are shown by default. [#75] 94 | 95 | - Fix bug with smart_resolver when intersphinx inventory doesn't include 96 | any py:class entries. [#76] 97 | 98 | - Fixed compatibility with Sphinx 2.0 and later. [#79] 99 | 100 | 0.10 (2019-01-09) 101 | ----------------- 102 | 103 | - Fixed compatibility with latest developer version of Sphinx. [#61] 104 | 105 | 0.9 (2018-11-07) 106 | ---------------- 107 | 108 | - Fix issue with ABC-derived classes (``abc`` and ``collections.abc`` modules) 109 | having their members ignored in Python 3. This was only an issue when 110 | ``:inherited-members:`` was not in effect. [#53] 111 | 112 | 0.8 (2018-10-18) 113 | ---------------- 114 | 115 | - Fixed compatibility with Sphinx 1.8.x. [#51] 116 | 117 | - Make all extensions parallel-friendly. [#44] 118 | 119 | 0.7 (2018-01-18) 120 | ---------------- 121 | 122 | - Fix compatibility with Sphinx 1.7.x. [#43] 123 | 124 | 0.6 (2017-07-05) 125 | ---------------- 126 | 127 | - Fix encoding issues on platforms that default to e.g. ASCII encoding. [#33] 128 | 129 | 0.5 (2017-05-29) 130 | ---------------- 131 | 132 | - Fix a bug that caused the :inherited-members: option to apply to all subsequent 133 | automodapi directives. [#25] 134 | 135 | 0.4 (2017-05-24) 136 | ---------------- 137 | 138 | - Fix compatibility with Sphinx 1.6 and 1.7. [#22, #23] 139 | 140 | - Introduce a new ``:include-all-objects:`` option to ``automodapi`` that will 141 | include not just functions and classes in a module, but also all other 142 | objects. To help this, introduce a new ``:variables-only:`` option for 143 | ``automodsumm``. [#24] 144 | 145 | 0.3 (2017-02-20) 146 | ---------------- 147 | 148 | - Fixed installation on Python 3.4. [#21] 149 | 150 | 0.2 (2016-12-28) 151 | ---------------- 152 | 153 | - Suppress warning about re-defining autoattribute in recent versions of 154 | Sphinx. [#8] 155 | 156 | - Avoid hard-coding sphinx_automodapi module name in case this extension is 157 | bundled into another package. [#12] 158 | 159 | - Fix use of automodapi when source files are inside a source directory. [#16] 160 | 161 | - Make sure generated rst is tidy and doesn't include extraneous whitespace. [#18] 162 | 163 | 0.1 (2016-12-12) 164 | ---------------- 165 | 166 | - Fixed a bug that caused the automodapi directive to not work properly when 167 | the main module docstring was not included. [#3] 168 | 169 | - Fixed a bug that caused skipped classes in automodapi directives to still 170 | be included in inheritance diagrams. [#3] 171 | 172 | - Original code taken out of astropy-helpers 173 | -------------------------------------------------------------------------------- /LICENSE.rst: -------------------------------------------------------------------------------- 1 | Copyright (c) 2014-2025, Astropy Developers 2 | 3 | All rights reserved. 4 | 5 | Redistribution and use in source and binary forms, with or without modification, 6 | are permitted provided that the following conditions are met: 7 | 8 | * Redistributions of source code must retain the above copyright notice, this 9 | list of conditions and the following disclaimer. 10 | * Redistributions in binary form must reproduce the above copyright notice, this 11 | list of conditions and the following disclaimer in the documentation and/or 12 | other materials provided with the distribution. 13 | * Neither the name of the Astropy Team nor the names of its contributors may be 14 | used to endorse or promote products derived from this software without 15 | specific prior written permission. 16 | 17 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 18 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 19 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 20 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 21 | ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 22 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 23 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 24 | ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 26 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 | -------------------------------------------------------------------------------- /MANIFEST.in: -------------------------------------------------------------------------------- 1 | include README.rst 2 | include CHANGES.rst 3 | include LICENSE.rst 4 | 5 | include setup.cfg 6 | include pyproject.toml 7 | 8 | exclude *.pyc *.o 9 | prune build 10 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | |DOI| |PyPI| |Docs| |CI Status| |Coverage Status| 2 | 3 | About 4 | ===== 5 | 6 | This is a Sphinx extension to automatically generate API pages for whole 7 | modules. It was originally developed for the Astropy project but is now 8 | available as a standalone package since it can be used for any other 9 | package. The documentation can be found on 10 | `ReadTheDocs `_. 11 | 12 | Running tests 13 | ------------- 14 | 15 | To run the tests, you can either do:: 16 | 17 | pytest sphinx_automodapi 18 | 19 | or if you have `tox `_ installed:: 20 | 21 | tox -e test 22 | 23 | .. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.5799977.svg 24 | :target: https://doi.org/10.5281/zenodo.5799977 25 | .. |PyPI| image:: https://img.shields.io/pypi/v/sphinx-automodapi.svg 26 | :target: https://pypi.python.org/pypi/sphinx-automodapi 27 | .. |Docs| image:: https://readthedocs.org/projects/sphinx-automodapi/badge/?version=latest 28 | :target: https://sphinx-automodapi.readthedocs.io/en/latest/?badge=latest 29 | .. |CI Status| image:: https://github.com/astropy/sphinx-automodapi/workflows/CI/badge.svg 30 | :target: https://github.com/astropy/sphinx-automodapi/actions 31 | .. |Coverage Status| image:: https://codecov.io/gh/astropy/sphinx-automodapi/branch/main/graph/badge.svg 32 | :target: https://codecov.io/gh/astropy/sphinx-automodapi 33 | 34 | Development status 35 | ------------------ 36 | 37 | Due to the limitations of FOSS development model, the Astropy Project 38 | does not have enough bandwidth to add new features or fixes to this 39 | package beyond what is necessary for the project itself. Therefore, 40 | we apologize for any inconvenience caused by unresolved open issues 41 | and unmerged stale pull requests. If you have any questions or concerns, 42 | please contact the project via https://www.astropy.org/help . 43 | Thank you for your interest in this package! 44 | -------------------------------------------------------------------------------- /docs/Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | PAPER = 8 | BUILDDIR = _build 9 | 10 | # Internal variables. 11 | PAPEROPT_a4 = -D latex_paper_size=a4 12 | PAPEROPT_letter = -D latex_paper_size=letter 13 | ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 14 | # the i18n builder cannot share the environment and doctrees with the others 15 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 16 | 17 | .PHONY: help 18 | help: 19 | @echo "Please use \`make ' where is one of" 20 | @echo " html to make standalone HTML files" 21 | @echo " dirhtml to make HTML files named index.html in directories" 22 | @echo " singlehtml to make a single large HTML file" 23 | @echo " pickle to make pickle files" 24 | @echo " json to make JSON files" 25 | @echo " htmlhelp to make HTML files and a HTML help project" 26 | @echo " qthelp to make HTML files and a qthelp project" 27 | @echo " applehelp to make an Apple Help Book" 28 | @echo " devhelp to make HTML files and a Devhelp project" 29 | @echo " epub to make an epub" 30 | @echo " epub3 to make an epub3" 31 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 32 | @echo " latexpdf to make LaTeX files and run them through pdflatex" 33 | @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" 34 | @echo " text to make text files" 35 | @echo " man to make manual pages" 36 | @echo " texinfo to make Texinfo files" 37 | @echo " info to make Texinfo files and run them through makeinfo" 38 | @echo " gettext to make PO message catalogs" 39 | @echo " changes to make an overview of all changed/added/deprecated items" 40 | @echo " xml to make Docutils-native XML files" 41 | @echo " pseudoxml to make pseudoxml-XML files for display purposes" 42 | @echo " linkcheck to check all external links for integrity" 43 | @echo " doctest to run all doctests embedded in the documentation (if enabled)" 44 | @echo " coverage to run coverage check of the documentation (if enabled)" 45 | @echo " dummy to check syntax errors of document sources" 46 | 47 | .PHONY: clean 48 | clean: 49 | rm -rf $(BUILDDIR)/* 50 | 51 | .PHONY: html 52 | html: 53 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 54 | @echo 55 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 56 | 57 | .PHONY: dirhtml 58 | dirhtml: 59 | $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 60 | @echo 61 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 62 | 63 | .PHONY: singlehtml 64 | singlehtml: 65 | $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 66 | @echo 67 | @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 68 | 69 | .PHONY: pickle 70 | pickle: 71 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 72 | @echo 73 | @echo "Build finished; now you can process the pickle files." 74 | 75 | .PHONY: json 76 | json: 77 | $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 78 | @echo 79 | @echo "Build finished; now you can process the JSON files." 80 | 81 | .PHONY: htmlhelp 82 | htmlhelp: 83 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 84 | @echo 85 | @echo "Build finished; now you can run HTML Help Workshop with the" \ 86 | ".hhp project file in $(BUILDDIR)/htmlhelp." 87 | 88 | .PHONY: qthelp 89 | qthelp: 90 | $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 91 | @echo 92 | @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 93 | ".qhcp project file in $(BUILDDIR)/qthelp, like this:" 94 | @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/sphinx-automodapi.qhcp" 95 | @echo "To view the help file:" 96 | @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/sphinx-automodapi.qhc" 97 | 98 | .PHONY: applehelp 99 | applehelp: 100 | $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp 101 | @echo 102 | @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." 103 | @echo "N.B. You won't be able to view it unless you put it in" \ 104 | "~/Library/Documentation/Help or install it in your application" \ 105 | "bundle." 106 | 107 | .PHONY: devhelp 108 | devhelp: 109 | $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 110 | @echo 111 | @echo "Build finished." 112 | @echo "To view the help file:" 113 | @echo "# mkdir -p $$HOME/.local/share/devhelp/sphinx-automodapi" 114 | @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/sphinx-automodapi" 115 | @echo "# devhelp" 116 | 117 | .PHONY: epub 118 | epub: 119 | $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 120 | @echo 121 | @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 122 | 123 | .PHONY: epub3 124 | epub3: 125 | $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 126 | @echo 127 | @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." 128 | 129 | .PHONY: latex 130 | latex: 131 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 132 | @echo 133 | @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 134 | @echo "Run \`make' in that directory to run these through (pdf)latex" \ 135 | "(use \`make latexpdf' here to do that automatically)." 136 | 137 | .PHONY: latexpdf 138 | latexpdf: 139 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 140 | @echo "Running LaTeX files through pdflatex..." 141 | $(MAKE) -C $(BUILDDIR)/latex all-pdf 142 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 143 | 144 | .PHONY: latexpdfja 145 | latexpdfja: 146 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 147 | @echo "Running LaTeX files through platex and dvipdfmx..." 148 | $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja 149 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 150 | 151 | .PHONY: text 152 | text: 153 | $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 154 | @echo 155 | @echo "Build finished. The text files are in $(BUILDDIR)/text." 156 | 157 | .PHONY: man 158 | man: 159 | $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 160 | @echo 161 | @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 162 | 163 | .PHONY: texinfo 164 | texinfo: 165 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 166 | @echo 167 | @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." 168 | @echo "Run \`make' in that directory to run these through makeinfo" \ 169 | "(use \`make info' here to do that automatically)." 170 | 171 | .PHONY: info 172 | info: 173 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 174 | @echo "Running Texinfo files through makeinfo..." 175 | make -C $(BUILDDIR)/texinfo info 176 | @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." 177 | 178 | .PHONY: gettext 179 | gettext: 180 | $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale 181 | @echo 182 | @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." 183 | 184 | .PHONY: changes 185 | changes: 186 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 187 | @echo 188 | @echo "The overview file is in $(BUILDDIR)/changes." 189 | 190 | .PHONY: linkcheck 191 | linkcheck: 192 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 193 | @echo 194 | @echo "Link check complete; look for any errors in the above output " \ 195 | "or in $(BUILDDIR)/linkcheck/output.txt." 196 | 197 | .PHONY: doctest 198 | doctest: 199 | $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 200 | @echo "Testing of doctests in the sources finished, look at the " \ 201 | "results in $(BUILDDIR)/doctest/output.txt." 202 | 203 | .PHONY: coverage 204 | coverage: 205 | $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage 206 | @echo "Testing of coverage in the sources finished, look at the " \ 207 | "results in $(BUILDDIR)/coverage/python.txt." 208 | 209 | .PHONY: xml 210 | xml: 211 | $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml 212 | @echo 213 | @echo "Build finished. The XML files are in $(BUILDDIR)/xml." 214 | 215 | .PHONY: pseudoxml 216 | pseudoxml: 217 | $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml 218 | @echo 219 | @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." 220 | 221 | .PHONY: dummy 222 | dummy: 223 | $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy 224 | @echo 225 | @echo "Build finished. Dummy builder generates no files." 226 | -------------------------------------------------------------------------------- /docs/automodapi.rst: -------------------------------------------------------------------------------- 1 | Automatically generating module documentation with automodapi 2 | ============================================================= 3 | 4 | .. _automodapi: 5 | 6 | Overview 7 | -------- 8 | 9 | The main Sphinx directive provided by the sphinx-automodapi package is the 10 | ``automodapi`` directive. As described in the :ref:`quickstart` guide, 11 | before you use the directive, you will need to make sure the following 12 | extension is included in the ``extensions`` entry of your documentation's 13 | ``conf.py`` file:: 14 | 15 | extensions = ['sphinx_automodapi.automodapi'] 16 | 17 | You can then add an ``automodapi`` block anywhere that you want to generate 18 | documentation for a module:: 19 | 20 | .. automodapi:: mypackage.mymodule 21 | 22 | 23 | This will add a section with the docstring of the module, followed by a list of 24 | functions, and by a list of classes. For each function and class, a full API 25 | page will be generated. 26 | 27 | The automodapi directive and allowed options are described in more detail below. 28 | 29 | In detail 30 | --------- 31 | 32 | .. automodule:: sphinx_automodapi.automodapi 33 | -------------------------------------------------------------------------------- /docs/automodsumm.rst: -------------------------------------------------------------------------------- 1 | Generating tables of module objects with automodsumm 2 | ==================================================== 3 | 4 | .. _automodsumm: 5 | 6 | Overview 7 | -------- 8 | 9 | The ``automodsumm`` directive takes all objects in a 10 | module and generates a table of these objects and associated API pages. The 11 | :ref:`automodapi ` directive then calls ``automodsumm`` once for 12 | functions and once for classes, and adds the module docstring - but effectively, 13 | the bulk of the work in creating the API tables and pages is done by 14 | ``automodsumm``. 15 | 16 | Nevertheless, in most cases, users should not need to call ``automodsumm`` 17 | directly, except if finer control is desired. The syntax of the directive is:: 18 | 19 | .. automodsumm:: mypackage.mymodule 20 | 21 | 22 | The automodsumm directive is described in more detail below. 23 | 24 | In detail 25 | --------- 26 | 27 | .. automodule:: sphinx_automodapi.automodsumm 28 | -------------------------------------------------------------------------------- /docs/conf.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | # -*- coding: utf-8 -*- 3 | # 4 | # -- General configuration ------------------------------------------------ 5 | from sphinx_automodapi import __version__ 6 | 7 | # Add any Sphinx extension module names here, as strings. They can be 8 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 9 | # ones. 10 | extensions = ['sphinx.ext.autosummary'] 11 | 12 | # Add any paths that contain templates here, relative to this directory. 13 | templates_path = ['_templates'] 14 | 15 | # The suffix(es) of source filenames. 16 | # You can specify multiple suffix as a list of string: 17 | source_suffix = '.rst' 18 | 19 | # The main toctree document. 20 | master_doc = 'index' 21 | 22 | # General information about the project. 23 | project = 'sphinx-automodapi' 24 | copyright = '2016, The Astropy Developers' 25 | author = 'The Astropy Developers' 26 | 27 | # The version info for the project you're documenting, acts as replacement for 28 | # |version| and |release|, also used in various other places throughout the 29 | # built documents. 30 | # 31 | # The full version, including alpha/beta/rc tags. 32 | release = __version__ 33 | # The short X.Y version. 34 | version = '.'.join(release.split('.')[:2]) 35 | 36 | # The language for content autogenerated by Sphinx. Refer to documentation 37 | # for a list of supported languages. 38 | # 39 | # This is also used if you do content translation via gettext catalogs. 40 | # Usually you set "language" from the command line for these cases. 41 | language = 'en' 42 | 43 | # List of patterns, relative to source directory, that match files and 44 | # directories to ignore when looking for source files. 45 | # This patterns also effect to html_static_path and html_extra_path 46 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 47 | 48 | # The name of the Pygments (syntax highlighting) style to use. 49 | pygments_style = 'sphinx' 50 | 51 | # -- Options for HTML output ---------------------------------------------- 52 | 53 | # The theme to use for HTML and HTML Help pages. See the documentation for 54 | # a list of builtin themes. 55 | html_theme = 'sphinx_rtd_theme' 56 | 57 | # Output file base name for HTML help builder. 58 | htmlhelp_basename = 'sphinx-automodapidoc' 59 | 60 | nitpicky = True 61 | -------------------------------------------------------------------------------- /docs/index.rst: -------------------------------------------------------------------------------- 1 | Documentation for sphinx-automodapi 2 | =================================== 3 | 4 | The sphinx-automodapi package provides Sphinx directives that help faciliate 5 | the automatic generation of API documentation pages for Python package modules. 6 | It was originally developped for the Astropy project, but is now developed as a 7 | standalone package that can be used for any project. 8 | 9 | Installation 10 | ------------ 11 | 12 | This extension requires Sphinx 1.7 or later, and can be installed with:: 13 | 14 | pip install sphinx-automodapi 15 | 16 | The extension is also available through conda package management system. It can be installed with:: 17 | 18 | conda install -c conda-forge sphinx-automodapi 19 | 20 | 21 | 22 | .. _quickstart: 23 | 24 | Quick start 25 | ----------- 26 | 27 | To use this extension, you will need to add the following entry to the 28 | ``extensions`` list in your Sphinx ``conf.py`` file:: 29 | 30 | extensions = ['sphinx_automodapi.automodapi'] 31 | numpydoc_show_class_members = False 32 | 33 | You can then add an ``automodapi`` block anywhere that you want to generate 34 | documentation for a module:: 35 | 36 | .. automodapi:: mypackage.mymodule 37 | 38 | This will add a section with the docstring of the module, followed by a list of 39 | functions, and by a list of classes. For each function and class, a full API 40 | page will be generated. The ``numpydoc_show_class_members=False`` option is needed 41 | to avoid having methods and attributes of classes being shown multiple times. 42 | 43 | By default, sphinx_automodapi will try and make a diagram showing an 44 | inheritance graph of all the classes in the module. This requires graphviz to 45 | be installed. To disable the inheritance diagram, you can do:: 46 | 47 | .. automodapi:: mypackage.mymodule 48 | :no-inheritance-diagram: 49 | 50 | The ``automodapi`` directive takes other options that are described in more 51 | detail in the `User guide`_ below. 52 | 53 | If you are documenting a module which imports classes from other files, and you 54 | want to include an inheritance diagram for the classes, you may run into Sphinx 55 | warnings, because the class may be documented as e.g. ``astropy.table.Table`` 56 | but the class really lives at ``astropy.table.core.Table``. To fix this you can 57 | make use of the ``'sphinx_automodapi.smart_resolver'`` Sphinx extension, which 58 | will automatically try and resolve such differences. In this, case, be sure to 59 | include:: 60 | 61 | extensions = ['sphinx_automodapi.automodapi', 62 | 'sphinx_automodapi.smart_resolver'] 63 | 64 | in your ``conf.py`` file. 65 | 66 | User guide 67 | ---------- 68 | 69 | .. toctree:: 70 | :maxdepth: 1 71 | 72 | automodapi.rst 73 | automodsumm.rst 74 | 75 | Dependency Version Guidelines 76 | ----------------------------- 77 | 78 | As a general guideline, automodapi dependencies (at the time of writing, just 79 | Sphinx) aim to maintain compatibility with versions <= 2 years old. Dependencies 80 | may be newer, however, if specific features become important to help automodapi 81 | work better or be more maintainable. 82 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = ["setuptools>=30.3.0", 3 | "setuptools_scm>=8.0.0", 4 | "wheel"] 5 | build-backend = 'setuptools.build_meta' 6 | 7 | 8 | [tool.setuptools_scm] 9 | version_file = "sphinx_automodapi/version.py" 10 | -------------------------------------------------------------------------------- /setup.cfg: -------------------------------------------------------------------------------- 1 | [metadata] 2 | name = sphinx-automodapi 3 | description = Sphinx extension for auto-generating API documentation for entire modules 4 | long_description = file:README.rst 5 | long_description_content_type = text/x-rst 6 | author = The Astropy Developers 7 | author_email = astropy.team@gmail.com 8 | license = BSD 3-Clause License 9 | url = https://github.com/astropy/sphinx-automodapi 10 | classifiers = 11 | Development Status :: 5 - Production/Stable 12 | Intended Audience :: Developers 13 | Programming Language :: Python 14 | Programming Language :: Python :: 3 15 | Operating System :: OS Independent 16 | License :: OSI Approved :: BSD License 17 | 18 | [options] 19 | zip_safe = False 20 | packages = find: 21 | python_requires = >=3.8 22 | install_requires = 23 | packaging 24 | sphinx>=4 25 | 26 | [options.extras_require] 27 | test = 28 | pytest 29 | pytest-cov 30 | cython 31 | coverage 32 | setuptools;python_version>='3.12' 33 | rtd = 34 | sphinx-rtd-theme 35 | 36 | [options.package_data] 37 | sphinx_automodapi = templates/*/*.rst 38 | sphinx_automodapi.tests = cases/*/*.*, cases/*/*/*.*, cases/*/*/*/*.*, cases/*/*/*/*/*.*, duplicated_warning/docs/* 39 | 40 | [tool:pytest] 41 | minversion = 4.6 42 | testpaths = sphinx_automodapi 43 | xfail_strict = true 44 | filterwarnings = 45 | error 46 | ignore:The `docutils\.parsers\.rst\.directive\.html` module will be removed:DeprecationWarning 47 | ignore:'contextfunction' is renamed to 'pass_context':DeprecationWarning 48 | ignore:'environmentfilter' is renamed to 'pass_environment':DeprecationWarning 49 | ignore:distutils Version classes are deprecated:DeprecationWarning 50 | ignore:'imghdr' is deprecated and slated for removal in Python 3.13:DeprecationWarning 51 | ignore:The alias 'sphinx\.util\.SkipProgressMessage' is deprecated 52 | ignore:The alias 'sphinx\.util\.progress_message' is deprecated 53 | ignore:Deprecated call to.*pkg_resources\.declare_namespace:DeprecationWarning 54 | # pip 23.1 issue: 55 | ignore:pkg_resources is deprecated as an API:DeprecationWarning 56 | 57 | [flake8] 58 | max-line-length = 125 59 | exclude = sphinx_automodapi/tests/test_autodoc_enhancements.py,sphinx_automodapi/tests/test_automodapi.py 60 | -------------------------------------------------------------------------------- /sphinx_automodapi/__init__.py: -------------------------------------------------------------------------------- 1 | from .version import version as __version__ # noqa 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/autodoc_enhancements.py: -------------------------------------------------------------------------------- 1 | """ 2 | Miscellaneous enhancements to help autodoc along. 3 | """ 4 | import dataclasses 5 | 6 | from sphinx.ext.autodoc import AttributeDocumenter 7 | 8 | __all__ = [] 9 | 10 | class_types = (type,) 11 | MethodDescriptorType = type(type.__subclasses__) 12 | 13 | 14 | # See 15 | # https://github.com/astropy/astropy-helpers/issues/116#issuecomment-71254836 16 | # for further background on this. 17 | def type_object_attrgetter(obj, attr, *defargs): 18 | """ 19 | This implements an improved attrgetter for type objects (i.e. classes) 20 | that can handle class attributes that are implemented as properties on 21 | a metaclass. 22 | 23 | Normally `getattr` on a class with a `property` (say, "foo"), would return 24 | the `property` object itself. However, if the class has a metaclass which 25 | *also* defines a `property` named "foo", ``getattr(cls, 'foo')`` will find 26 | the "foo" property on the metaclass and resolve it. For the purposes of 27 | autodoc we just want to document the "foo" property defined on the class, 28 | not on the metaclass. 29 | 30 | For example:: 31 | 32 | >>> class Meta(type): 33 | ... @property 34 | ... def foo(cls): 35 | ... return 'foo' 36 | ... 37 | >>> class MyClass(metaclass=Meta): 38 | ... @property 39 | ... def foo(self): 40 | ... \"\"\"Docstring for MyClass.foo property.\"\"\" 41 | ... return 'myfoo' 42 | ... 43 | >>> getattr(MyClass, 'foo') 44 | 'foo' 45 | >>> type_object_attrgetter(MyClass, 'foo') 46 | 47 | >>> type_object_attrgetter(MyClass, 'foo').__doc__ 48 | 'Docstring for MyClass.foo property.' 49 | 50 | The last line of the example shows the desired behavior for the purposes 51 | of autodoc. 52 | """ 53 | 54 | for base in obj.__mro__: 55 | if attr in base.__dict__: 56 | if isinstance(base.__dict__[attr], property): 57 | # Note, this should only be used for properties--for any other 58 | # type of descriptor (classmethod, for example) this can mess 59 | # up existing expectations of what getattr(cls, ...) returns 60 | return base.__dict__[attr] 61 | break 62 | 63 | try: 64 | return getattr(obj, attr, *defargs) 65 | except AttributeError: 66 | # for dataclasses, get the attribute from the __dataclass_fields__ 67 | if dataclasses.is_dataclass(obj) and attr in obj.__dataclass_fields__: 68 | return obj.__dataclass_fields__[attr].default 69 | else: 70 | raise 71 | 72 | 73 | def setup(app): 74 | # Must have the autodoc extension set up first so we can override it 75 | app.setup_extension('sphinx.ext.autodoc') 76 | 77 | app.add_autodoc_attrgetter(type, type_object_attrgetter) 78 | 79 | suppress_warnings_orig = app.config.suppress_warnings[:] 80 | if 'app.add_directive' not in app.config.suppress_warnings: 81 | app.config.suppress_warnings.append('app.add_directive') 82 | try: 83 | app.add_autodocumenter(AttributeDocumenter) 84 | finally: 85 | app.config.suppress_warnings = suppress_warnings_orig 86 | 87 | return {'parallel_read_safe': True, 88 | 'parallel_write_safe': True} 89 | -------------------------------------------------------------------------------- /sphinx_automodapi/automodapi.py: -------------------------------------------------------------------------------- 1 | # Licensed under a 3-clause BSD style license - see LICENSE.rst 2 | """ 3 | This directive takes a single argument that must be a module or package. It 4 | will produce a block of documentation that includes the docstring for the 5 | package, an :ref:`automodsumm` directive, and an :ref:`automod-diagram` if 6 | there are any classes in the module. If only the main docstring of the 7 | module/package is desired in the documentation, use `automodule`_ instead of 8 | `automodapi`_. 9 | 10 | It accepts the following options: 11 | 12 | * ``:include-all-objects:`` 13 | If present, include not just functions and classes, but all objects. 14 | This includes variables, for which a possible docstring after the 15 | variable definition will be shown. 16 | 17 | * ``:inheritance-diagram:`` / ``:no-inheritance-diagram:`` 18 | Specify whether or not to show the inheritance diagram for classes. This 19 | overrides the default global configuration set in 20 | ``automodapi_inheritance_diagram``. 21 | 22 | * ``:skip: str`` 23 | This option results in the 24 | specified object being skipped, that is the object will *not* be 25 | included in the generated documentation. This option may appear 26 | any number of times to skip multiple objects. 27 | 28 | * ``:include: str`` 29 | This option is the opposite of :skip: -- if specified, only the object 30 | names that match any of the names passed to :include: will be included 31 | in the generated documentation. This option may appear multiple times 32 | to include multiple objects. 33 | 34 | * ``:no-main-docstr:`` 35 | If present, the docstring for the module/package will not be generated. 36 | The function and class tables will still be used, however. 37 | 38 | * ``:headings: str`` 39 | Specifies the characters (in one string) used as the heading 40 | levels used for the generated section. This must have at least 2 41 | characters (any after 2 will be ignored). This also *must* match 42 | the rest of the documentation on this page for sphinx to be 43 | happy. Defaults to "-^", which matches the convention used for 44 | Python's documentation, assuming the automodapi call is inside a 45 | top-level section (which usually uses '='). 46 | 47 | * ``:no-heading:`` 48 | If specified do not create a top level heading for the section. 49 | That is, do not create a title heading with text like "packagename 50 | Package". The actual docstring for the package/module will still be 51 | shown, though, unless ``:no-main-docstr:`` is given. 52 | 53 | * ``:allowed-package-names: str`` 54 | Specifies the packages that functions/classes documented here are 55 | allowed to be from, as comma-separated list of package names. If not 56 | given, only objects that are actually in a subpackage of the package 57 | currently being documented are included. 58 | 59 | * ``:inherited-members:`` / ``:no-inherited-members:`` 60 | The global sphinx configuration option 61 | ``automodsumm_inherited_members`` decides if members that a class 62 | inherits from a base class are included in the generated 63 | documentation. The option ``:inherited-members:`` or ``:no-inherited-members:`` 64 | allows the user to overrride the global setting. 65 | 66 | * ``:noindex:`` 67 | Propagates the ``noindex`` flag to autodoc. Use it to avoid duplicate 68 | objects warnings. 69 | 70 | * ``:sort:`` 71 | If the module contains ``__all__``, sort the module's objects 72 | alphabetically (if ``__all__`` is not present, the objects are found 73 | using `dir`, which always gives a sorted list). 74 | 75 | 76 | This extension also adds five sphinx configuration options: 77 | 78 | * ``automodapi_inheritance_diagram`` 79 | Should be a boolean that indicates whether to show inheritance diagrams 80 | by default. This can be overriden on a case by case basis with 81 | ``:inheritance-diagram:`` and ``:no-inheritance-diagram:``. Defaults to 82 | ``True``. 83 | 84 | * ``automodapi_toctreedirnm`` 85 | This must be a string that specifies the name of the directory the 86 | automodsumm generated documentation ends up in. This directory path should 87 | be relative to the documentation root (e.g., same place as ``index.rst``). 88 | Defaults to ``'api'``. 89 | 90 | * ``automodapi_writereprocessed`` 91 | Should be a bool, and if `True`, will cause `automodapi`_ to write files 92 | with any `automodapi`_ sections replaced with the content Sphinx 93 | processes after `automodapi`_ has run. The output files are not 94 | actually used by sphinx, so this option is only for figuring out the 95 | cause of sphinx warnings or other debugging. Defaults to `False`. 96 | 97 | * ``automodsumm_inherited_members`` 98 | Should be a bool and if ``True`` members that a class inherits from a base 99 | class are included in the generated documentation. Defaults to ``False``. 100 | 101 | * ``automodsumm_included_members`` 102 | A list of strings containing the names of hidden class members that should be 103 | included in the documentation. This is most commonly used to add special class 104 | methods like ``__getitem__`` and ``__setitem__``. Defaults to 105 | ``['__init__', '__call__']``. 106 | 107 | * ``automodsumm_properties_are_attributes`` 108 | Should be a bool and if ``True`` properties are treated as attributes in the 109 | documentation meaning that no property specific documentation is generated. 110 | Defaults to ``True``. 111 | 112 | .. _automodule: http://sphinx-doc.org/latest/ext/autodoc.html?highlight=automodule#directive-automodule 113 | """ 114 | 115 | # Implementation note: 116 | # The 'automodapi' directive is not actually implemented as a docutils 117 | # directive. Instead, this extension searches for the 'automodapi' text in 118 | # all sphinx documents, and replaces it where necessary from a template built 119 | # into this extension. This is necessary because automodsumm (and autosummary) 120 | # use the "builder-inited" event, which comes before the directives are 121 | # actually built. 122 | 123 | import inspect 124 | import os 125 | import re 126 | import sys 127 | 128 | from sphinx.util import logging 129 | 130 | from .utils import find_mod_objs 131 | 132 | __all__ = [] 133 | 134 | automod_templ_modheader = """ 135 | {modname} {pkgormod} 136 | {modhds}{pkgormodhds} 137 | 138 | {automoduleline} 139 | """ 140 | 141 | automod_templ_classes = """ 142 | Classes 143 | {clshds} 144 | 145 | .. automodsumm:: {modname} 146 | :classes-only: 147 | {clsfuncoptions} 148 | """ 149 | 150 | automod_templ_funcs = """ 151 | Functions 152 | {funchds} 153 | 154 | .. automodsumm:: {modname} 155 | :functions-only: 156 | {clsfuncoptions} 157 | """ 158 | 159 | automod_templ_vars = """ 160 | Variables 161 | {otherhds} 162 | 163 | .. automodsumm:: {modname} 164 | :variables-only: 165 | {clsfuncoptions} 166 | """ 167 | 168 | automod_templ_inh = """ 169 | Class Inheritance Diagram 170 | {clsinhsechds} 171 | 172 | .. automod-diagram:: {modname} 173 | :private-bases: 174 | :parts: 1 175 | {allowedpkgnms} 176 | {skip} 177 | """ 178 | 179 | _automodapirex = re.compile(r'^(?:\.\.\s+automodapi::\s*)([A-Za-z0-9_.]+)' 180 | r'\s*$((?:\n\s+:[a-zA-Z_\-]+:.*$)*)', 181 | flags=re.MULTILINE) 182 | # the last group of the above regex is intended to go into finall with the below 183 | _automodapiargsrex = re.compile(r':([a-zA-Z_\-]+):(.*)$', flags=re.MULTILINE) 184 | 185 | 186 | def automodapi_replace(sourcestr, app, dotoctree=True, docname=None, 187 | warnings=True): 188 | """ 189 | Replaces `sourcestr`'s entries of ".. automodapi::" with the 190 | automodapi template form based on provided options. 191 | 192 | This is used with the sphinx event 'source-read' to replace 193 | `automodapi`_ entries before sphinx actually processes them, as 194 | automodsumm needs the code to be present to generate stub 195 | documentation. 196 | 197 | Parameters 198 | ---------- 199 | sourcestr : str 200 | The string with sphinx source to be checked for automodapi 201 | replacement. 202 | app : `sphinx.application.Application` 203 | The sphinx application. 204 | dotoctree : bool 205 | If `True`, a ":toctree:" option will be added in the ".. 206 | automodsumm::" sections of the template, pointing to the 207 | appropriate "generated" directory based on the Astropy convention 208 | (e.g. in ``docs/api``) 209 | docname : str 210 | The name of the file for this `sourcestr` (if known - if not, it 211 | can be `None`). If not provided and `dotoctree` is `True`, the 212 | generated files may end up in the wrong place. 213 | warnings : bool 214 | If `False`, all warnings that would normally be issued are 215 | silenced. 216 | 217 | Returns 218 | ------- 219 | newstr :str 220 | The string with automodapi entries replaced with the correct 221 | sphinx markup. 222 | """ 223 | 224 | logger = logging.getLogger(__name__) 225 | 226 | spl = _automodapirex.split(sourcestr) 227 | if len(spl) > 1: # automodsumm is in this document 228 | 229 | # Use app.srcdir because api folder should be inside source folder not 230 | # at folder where sphinx is run. 231 | 232 | if dotoctree: 233 | toctreestr = ':toctree: ' 234 | api_dir = os.path.join(app.srcdir, app.config.automodapi_toctreedirnm) 235 | if docname is None: 236 | doc_path = app.srcdir 237 | else: 238 | doc_path = os.path.dirname(os.path.join(app.srcdir, docname)) 239 | toctreestr += os.path.relpath(api_dir, doc_path).replace(os.sep, '/') 240 | else: 241 | toctreestr = '' 242 | 243 | newstrs = [spl[0]] 244 | for grp in range(len(spl) // 3): 245 | modnm = spl[grp * 3 + 1] 246 | 247 | # find where this is in the document for warnings 248 | if docname is None: 249 | location = None 250 | else: 251 | location = (docname, spl[0].count('\n')) 252 | 253 | # initialize default options 254 | toskip = [] 255 | includes = [] 256 | inhdiag = app.config.automodapi_inheritance_diagram 257 | maindocstr = True 258 | top_head = True 259 | hds = '-^' 260 | allowedpkgnms = [] 261 | allowothers = False 262 | noindex = False 263 | sort = False 264 | 265 | # look for actual options 266 | unknownops = [] 267 | inherited_members = None 268 | for opname, args in _automodapiargsrex.findall(spl[grp * 3 + 2]): 269 | if opname == 'skip': 270 | toskip.append(args.strip()) 271 | elif opname == 'include': 272 | includes.append(args.strip()) 273 | elif opname == 'inheritance-diagram': 274 | inhdiag = True 275 | elif opname == 'no-inheritance-diagram': 276 | inhdiag = False 277 | elif opname == 'no-main-docstr': 278 | maindocstr = False 279 | elif opname == 'headings': 280 | hds = args 281 | elif opname == 'no-heading': 282 | top_head = False 283 | elif opname == 'allowed-package-names': 284 | allowedpkgnms.extend(arg.strip() for arg in args.split(',')) 285 | elif opname == 'inherited-members': 286 | inherited_members = True 287 | elif opname == 'no-inherited-members': 288 | inherited_members = False 289 | elif opname == 'include-all-objects': 290 | allowothers = True 291 | elif opname == 'noindex': 292 | noindex = True 293 | elif opname == 'sort': 294 | sort = True 295 | else: 296 | unknownops.append(opname) 297 | 298 | # join all the allowedpkgnms 299 | if len(allowedpkgnms) == 0: 300 | allowedpkgnms = '' 301 | onlylocals = True 302 | else: 303 | onlylocals = allowedpkgnms 304 | allowedpkgnms = ':allowed-package-names: ' + ','.join(allowedpkgnms) 305 | 306 | # get the two heading chars 307 | hds = hds.strip() 308 | if len(hds) < 2: 309 | msg = 'Not enough headings (got {0}, need 2), using default -^' 310 | if warnings: 311 | logger.warning(msg.format(len(hds)), location) 312 | hds = '-^' 313 | h1, h2 = hds[:2] 314 | 315 | # tell sphinx that the remaining args are invalid. 316 | if len(unknownops) > 0 and app is not None: 317 | opsstrs = ','.join(unknownops) 318 | msg = 'Found additional options ' + opsstrs + ' in automodapi.' 319 | if warnings: 320 | logger.warning(msg, location) 321 | 322 | ispkg, hascls, hasfuncs, hasother, toskip = _mod_info( 323 | modnm, toskip, includes, onlylocals=onlylocals) 324 | 325 | # add automodule directive only if no-main-docstr isn't present 326 | if maindocstr: 327 | automodline = '.. automodule:: {modname}'.format(modname=modnm) 328 | else: 329 | automodline = '' 330 | if top_head: 331 | newstrs.append(automod_templ_modheader.format( 332 | modname=modnm, 333 | modhds=h1 * len(modnm), 334 | pkgormod='Package' if ispkg else 'Module', 335 | pkgormodhds=h1 * (8 if ispkg else 7), 336 | automoduleline=automodline)) # noqa 337 | else: 338 | newstrs.append(automod_templ_modheader.format( 339 | modname='', 340 | modhds='', 341 | pkgormod='', 342 | pkgormodhds='', 343 | automoduleline=automodline)) 344 | 345 | # construct the options for the class/function sections 346 | # start out indented at 4 spaces, but need to keep the indentation. 347 | clsfuncoptions = [] 348 | if toctreestr: 349 | clsfuncoptions.append(toctreestr) 350 | if noindex: 351 | clsfuncoptions.append(':noindex:') 352 | if sort: 353 | clsfuncoptions.append(':sort:') 354 | if toskip: 355 | clsfuncoptions.append(':skip: ' + ','.join(toskip)) 356 | if allowedpkgnms: 357 | clsfuncoptions.append(allowedpkgnms) 358 | if hascls: # This makes no sense unless there are classes. 359 | if inherited_members is True: 360 | clsfuncoptions.append(':inherited-members:') 361 | if inherited_members is False: 362 | clsfuncoptions.append(':no-inherited-members:') 363 | clsfuncoptionstr = '\n '.join(clsfuncoptions) 364 | 365 | if hasfuncs: 366 | newstrs.append(automod_templ_funcs.format( 367 | modname=modnm, 368 | funchds=h2 * 9, 369 | clsfuncoptions=clsfuncoptionstr)) 370 | 371 | if hascls: 372 | newstrs.append(automod_templ_classes.format( 373 | modname=modnm, 374 | clshds=h2 * 7, 375 | clsfuncoptions=clsfuncoptionstr)) 376 | 377 | if allowothers and hasother: 378 | newstrs.append(automod_templ_vars.format( 379 | modname=modnm, 380 | otherhds=h2 * 9, 381 | clsfuncoptions=clsfuncoptionstr)) 382 | 383 | if inhdiag and hascls: 384 | # add inheritance diagram if any classes are in the module 385 | if toskip: 386 | clsskip = ':skip: ' + ','.join(toskip) 387 | else: 388 | clsskip = '' 389 | diagram_entry = automod_templ_inh.format( 390 | modname=modnm, 391 | clsinhsechds=h2 * 25, 392 | allowedpkgnms=allowedpkgnms, 393 | skip=clsskip) 394 | diagram_entry = diagram_entry.replace(' \n', '') 395 | newstrs.append(diagram_entry) 396 | 397 | newstrs.append(spl[grp * 3 + 3]) 398 | 399 | newsourcestr = ''.join(newstrs) 400 | 401 | if app.config.automodapi_writereprocessed: 402 | # sometimes they are unicode, sometimes not, depending on how 403 | # sphinx has processed things 404 | if isinstance(newsourcestr, str): 405 | ustr = newsourcestr 406 | else: 407 | ustr = newsourcestr.decode(app.config.source_encoding) 408 | 409 | if docname is None: 410 | with open(os.path.join(app.srcdir, 'unknown.automodapi'), 411 | 'a', encoding='utf8') as f: 412 | f.write(u'\n**NEW DOC**\n\n') 413 | f.write(ustr) 414 | else: 415 | env = app.builder.env 416 | # Determine the filename associated with this doc (specifically 417 | # the extension) 418 | filename = docname + os.path.splitext(env.doc2path(docname))[1] 419 | filename += '.automodapi' 420 | 421 | with open(os.path.join(app.srcdir, filename), 'w', 422 | encoding='utf8') as f: 423 | f.write(ustr) 424 | 425 | return newsourcestr 426 | else: 427 | return sourcestr 428 | 429 | 430 | def _mod_info(modname, toskip=[], include=[], onlylocals=True): 431 | """ 432 | Determines if a module is a module or a package and whether or not 433 | it has classes or functions. 434 | """ 435 | 436 | hascls = hasfunc = hasother = False 437 | 438 | skips = toskip.copy() 439 | for localnm, fqnm, obj in zip(*find_mod_objs(modname, onlylocals=onlylocals)): 440 | if include and localnm not in include and localnm not in skips: 441 | skips.append(localnm) 442 | 443 | elif localnm not in toskip: 444 | hascls = hascls or inspect.isclass(obj) 445 | hasfunc = hasfunc or inspect.isroutine(obj) 446 | hasother = hasother or (not inspect.isclass(obj) and 447 | not inspect.isroutine(obj)) 448 | if hascls and hasfunc and hasother: 449 | break 450 | 451 | # find_mod_objs has already imported modname 452 | # TODO: There is probably a cleaner way to do this, though this is pretty 453 | # reliable for all Python versions for most cases that we care about. 454 | pkg = sys.modules[modname] 455 | ispkg = (hasattr(pkg, '__file__') and isinstance(pkg.__file__, str) and 456 | os.path.split(pkg.__file__)[1].startswith('__init__.py')) 457 | 458 | return ispkg, hascls, hasfunc, hasother, skips 459 | 460 | 461 | def process_automodapi(app, docname, source): 462 | source[0] = automodapi_replace(source[0], app, True, docname) 463 | 464 | 465 | def setup(app): 466 | 467 | app.setup_extension('sphinx.ext.autosummary') 468 | 469 | # Note: we use __name__ here instead of just writing the module name in 470 | # case this extension is bundled into another package 471 | from . import automodsumm 472 | app.setup_extension(automodsumm.__name__) 473 | 474 | app.connect('source-read', process_automodapi) 475 | 476 | app.add_config_value('automodapi_inheritance_diagram', True, True) 477 | app.add_config_value('automodapi_toctreedirnm', 'api', True) 478 | app.add_config_value('automodapi_writereprocessed', False, True) 479 | 480 | return {'parallel_read_safe': True, 481 | 'parallel_write_safe': True} 482 | -------------------------------------------------------------------------------- /sphinx_automodapi/smart_resolver.py: -------------------------------------------------------------------------------- 1 | # Licensed under a 3-clause BSD style license - see LICENSE.rst 2 | """ 3 | The classes in the astropy docs are documented by their API location, 4 | which is not necessarily where they are defined in the source. This 5 | causes a problem when certain automated features of the doc build, 6 | such as the inheritance diagrams or the `Bases` list of a class 7 | reference a class by its canonical location rather than its "user" 8 | location. 9 | 10 | In the `autodoc-process-docstring` event, a mapping from the actual 11 | name to the API name is maintained. Later, in the `missing-reference` 12 | event, unresolved references are looked up in this dictionary and 13 | corrected if possible. 14 | """ 15 | 16 | from docutils.nodes import literal, reference 17 | 18 | 19 | def process_docstring(app, what, name, obj, options, lines): 20 | if isinstance(obj, type): 21 | env = app.env 22 | if not hasattr(env, 'class_name_mapping'): 23 | env.class_name_mapping = {} 24 | mapping = env.class_name_mapping 25 | mapping[obj.__module__ + '.' + obj.__name__] = name 26 | 27 | 28 | def merge_mapping(app, env, docnames, env_other): 29 | if not hasattr(env_other, 'class_name_mapping'): 30 | return 31 | if not hasattr(env, 'class_name_mapping'): 32 | env.class_name_mapping = {} 33 | env.class_name_mapping.update(env_other.class_name_mapping) 34 | 35 | 36 | def missing_reference_handler(app, env, node, contnode): 37 | """ 38 | Handler to be connect to the sphinx 'missing-reference' event. The handler a 39 | resolves reference (node) and returns a new node when sphinx could not 40 | originally resolve the reference. 41 | 42 | see `missing-reference in sphinx documentation 43 | `_ 44 | 45 | :param app: The Sphinx application object 46 | :param env: The build environment (``app.builder.env`) 47 | :param node: The ``pending_xref`` node to be resolved. Its attributes reftype, 48 | reftarget, modname and classname attributes determine the type and 49 | target of the reference. 50 | :param contnode: The node that carries the text and formatting inside the 51 | future reference and should be a child of the returned 52 | reference node. 53 | """ 54 | # a good example of how a missing reference handle works look to 55 | # https://github.com/sphinx-doc/sphinx/issues/1572#issuecomment-68590981 56 | # 57 | # Important attributes of the "node": 58 | # 59 | # example role: :ref:`title ` 60 | # 61 | # 'reftype' - role name (in the example above 'ref' is the reftype) 62 | # 'reftarget' - target of the role, as given in the role content 63 | # (in the example 'target' is the reftarget 64 | # 'refexplicit' - the explicit title of the role 65 | # (in the example 'title' is the refexplicit) 66 | # 'refdoc' - document in which the role appeared 67 | # 'refdomain' - domain of the role, in our case emtpy 68 | 69 | if not hasattr(env, 'class_name_mapping'): 70 | env.class_name_mapping = {} 71 | mapping = env.class_name_mapping 72 | 73 | reftype = node['reftype'] 74 | reftarget = node['reftarget'] 75 | refexplicit = node.get('refexplicit') # default: None 76 | refdoc = node.get('refdoc', env.docname) 77 | if reftype in ('obj', 'class', 'exc', 'meth'): 78 | suffix = '' 79 | if reftarget not in mapping: 80 | if '.' in reftarget: 81 | front, suffix = reftarget.rsplit('.', 1) 82 | else: 83 | front = None 84 | suffix = reftarget 85 | 86 | if suffix.startswith('_') and not suffix.startswith('__'): 87 | # If this is a reference to a hidden class or method, 88 | # we can't link to it, but we don't want to have a 89 | # nitpick warning. 90 | return node[0].deepcopy() 91 | 92 | if reftype in ('obj', 'meth') and front is not None: 93 | if front in mapping: 94 | reftarget = front 95 | suffix = '.' + suffix 96 | 97 | if (reftype in ('class', ) and '.' in reftarget and 98 | reftarget not in mapping): 99 | 100 | if '.' in front: 101 | reftarget, _ = front.rsplit('.', 1) 102 | suffix = '.' + suffix 103 | reftarget = reftarget + suffix 104 | prefix = reftarget.rsplit('.')[0] 105 | inventory = getattr(env, 'intersphinx_named_inventory', {}) 106 | if (reftarget not in mapping and 107 | prefix in inventory): 108 | 109 | if 'py:class' in inventory[prefix] and \ 110 | reftarget in inventory[prefix]['py:class']: 111 | newtarget = inventory[prefix]['py:class'][reftarget][2] 112 | if not refexplicit and '~' not in node.rawsource: 113 | contnode = literal(text=reftarget) 114 | newnode = reference('', '', internal=True) 115 | newnode['reftitle'] = reftarget 116 | newnode['refuri'] = newtarget 117 | newnode.append(contnode) 118 | 119 | return newnode 120 | 121 | if reftarget in mapping: 122 | newtarget = mapping[reftarget] + suffix 123 | if not refexplicit and '~' not in node.rawsource: 124 | contnode = literal(text=newtarget) 125 | newnode = env.domains['py'].resolve_xref(env, refdoc, app.builder, 'class', 126 | newtarget, node, contnode) 127 | if newnode is not None: 128 | newnode['reftitle'] = reftarget 129 | return newnode 130 | 131 | 132 | def setup(app): 133 | 134 | app.connect('autodoc-process-docstring', process_docstring) 135 | app.connect('missing-reference', missing_reference_handler) 136 | app.connect('env-merge-info', merge_mapping) 137 | 138 | return {'parallel_read_safe': True, 139 | 'parallel_write_safe': True} 140 | -------------------------------------------------------------------------------- /sphinx_automodapi/templates/autosummary_core/base.rst: -------------------------------------------------------------------------------- 1 | {% if referencefile %} 2 | .. include:: {{ referencefile }} 3 | {% endif %} 4 | 5 | {{ objname }} 6 | {{ underline }} 7 | 8 | .. currentmodule:: {{ module }} 9 | 10 | .. auto{{ objtype }}:: {{ objname }} 11 | -------------------------------------------------------------------------------- /sphinx_automodapi/templates/autosummary_core/class.rst: -------------------------------------------------------------------------------- 1 | {% if referencefile %} 2 | .. include:: {{ referencefile }} 3 | {% endif %} 4 | 5 | {{ objname }} 6 | {{ underline }} 7 | 8 | .. currentmodule:: {{ module }} 9 | 10 | .. autoclass:: {{ objname }} 11 | :show-inheritance: 12 | {% if noindex -%} 13 | :noindex: 14 | {%- endif %} 15 | 16 | {% if '__init__' in methods %} 17 | {% set caught_result = methods.remove('__init__') %} 18 | {% endif %} 19 | 20 | {% block attributes_summary %} 21 | {% if attributes or properties %} 22 | 23 | .. rubric:: Attributes Summary 24 | 25 | .. autosummary:: 26 | {% for item in attributes %} 27 | ~{{ name }}.{{ item }} 28 | {%- endfor %} 29 | 30 | {% for item in properties %} 31 | ~{{ name }}.{{ item }} 32 | {%- endfor %} 33 | 34 | {% endif %} 35 | {% endblock %} 36 | 37 | {% block methods_summary %} 38 | {% if methods %} 39 | 40 | .. rubric:: Methods Summary 41 | 42 | .. autosummary:: 43 | {% for item in methods %} 44 | ~{{ name }}.{{ item }} 45 | {%- endfor %} 46 | 47 | {% endif %} 48 | {% endblock %} 49 | 50 | {% block attributes_documentation %} 51 | {% if attributes or properties%} 52 | 53 | .. rubric:: Attributes Documentation 54 | 55 | {% for item in attributes %} 56 | .. autoattribute:: {{ item }} 57 | {%- endfor %} 58 | 59 | {% for item in properties %} 60 | .. autoproperty:: {{ item }} 61 | {%- endfor %} 62 | 63 | {% endif %} 64 | {% endblock %} 65 | 66 | {% block methods_documentation %} 67 | {% if methods %} 68 | 69 | .. rubric:: Methods Documentation 70 | 71 | {% for item in methods %} 72 | .. automethod:: {{ item }} 73 | {%- endfor %} 74 | 75 | {% endif %} 76 | {% endblock %} 77 | -------------------------------------------------------------------------------- /sphinx_automodapi/templates/autosummary_core/module.rst: -------------------------------------------------------------------------------- 1 | {% if referencefile %} 2 | .. include:: {{ referencefile }} 3 | {% endif %} 4 | 5 | {{ objname }} 6 | {{ underline }} 7 | 8 | .. automodule:: {{ fullname }} 9 | 10 | {% block functions %} 11 | {% if functions %} 12 | .. rubric:: Functions 13 | 14 | .. autosummary:: 15 | {% for item in functions %} 16 | {{ item }} 17 | {%- endfor %} 18 | {% endif %} 19 | {% endblock %} 20 | 21 | {% block classes %} 22 | {% if classes %} 23 | .. rubric:: Classes 24 | 25 | .. autosummary:: 26 | {% for item in classes %} 27 | {{ item }} 28 | {%- endfor %} 29 | {% endif %} 30 | {% endblock %} 31 | 32 | {% block exceptions %} 33 | {% if exceptions %} 34 | .. rubric:: Exceptions 35 | 36 | .. autosummary:: 37 | {% for item in exceptions %} 38 | {{ item }} 39 | {%- endfor %} 40 | {% endif %} 41 | {% endblock %} 42 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/__init__.py: -------------------------------------------------------------------------------- 1 | import os 2 | import sys 3 | import subprocess as sp 4 | 5 | from textwrap import dedent 6 | 7 | import pytest 8 | 9 | 10 | @pytest.fixture 11 | def cython_testpackage(tmpdir, request): 12 | """ 13 | Creates a trivial Cython package for use with tests. 14 | """ 15 | 16 | test_pkg = tmpdir.mkdir('test_pkg') 17 | test_pkg.mkdir('apyhtest_eva').ensure('__init__.py') 18 | test_pkg.join('apyhtest_eva').join('unit02.pyx').write(dedent("""\ 19 | def pilot(): 20 | \"\"\"Returns the pilot of Eva Unit-02.\"\"\" 21 | 22 | return True 23 | """)) 24 | 25 | import sphinx_automodapi # noqa 26 | 27 | test_pkg.join('setup.py').write(dedent("""\ 28 | import sys 29 | 30 | sys.path.insert(0, {0!r}) 31 | 32 | from os.path import join 33 | from setuptools import setup, Extension 34 | 35 | NAME = 'apyhtest_eva' 36 | VERSION = 0.1 37 | RELEASE = True 38 | 39 | 40 | setup( 41 | name=NAME, 42 | version=VERSION, 43 | ext_modules=[Extension('apyhtest_eva.unit02', 44 | [join('apyhtest_eva', 'unit02.pyx')])] 45 | ) 46 | """.format(os.path.dirname(sphinx_automodapi.__path__[0])))) 47 | 48 | # Build the Cython module in a subprocess; otherwise strange things can 49 | # happen with Cython's global module state 50 | sp.call([sys.executable, 'setup.py', 'build_ext', '--inplace'], cwd=test_pkg.strpath) 51 | 52 | sys.path.insert(0, str(test_pkg)) 53 | import apyhtest_eva.unit02 # noqa 54 | 55 | def cleanup(test_pkg=test_pkg): 56 | for modname in ['apyhtest_eva', 'apyhtest_eva.unit02']: 57 | try: 58 | del sys.modules[modname] 59 | except KeyError: 60 | pass 61 | 62 | sys.path.remove(str(test_pkg)) 63 | 64 | request.addfinalizer(cleanup) 65 | 66 | return test_pkg 67 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/abstract_classes/README.md: -------------------------------------------------------------------------------- 1 | This example is to make sure that classes derived from the `abc` module will 2 | have their members listed when ``:inherited-members:`` is not in effect 3 | (https://github.com/astropy/sphinx-automodapi/issues/52). 4 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/abstract_classes/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module.abstract_classes 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst: -------------------------------------------------------------------------------- 1 | SequenceSubclass 2 | ================ 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.abstract_classes 5 | 6 | .. autoclass:: SequenceSubclass 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~SequenceSubclass.my_property 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~SequenceSubclass.my_method 20 | 21 | .. rubric:: Attributes Documentation 22 | 23 | .. autoattribute:: my_property 24 | 25 | .. rubric:: Methods Documentation 26 | 27 | .. automethod:: my_method 28 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.abstract_classes Module 3 | -------------------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.abstract_classes 6 | 7 | Classes 8 | ^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.abstract_classes 11 | :classes-only: 12 | :toctree: api 13 | 14 | Class Inheritance Diagram 15 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 16 | 17 | .. automod-diagram:: sphinx_automodapi.tests.example_module.abstract_classes 18 | :private-bases: 19 | :parts: 1 20 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.abstract_classes 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | SequenceSubclass 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst: -------------------------------------------------------------------------------- 1 | SequenceSubclass 2 | ================ 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.abstract_classes 5 | 6 | .. autoclass:: SequenceSubclass 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~SequenceSubclass.my_property 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~SequenceSubclass.my_method 20 | 21 | .. rubric:: Attributes Documentation 22 | 23 | .. autoproperty:: my_property 24 | 25 | .. rubric:: Methods Documentation 26 | 27 | .. automethod:: my_method 28 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.abstract_classes Module 3 | -------------------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.abstract_classes 6 | 7 | Classes 8 | ^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.abstract_classes 11 | :classes-only: 12 | :toctree: api 13 | 14 | Class Inheritance Diagram 15 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 16 | 17 | .. automod-diagram:: sphinx_automodapi.tests.example_module.abstract_classes 18 | :private-bases: 19 | :parts: 1 20 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.abstract_classes 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | SequenceSubclass 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/allowed_names/README.md: -------------------------------------------------------------------------------- 1 | Documenting a module with classes, functions, and variables that are 2 | imported from other files, but where only some of those are allowed. 3 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/allowed_names/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module 2 | :allowed-package-names: sphinx_automodapi.tests.example_module.classes 3 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Egg.rst: -------------------------------------------------------------------------------- 1 | Egg 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Egg 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Egg.weight 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~Egg.buy 20 | ~Egg.eat 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoattribute:: weight 25 | 26 | .. rubric:: Methods Documentation 27 | 28 | .. automethod:: buy 29 | .. automethod:: eat 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst: -------------------------------------------------------------------------------- 1 | Spam 2 | ==== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Spam 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module Package 3 | ---------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module 6 | 7 | Classes 8 | ^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module 11 | :classes-only: 12 | :toctree: api 13 | :allowed-package-names: sphinx_automodapi.tests.example_module.classes 14 | 15 | Class Inheritance Diagram 16 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 17 | 18 | .. automod-diagram:: sphinx_automodapi.tests.example_module 19 | :private-bases: 20 | :parts: 1 21 | :allowed-package-names: sphinx_automodapi.tests.example_module.classes 22 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | Egg 7 | Spam 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst: -------------------------------------------------------------------------------- 1 | Egg 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Egg 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Egg.weight 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~Egg.buy 20 | ~Egg.eat 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoproperty:: weight 25 | 26 | .. rubric:: Methods Documentation 27 | 28 | .. automethod:: buy 29 | .. automethod:: eat 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst: -------------------------------------------------------------------------------- 1 | Spam 2 | ==== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Spam 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module Package 3 | ---------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module 6 | 7 | Classes 8 | ^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module 11 | :classes-only: 12 | :toctree: api 13 | :allowed-package-names: sphinx_automodapi.tests.example_module.classes 14 | 15 | Class Inheritance Diagram 16 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 17 | 18 | .. automod-diagram:: sphinx_automodapi.tests.example_module 19 | :private-bases: 20 | :parts: 1 21 | :allowed-package-names: sphinx_automodapi.tests.example_module.classes 22 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | Egg 7 | Spam 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/attribute_class/README.md: -------------------------------------------------------------------------------- 1 | This example is to make sure that classes can have attributes and properties 2 | and they can be distiguished if ``automodsumm_properties_are_attributes = False`` 3 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/attribute_class/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module.attribute_class 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.attribute_class.ClassWithAttribute.rst: -------------------------------------------------------------------------------- 1 | ClassWithAttribute 2 | ================== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.attribute_class 5 | 6 | .. autoclass:: ClassWithAttribute 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~ClassWithAttribute.my_attribute 14 | ~ClassWithAttribute.my_property 15 | 16 | .. rubric:: Methods Summary 17 | 18 | .. autosummary:: 19 | 20 | ~ClassWithAttribute.my_method 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoattribute:: my_attribute 25 | .. autoattribute:: my_property 26 | 27 | .. rubric:: Methods Documentation 28 | 29 | .. automethod:: my_method 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.attribute_class Module 3 | ------------------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.attribute_class 6 | 7 | Classes 8 | ^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.attribute_class 11 | :classes-only: 12 | :toctree: api 13 | 14 | Class Inheritance Diagram 15 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 16 | 17 | .. automod-diagram:: sphinx_automodapi.tests.example_module.attribute_class 18 | :private-bases: 19 | :parts: 1 20 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.attribute_class 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | ClassWithAttribute 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.attribute_class.ClassWithAttribute.rst: -------------------------------------------------------------------------------- 1 | ClassWithAttribute 2 | ================== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.attribute_class 5 | 6 | .. autoclass:: ClassWithAttribute 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~ClassWithAttribute.my_attribute 14 | 15 | ~ClassWithAttribute.my_property 16 | 17 | .. rubric:: Methods Summary 18 | 19 | .. autosummary:: 20 | 21 | ~ClassWithAttribute.my_method 22 | 23 | .. rubric:: Attributes Documentation 24 | 25 | .. autoattribute:: my_attribute 26 | 27 | .. autoproperty:: my_property 28 | 29 | .. rubric:: Methods Documentation 30 | 31 | .. automethod:: my_method 32 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.attribute_class Module 3 | ------------------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.attribute_class 6 | 7 | Classes 8 | ^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.attribute_class 11 | :classes-only: 12 | :toctree: api 13 | 14 | Class Inheritance Diagram 15 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 16 | 17 | .. automod-diagram:: sphinx_automodapi.tests.example_module.attribute_class 18 | :private-bases: 19 | :parts: 1 20 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.attribute_class 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | ClassWithAttribute 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_no_inherit/README.md: -------------------------------------------------------------------------------- 1 | Documenting a module with classes but excluding a class with inheritance 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_no_inherit/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module.classes 2 | :skip: Spam 3 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst: -------------------------------------------------------------------------------- 1 | Egg 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 5 | 6 | .. autoclass:: Egg 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Egg.weight 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~Egg.buy 20 | ~Egg.eat 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoattribute:: weight 25 | 26 | .. rubric:: Methods Documentation 27 | 28 | .. automethod:: buy 29 | .. automethod:: eat 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.classes Module 3 | ----------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.classes 6 | 7 | Classes 8 | ^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.classes 11 | :classes-only: 12 | :toctree: api 13 | :skip: Spam 14 | 15 | Class Inheritance Diagram 16 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 17 | 18 | .. automod-diagram:: sphinx_automodapi.tests.example_module.classes 19 | :private-bases: 20 | :parts: 1 21 | :skip: Spam 22 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | Egg 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst: -------------------------------------------------------------------------------- 1 | Egg 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 5 | 6 | .. autoclass:: Egg 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Egg.weight 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~Egg.buy 20 | ~Egg.eat 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoproperty:: weight 25 | 26 | .. rubric:: Methods Documentation 27 | 28 | .. automethod:: buy 29 | .. automethod:: eat 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_not_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.classes Module 3 | ----------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.classes 6 | 7 | Classes 8 | ^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.classes 11 | :classes-only: 12 | :toctree: api 13 | :skip: Spam 14 | 15 | Class Inheritance Diagram 16 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 17 | 18 | .. automod-diagram:: sphinx_automodapi.tests.example_module.classes 19 | :private-bases: 20 | :parts: 1 21 | :skip: Spam 22 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_not_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | Egg 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_with_inherit/README.md: -------------------------------------------------------------------------------- 1 | Documenting a module with classes including one that inherits a base class 2 | that isn't in the public API. 3 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_with_inherit/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module.classes 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst: -------------------------------------------------------------------------------- 1 | Egg 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 5 | 6 | .. autoclass:: Egg 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Egg.weight 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~Egg.buy 20 | ~Egg.eat 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoattribute:: weight 25 | 26 | .. rubric:: Methods Documentation 27 | 28 | .. automethod:: buy 29 | .. automethod:: eat 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Spam.rst: -------------------------------------------------------------------------------- 1 | Spam 2 | ==== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 5 | 6 | .. autoclass:: Spam 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.classes Module 3 | ----------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.classes 6 | 7 | Classes 8 | ^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.classes 11 | :classes-only: 12 | :toctree: api 13 | 14 | Class Inheritance Diagram 15 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 16 | 17 | .. automod-diagram:: sphinx_automodapi.tests.example_module.classes 18 | :private-bases: 19 | :parts: 1 20 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | Spam 7 | Egg 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst: -------------------------------------------------------------------------------- 1 | Egg 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 5 | 6 | .. autoclass:: Egg 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Egg.weight 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~Egg.buy 20 | ~Egg.eat 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoproperty:: weight 25 | 26 | .. rubric:: Methods Documentation 27 | 28 | .. automethod:: buy 29 | .. automethod:: eat 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Spam.rst: -------------------------------------------------------------------------------- 1 | Spam 2 | ==== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 5 | 6 | .. autoclass:: Spam 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.classes Module 3 | ----------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.classes 6 | 7 | Classes 8 | ^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.classes 11 | :classes-only: 12 | :toctree: api 13 | 14 | Class Inheritance Diagram 15 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 16 | 17 | .. automod-diagram:: sphinx_automodapi.tests.example_module.classes 18 | :private-bases: 19 | :parts: 1 20 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/classes_with_inherit/output_prop_is_not_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | Spam 7 | Egg 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_headings/README.md: -------------------------------------------------------------------------------- 1 | Documenting a module with functions, and customizing the heading symbols 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_headings/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module.functions 2 | :headings: *&^ 3 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_headings/output/api/sphinx_automodapi.tests.example_module.functions.add.rst: -------------------------------------------------------------------------------- 1 | add 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 5 | 6 | .. autofunction:: add 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_headings/output/api/sphinx_automodapi.tests.example_module.functions.multiply.rst: -------------------------------------------------------------------------------- 1 | multiply 2 | ======== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 5 | 6 | .. autofunction:: multiply 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_headings/output/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.functions Module 3 | ******************************************************* 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.functions 6 | 7 | Functions 8 | &&&&&&&&& 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.functions 11 | :functions-only: 12 | :toctree: api 13 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_headings/output/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | add 7 | subtract 8 | multiply 9 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_noheading/README.md: -------------------------------------------------------------------------------- 1 | Documenting a module with functions, and disabling the top-level headings 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_noheading/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module.functions 2 | :no-heading: 3 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_noheading/output/api/sphinx_automodapi.tests.example_module.functions.add.rst: -------------------------------------------------------------------------------- 1 | add 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 5 | 6 | .. autofunction:: add 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_noheading/output/api/sphinx_automodapi.tests.example_module.functions.multiply.rst: -------------------------------------------------------------------------------- 1 | multiply 2 | ======== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 5 | 6 | .. autofunction:: multiply 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_noheading/output/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | .. automodule:: sphinx_automodapi.tests.example_module.functions 2 | 3 | Functions 4 | ^^^^^^^^^ 5 | 6 | .. automodsumm:: sphinx_automodapi.tests.example_module.functions 7 | :functions-only: 8 | :toctree: api 9 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_noheading/output/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | add 7 | subtract 8 | multiply 9 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_nomaindocstring/README.md: -------------------------------------------------------------------------------- 1 | Documenting a module with functions, excluding the module docstring 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_nomaindocstring/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module.functions 2 | :no-main-docstr: 3 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_nomaindocstring/output/api/sphinx_automodapi.tests.example_module.functions.add.rst: -------------------------------------------------------------------------------- 1 | add 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 5 | 6 | .. autofunction:: add 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_nomaindocstring/output/api/sphinx_automodapi.tests.example_module.functions.multiply.rst: -------------------------------------------------------------------------------- 1 | multiply 2 | ======== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 5 | 6 | .. autofunction:: multiply 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_nomaindocstring/output/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.functions Module 3 | ------------------------------------------------------- 4 | 5 | 6 | 7 | Functions 8 | ^^^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.functions 11 | :functions-only: 12 | :toctree: api 13 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_nomaindocstring/output/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | add 7 | subtract 8 | multiply 9 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_simple/README.md: -------------------------------------------------------------------------------- 1 | Documenting a module with functions 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_simple/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module.functions 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_simple/output/api/sphinx_automodapi.tests.example_module.functions.add.rst: -------------------------------------------------------------------------------- 1 | add 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 5 | 6 | .. autofunction:: add 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_simple/output/api/sphinx_automodapi.tests.example_module.functions.multiply.rst: -------------------------------------------------------------------------------- 1 | multiply 2 | ======== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 5 | 6 | .. autofunction:: multiply 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_simple/output/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.functions Module 3 | ------------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.functions 6 | 7 | Functions 8 | ^^^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.functions 11 | :functions-only: 12 | :toctree: api 13 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/func_simple/output/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | add 7 | subtract 8 | multiply 9 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/inherited_members/README.md: -------------------------------------------------------------------------------- 1 | This example is to make sure that when there are multiple automodapi calls and 2 | only one has inherited-members, it applies only to that one (this is a regression 3 | test for a bug that causes a single inherited-members option to apply to all 4 | subsequent automodapi calls) 5 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/inherited_members/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module.classes 2 | :inherited-members: 3 | 4 | .. automodapi:: sphinx_automodapi.tests.example_module.other_classes 5 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst: -------------------------------------------------------------------------------- 1 | Egg 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 5 | 6 | .. autoclass:: Egg 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Egg.weight 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~Egg.buy 20 | ~Egg.eat 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoattribute:: weight 25 | 26 | .. rubric:: Methods Documentation 27 | 28 | .. automethod:: buy 29 | .. automethod:: eat 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Spam.rst: -------------------------------------------------------------------------------- 1 | Spam 2 | ==== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 5 | 6 | .. autoclass:: Spam 7 | :show-inheritance: 8 | 9 | .. rubric:: Methods Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Spam.buy 14 | ~Spam.eat 15 | 16 | .. rubric:: Methods Documentation 17 | 18 | .. automethod:: buy 19 | .. automethod:: eat 20 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.other_classes.Foo.rst: -------------------------------------------------------------------------------- 1 | Foo 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.other_classes 5 | 6 | .. autoclass:: Foo 7 | :show-inheritance: 8 | 9 | .. rubric:: Methods Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Foo.hmm 14 | 15 | .. rubric:: Methods Documentation 16 | 17 | .. automethod:: hmm 18 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.classes Module 3 | ----------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.classes 6 | 7 | Classes 8 | ^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.classes 11 | :classes-only: 12 | :toctree: api 13 | :inherited-members: 14 | 15 | Class Inheritance Diagram 16 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 17 | 18 | .. automod-diagram:: sphinx_automodapi.tests.example_module.classes 19 | :private-bases: 20 | :parts: 1 21 | 22 | 23 | 24 | sphinx_automodapi.tests.example_module.other_classes Module 25 | ----------------------------------------------------------- 26 | 27 | .. automodule:: sphinx_automodapi.tests.example_module.other_classes 28 | 29 | Classes 30 | ^^^^^^^ 31 | 32 | .. automodsumm:: sphinx_automodapi.tests.example_module.other_classes 33 | :classes-only: 34 | :toctree: api 35 | 36 | Class Inheritance Diagram 37 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 38 | 39 | .. automod-diagram:: sphinx_automodapi.tests.example_module.other_classes 40 | :private-bases: 41 | :parts: 1 42 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/inherited_members/output_prop_is_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | :inherited-members: 6 | 7 | Spam 8 | Egg 9 | .. currentmodule:: sphinx_automodapi.tests.example_module.other_classes 10 | 11 | .. autosummary:: 12 | :toctree: api 13 | 14 | Foo 15 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst: -------------------------------------------------------------------------------- 1 | Egg 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 5 | 6 | .. autoclass:: Egg 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Egg.weight 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~Egg.buy 20 | ~Egg.eat 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoproperty:: weight 25 | 26 | .. rubric:: Methods Documentation 27 | 28 | .. automethod:: buy 29 | .. automethod:: eat 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Spam.rst: -------------------------------------------------------------------------------- 1 | Spam 2 | ==== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 5 | 6 | .. autoclass:: Spam 7 | :show-inheritance: 8 | 9 | .. rubric:: Methods Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Spam.buy 14 | ~Spam.eat 15 | 16 | .. rubric:: Methods Documentation 17 | 18 | .. automethod:: buy 19 | .. automethod:: eat 20 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.other_classes.Foo.rst: -------------------------------------------------------------------------------- 1 | Foo 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.other_classes 5 | 6 | .. autoclass:: Foo 7 | :show-inheritance: 8 | 9 | .. rubric:: Methods Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Foo.hmm 14 | 15 | .. rubric:: Methods Documentation 16 | 17 | .. automethod:: hmm 18 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.classes Module 3 | ----------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.classes 6 | 7 | Classes 8 | ^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.classes 11 | :classes-only: 12 | :toctree: api 13 | :inherited-members: 14 | 15 | Class Inheritance Diagram 16 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 17 | 18 | .. automod-diagram:: sphinx_automodapi.tests.example_module.classes 19 | :private-bases: 20 | :parts: 1 21 | 22 | 23 | 24 | sphinx_automodapi.tests.example_module.other_classes Module 25 | ----------------------------------------------------------- 26 | 27 | .. automodule:: sphinx_automodapi.tests.example_module.other_classes 28 | 29 | Classes 30 | ^^^^^^^ 31 | 32 | .. automodsumm:: sphinx_automodapi.tests.example_module.other_classes 33 | :classes-only: 34 | :toctree: api 35 | 36 | Class Inheritance Diagram 37 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 38 | 39 | .. automod-diagram:: sphinx_automodapi.tests.example_module.other_classes 40 | :private-bases: 41 | :parts: 1 42 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/inherited_members/output_prop_is_not_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | :inherited-members: 6 | 7 | Spam 8 | Egg 9 | .. currentmodule:: sphinx_automodapi.tests.example_module.other_classes 10 | 11 | .. autosummary:: 12 | :toctree: api 13 | 14 | Foo 15 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel/README.md: -------------------------------------------------------------------------------- 1 | Documenting a module with classes and functions that are imported from other 2 | files, and with an inheritance diagram (which then requires the smart_resolver) 3 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Egg.rst: -------------------------------------------------------------------------------- 1 | Egg 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Egg 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Egg.weight 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~Egg.buy 20 | ~Egg.eat 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoattribute:: weight 25 | 26 | .. rubric:: Methods Documentation 27 | 28 | .. automethod:: buy 29 | .. automethod:: eat 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst: -------------------------------------------------------------------------------- 1 | Spam 2 | ==== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Spam 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.add.rst: -------------------------------------------------------------------------------- 1 | add 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autofunction:: add 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.multiply.rst: -------------------------------------------------------------------------------- 1 | multiply 2 | ======== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autofunction:: multiply 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module Package 3 | ---------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module 6 | 7 | Functions 8 | ^^^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module 11 | :functions-only: 12 | :toctree: api 13 | 14 | Classes 15 | ^^^^^^^ 16 | 17 | .. automodsumm:: sphinx_automodapi.tests.example_module 18 | :classes-only: 19 | :toctree: api 20 | 21 | Class Inheritance Diagram 22 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 23 | 24 | .. automod-diagram:: sphinx_automodapi.tests.example_module 25 | :private-bases: 26 | :parts: 1 27 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | add 7 | multiply 8 | subtract 9 | .. currentmodule:: sphinx_automodapi.tests.example_module 10 | 11 | .. autosummary:: 12 | :toctree: api 13 | 14 | Egg 15 | Spam 16 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst: -------------------------------------------------------------------------------- 1 | Egg 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Egg 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Egg.weight 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~Egg.buy 20 | ~Egg.eat 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoproperty:: weight 25 | 26 | .. rubric:: Methods Documentation 27 | 28 | .. automethod:: buy 29 | .. automethod:: eat 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst: -------------------------------------------------------------------------------- 1 | Spam 2 | ==== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Spam 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.add.rst: -------------------------------------------------------------------------------- 1 | add 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autofunction:: add 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.multiply.rst: -------------------------------------------------------------------------------- 1 | multiply 2 | ======== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autofunction:: multiply 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module Package 3 | ---------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module 6 | 7 | Functions 8 | ^^^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module 11 | :functions-only: 12 | :toctree: api 13 | 14 | Classes 15 | ^^^^^^^ 16 | 17 | .. automodsumm:: sphinx_automodapi.tests.example_module 18 | :classes-only: 19 | :toctree: api 20 | 21 | Class Inheritance Diagram 22 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 23 | 24 | .. automod-diagram:: sphinx_automodapi.tests.example_module 25 | :private-bases: 26 | :parts: 1 27 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel/output_prop_is_not_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | add 7 | multiply 8 | subtract 9 | .. currentmodule:: sphinx_automodapi.tests.example_module 10 | 11 | .. autosummary:: 12 | :toctree: api 13 | 14 | Egg 15 | Spam 16 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/README.md: -------------------------------------------------------------------------------- 1 | Documenting a module with classes, functions, and variables that are 2 | imported from other files, and with an inheritance diagram (which then 3 | requires the smart_resolver). 4 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module 2 | :include-all-objects: 3 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Egg.rst: -------------------------------------------------------------------------------- 1 | Egg 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Egg 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Egg.weight 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~Egg.buy 20 | ~Egg.eat 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoattribute:: weight 25 | 26 | .. rubric:: Methods Documentation 27 | 28 | .. automethod:: buy 29 | .. automethod:: eat 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.FUNNY_WALK_STEPS.rst: -------------------------------------------------------------------------------- 1 | FUNNY_WALK_STEPS 2 | ================ 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autodata:: FUNNY_WALK_STEPS 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.PARROT_STATE.rst: -------------------------------------------------------------------------------- 1 | PARROT_STATE 2 | ============ 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autodata:: PARROT_STATE 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst: -------------------------------------------------------------------------------- 1 | Spam 2 | ==== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Spam 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.add.rst: -------------------------------------------------------------------------------- 1 | add 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autofunction:: add 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.multiply.rst: -------------------------------------------------------------------------------- 1 | multiply 2 | ======== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autofunction:: multiply 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module Package 3 | ---------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module 6 | 7 | Functions 8 | ^^^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module 11 | :functions-only: 12 | :toctree: api 13 | 14 | Classes 15 | ^^^^^^^ 16 | 17 | .. automodsumm:: sphinx_automodapi.tests.example_module 18 | :classes-only: 19 | :toctree: api 20 | 21 | Variables 22 | ^^^^^^^^^ 23 | 24 | .. automodsumm:: sphinx_automodapi.tests.example_module 25 | :variables-only: 26 | :toctree: api 27 | 28 | Class Inheritance Diagram 29 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 30 | 31 | .. automod-diagram:: sphinx_automodapi.tests.example_module 32 | :private-bases: 33 | :parts: 1 34 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | add 7 | multiply 8 | subtract 9 | .. currentmodule:: sphinx_automodapi.tests.example_module 10 | 11 | .. autosummary:: 12 | :toctree: api 13 | 14 | Egg 15 | Spam 16 | .. currentmodule:: sphinx_automodapi.tests.example_module 17 | 18 | .. autosummary:: 19 | :toctree: api 20 | 21 | FUNNY_WALK_STEPS 22 | PARROT_STATE 23 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst: -------------------------------------------------------------------------------- 1 | Egg 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Egg 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Egg.weight 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~Egg.buy 20 | ~Egg.eat 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoproperty:: weight 25 | 26 | .. rubric:: Methods Documentation 27 | 28 | .. automethod:: buy 29 | .. automethod:: eat 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.FUNNY_WALK_STEPS.rst: -------------------------------------------------------------------------------- 1 | FUNNY_WALK_STEPS 2 | ================ 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autodata:: FUNNY_WALK_STEPS 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.PARROT_STATE.rst: -------------------------------------------------------------------------------- 1 | PARROT_STATE 2 | ============ 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autodata:: PARROT_STATE 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst: -------------------------------------------------------------------------------- 1 | Spam 2 | ==== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Spam 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.add.rst: -------------------------------------------------------------------------------- 1 | add 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autofunction:: add 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.multiply.rst: -------------------------------------------------------------------------------- 1 | multiply 2 | ======== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autofunction:: multiply 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module Package 3 | ---------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module 6 | 7 | Functions 8 | ^^^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module 11 | :functions-only: 12 | :toctree: api 13 | 14 | Classes 15 | ^^^^^^^ 16 | 17 | .. automodsumm:: sphinx_automodapi.tests.example_module 18 | :classes-only: 19 | :toctree: api 20 | 21 | Variables 22 | ^^^^^^^^^ 23 | 24 | .. automodsumm:: sphinx_automodapi.tests.example_module 25 | :variables-only: 26 | :toctree: api 27 | 28 | Class Inheritance Diagram 29 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 30 | 31 | .. automod-diagram:: sphinx_automodapi.tests.example_module 32 | :private-bases: 33 | :parts: 1 34 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output_prop_is_not_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | add 7 | multiply 8 | subtract 9 | .. currentmodule:: sphinx_automodapi.tests.example_module 10 | 11 | .. autosummary:: 12 | :toctree: api 13 | 14 | Egg 15 | Spam 16 | .. currentmodule:: sphinx_automodapi.tests.example_module 17 | 18 | .. autosummary:: 19 | :toctree: api 20 | 21 | FUNNY_WALK_STEPS 22 | PARROT_STATE 23 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/README.md: -------------------------------------------------------------------------------- 1 | Documenting a module with classes and functions that are imported from 2 | other files 3 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module 2 | :no-inheritance-diagram: 3 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Egg.rst: -------------------------------------------------------------------------------- 1 | Egg 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Egg 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Egg.weight 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~Egg.buy 20 | ~Egg.eat 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoattribute:: weight 25 | 26 | .. rubric:: Methods Documentation 27 | 28 | .. automethod:: buy 29 | .. automethod:: eat 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst: -------------------------------------------------------------------------------- 1 | Spam 2 | ==== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Spam 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.add.rst: -------------------------------------------------------------------------------- 1 | add 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autofunction:: add 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.multiply.rst: -------------------------------------------------------------------------------- 1 | multiply 2 | ======== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autofunction:: multiply 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module Package 3 | ---------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module 6 | 7 | Functions 8 | ^^^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module 11 | :functions-only: 12 | :toctree: api 13 | 14 | Classes 15 | ^^^^^^^ 16 | 17 | .. automodsumm:: sphinx_automodapi.tests.example_module 18 | :classes-only: 19 | :toctree: api 20 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | add 7 | multiply 8 | subtract 9 | .. currentmodule:: sphinx_automodapi.tests.example_module 10 | 11 | .. autosummary:: 12 | :toctree: api 13 | 14 | Egg 15 | Spam 16 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst: -------------------------------------------------------------------------------- 1 | Egg 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Egg 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~Egg.weight 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~Egg.buy 20 | ~Egg.eat 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoproperty:: weight 25 | 26 | .. rubric:: Methods Documentation 27 | 28 | .. automethod:: buy 29 | .. automethod:: eat 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst: -------------------------------------------------------------------------------- 1 | Spam 2 | ==== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autoclass:: Spam 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.add.rst: -------------------------------------------------------------------------------- 1 | add 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autofunction:: add 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.multiply.rst: -------------------------------------------------------------------------------- 1 | multiply 2 | ======== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module 5 | 6 | .. autofunction:: multiply 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module Package 3 | ---------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module 6 | 7 | Functions 8 | ^^^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module 11 | :functions-only: 12 | :toctree: api 13 | 14 | Classes 15 | ^^^^^^^ 16 | 17 | .. automodsumm:: sphinx_automodapi.tests.example_module 18 | :classes-only: 19 | :toctree: api 20 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/mixed_toplevel_nodiagram/output_prop_is_not_attr/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | add 7 | multiply 8 | subtract 9 | .. currentmodule:: sphinx_automodapi.tests.example_module 10 | 11 | .. autosummary:: 12 | :toctree: api 13 | 14 | Egg 15 | Spam 16 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/nested/README.md: -------------------------------------------------------------------------------- 1 | Documenting a sub-module which is at a different level in the docs than the API folder 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/nested/input/index.rst: -------------------------------------------------------------------------------- 1 | .. toctree:: 2 | :maxdepth: 1 3 | 4 | tests/example_module/index 5 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/nested/input/tests/example_module/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module.functions_with_ref 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/nested/input/tests/example_module/references.txt: -------------------------------------------------------------------------------- 1 | .. _astropy: http://www.astropy.org 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/nested/output/api/sphinx_automodapi.tests.example_module.functions_with_ref.add.rst: -------------------------------------------------------------------------------- 1 | .. include:: ../tests/example_module/references.txt 2 | 3 | add 4 | === 5 | 6 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions_with_ref 7 | 8 | .. autofunction:: add 9 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/nested/output/api/sphinx_automodapi.tests.example_module.functions_with_ref.multiply.rst: -------------------------------------------------------------------------------- 1 | .. include:: ../tests/example_module/references.txt 2 | 3 | multiply 4 | ======== 5 | 6 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions_with_ref 7 | 8 | .. autofunction:: multiply 9 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/nested/output/tests/example_module/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.functions_with_ref Module 3 | ---------------------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.functions_with_ref 6 | 7 | Functions 8 | ^^^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.functions_with_ref 11 | :functions-only: 12 | :toctree: ../../api 13 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/nested/output/tests/example_module/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions_with_ref 2 | 3 | .. autosummary:: 4 | :toctree: ../../api 5 | 6 | add 7 | multiply 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/non_ascii/README.md: -------------------------------------------------------------------------------- 1 | Non-ASCII characters 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/non_ascii/input/index.rst: -------------------------------------------------------------------------------- 1 | Ceçi est un exemple qui inclus des charactères non-ASCII 2 | 3 | .. automodapi:: sphinx_automodapi.tests.example_module.functions 4 | .. automodapi:: sphinx_automodapi.tests.example_module.nonascii 5 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/non_ascii/output/api/sphinx_automodapi.tests.example_module.functions.add.rst: -------------------------------------------------------------------------------- 1 | add 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 5 | 6 | .. autofunction:: add 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/non_ascii/output/api/sphinx_automodapi.tests.example_module.functions.multiply.rst: -------------------------------------------------------------------------------- 1 | multiply 2 | ======== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 5 | 6 | .. autofunction:: multiply 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/non_ascii/output/api/sphinx_automodapi.tests.example_module.nonascii.NonAsciiÄöüßő.rst: -------------------------------------------------------------------------------- 1 | NonAsciiÄöüßő 2 | ============= 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.nonascii 5 | 6 | .. autoclass:: NonAsciiÄöüßő 7 | :show-inheritance: 8 | 9 | .. rubric:: Methods Summary 10 | 11 | .. autosummary:: 12 | 13 | ~NonAsciiÄöüßő.get_ß 14 | ~NonAsciiÄöüßő.get_äöü 15 | 16 | .. rubric:: Methods Documentation 17 | 18 | .. automethod:: get_ß 19 | .. automethod:: get_äöü 20 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/non_ascii/output/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | Ceçi est un exemple qui inclus des charactères non-ASCII 2 | 3 | 4 | sphinx_automodapi.tests.example_module.functions Module 5 | ------------------------------------------------------- 6 | 7 | .. automodule:: sphinx_automodapi.tests.example_module.functions 8 | 9 | Functions 10 | ^^^^^^^^^ 11 | 12 | .. automodsumm:: sphinx_automodapi.tests.example_module.functions 13 | :functions-only: 14 | :toctree: api 15 | 16 | 17 | sphinx_automodapi.tests.example_module.nonascii Module 18 | ------------------------------------------------------ 19 | 20 | .. automodule:: sphinx_automodapi.tests.example_module.nonascii 21 | 22 | Classes 23 | ^^^^^^^ 24 | 25 | .. automodsumm:: sphinx_automodapi.tests.example_module.nonascii 26 | :classes-only: 27 | :toctree: api 28 | 29 | Class Inheritance Diagram 30 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 31 | 32 | .. automod-diagram:: sphinx_automodapi.tests.example_module.nonascii 33 | :private-bases: 34 | :parts: 1 35 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/non_ascii/output/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | add 7 | subtract 8 | multiply 9 | .. currentmodule:: sphinx_automodapi.tests.example_module.nonascii 10 | 11 | .. autosummary:: 12 | :toctree: api 13 | 14 | NonAsciiÄöüßő 15 | 16 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/public_from_private/README.md: -------------------------------------------------------------------------------- 1 | Importing a class from a private submodule to a public submodule 2 | at the same level of hierarchy in the module. 3 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/public_from_private/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module.public 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Camelot.rst: -------------------------------------------------------------------------------- 1 | Camelot 2 | ======= 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.public 5 | 6 | .. autoclass:: Camelot 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Spam.rst: -------------------------------------------------------------------------------- 1 | Spam 2 | ==== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.public 5 | 6 | .. autoclass:: Spam 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.public Module 3 | ---------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.public 6 | 7 | Classes 8 | ^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.public 11 | :classes-only: 12 | :toctree: api 13 | 14 | Class Inheritance Diagram 15 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 16 | 17 | .. automod-diagram:: sphinx_automodapi.tests.example_module.public 18 | :private-bases: 19 | :parts: 1 20 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.public 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | Camelot 7 | Spam 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/slots/README.md: -------------------------------------------------------------------------------- 1 | Test classes that put attributes in `__slots__`. -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/slots/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module.slots 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/slots/output/api/sphinx_automodapi.tests.example_module.slots.DerivedParam.rst: -------------------------------------------------------------------------------- 1 | DerivedParam 2 | ============ 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.slots 5 | 6 | .. autoclass:: DerivedParam 7 | :show-inheritance: 8 | 9 | .. rubric:: Methods Summary 10 | 11 | .. autosummary:: 12 | 13 | ~DerivedParam.derived_from_slot_class_method 14 | 15 | .. rubric:: Methods Documentation 16 | 17 | .. automethod:: derived_from_slot_class_method 18 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/slots/output/api/sphinx_automodapi.tests.example_module.slots.DerivedSlotParam.rst: -------------------------------------------------------------------------------- 1 | DerivedSlotParam 2 | ================ 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.slots 5 | 6 | .. autoclass:: DerivedSlotParam 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~DerivedSlotParam.extra_attr 14 | 15 | .. rubric:: Methods Summary 16 | 17 | .. autosummary:: 18 | 19 | ~DerivedSlotParam.derived_from_slot_class_method 20 | 21 | .. rubric:: Attributes Documentation 22 | 23 | .. autoattribute:: extra_attr 24 | 25 | .. rubric:: Methods Documentation 26 | 27 | .. automethod:: derived_from_slot_class_method 28 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/slots/output/api/sphinx_automodapi.tests.example_module.slots.SlotDict.rst: -------------------------------------------------------------------------------- 1 | SlotDict 2 | ======== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.slots 5 | 6 | .. autoclass:: SlotDict 7 | :show-inheritance: 8 | 9 | .. rubric:: Attributes Summary 10 | 11 | .. autosummary:: 12 | 13 | ~SlotDict.class_attr 14 | ~SlotDict.instance_attr 15 | 16 | .. rubric:: Methods Summary 17 | 18 | .. autosummary:: 19 | 20 | ~SlotDict.my_method 21 | 22 | .. rubric:: Attributes Documentation 23 | 24 | .. autoattribute:: class_attr 25 | .. autoattribute:: instance_attr 26 | 27 | .. rubric:: Methods Documentation 28 | 29 | .. automethod:: my_method 30 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/slots/output/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.slots Module 3 | --------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.slots 6 | 7 | Classes 8 | ^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.slots 11 | :classes-only: 12 | :toctree: api 13 | 14 | Class Inheritance Diagram 15 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 16 | 17 | .. automod-diagram:: sphinx_automodapi.tests.example_module.slots 18 | :private-bases: 19 | :parts: 1 20 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/slots/output/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.slots 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | SlotDict 7 | DerivedParam 8 | DerivedSlotParam 9 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/source_dir/README.md: -------------------------------------------------------------------------------- 1 | Documentation is inside a source directory 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/source_dir/input/src/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module.functions 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/source_dir/output/src/api/sphinx_automodapi.tests.example_module.functions.add.rst: -------------------------------------------------------------------------------- 1 | add 2 | === 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 5 | 6 | .. autofunction:: add 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/source_dir/output/src/api/sphinx_automodapi.tests.example_module.functions.multiply.rst: -------------------------------------------------------------------------------- 1 | multiply 2 | ======== 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 5 | 6 | .. autofunction:: multiply 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/source_dir/output/src/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.functions Module 3 | ------------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.functions 6 | 7 | Functions 8 | ^^^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.functions 11 | :functions-only: 12 | :toctree: api 13 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/source_dir/output/src/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.functions 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | add 7 | subtract 8 | multiply 9 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/variables/README.md: -------------------------------------------------------------------------------- 1 | Documenting a module with global variables 2 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/variables/input/index.rst: -------------------------------------------------------------------------------- 1 | .. automodapi:: sphinx_automodapi.tests.example_module.variables 2 | :include-all-objects: 3 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/variables/output/api/sphinx_automodapi.tests.example_module.variables.FUNNY_WALK_STEPS.rst: -------------------------------------------------------------------------------- 1 | FUNNY_WALK_STEPS 2 | ================ 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.variables 5 | 6 | .. autodata:: FUNNY_WALK_STEPS 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/variables/output/api/sphinx_automodapi.tests.example_module.variables.PARROT_STATE.rst: -------------------------------------------------------------------------------- 1 | PARROT_STATE 2 | ============ 3 | 4 | .. currentmodule:: sphinx_automodapi.tests.example_module.variables 5 | 6 | .. autodata:: PARROT_STATE 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/variables/output/index.rst.automodapi: -------------------------------------------------------------------------------- 1 | 2 | sphinx_automodapi.tests.example_module.variables Module 3 | ------------------------------------------------------- 4 | 5 | .. automodule:: sphinx_automodapi.tests.example_module.variables 6 | 7 | Variables 8 | ^^^^^^^^^ 9 | 10 | .. automodsumm:: sphinx_automodapi.tests.example_module.variables 11 | :variables-only: 12 | :toctree: api 13 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/cases/variables/output/index.rst.automodsumm: -------------------------------------------------------------------------------- 1 | .. currentmodule:: sphinx_automodapi.tests.example_module.variables 2 | 3 | .. autosummary:: 4 | :toctree: api 5 | 6 | PARROT_STATE 7 | FUNNY_WALK_STEPS 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/duplicated_warning/__init__.py: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/astropy/sphinx-automodapi/a6b6eb30736e870745ffd07c0d231d8d21fb4163/sphinx_automodapi/tests/duplicated_warning/__init__.py -------------------------------------------------------------------------------- /sphinx_automodapi/tests/duplicated_warning/docs/conf.py: -------------------------------------------------------------------------------- 1 | project = 'duplicated' 2 | copyright = '2022, Maximilian Linhoff' 3 | author = 'Maximilian Linhoff' 4 | release = '0.1' 5 | 6 | 7 | extensions = [ 8 | "sphinx_automodapi.automodapi", 9 | ] 10 | 11 | html_theme = 'alabaster' 12 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/duplicated_warning/docs/foo.rst: -------------------------------------------------------------------------------- 1 | Foo Submodule 2 | ============= 3 | 4 | 5 | API Reference 6 | ------------- 7 | 8 | .. automodapi:: sphinx_automodapi.tests.duplicated_warning.duplicated.foo 9 | :noindex: 10 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/duplicated_warning/docs/index.rst: -------------------------------------------------------------------------------- 1 | .. duplicated documentation master file, created by 2 | sphinx-quickstart on Tue Mar 29 17:11:23 2022. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | Welcome to duplicated's documentation! 7 | ====================================== 8 | 9 | .. toctree:: 10 | :maxdepth: 2 11 | :caption: Contents: 12 | 13 | foo 14 | 15 | 16 | API Reference 17 | ------------- 18 | 19 | .. automodapi:: sphinx_automodapi.tests.duplicated_warning.duplicated 20 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/duplicated_warning/duplicated/__init__.py: -------------------------------------------------------------------------------- 1 | from .foo import Foo 2 | 3 | 4 | __all__ = [ 5 | 'Foo', 6 | ] 7 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/duplicated_warning/duplicated/foo/__init__.py: -------------------------------------------------------------------------------- 1 | from .foo import Foo 2 | 3 | __all__ = [ 4 | "Foo", 5 | ] 6 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/duplicated_warning/duplicated/foo/foo.py: -------------------------------------------------------------------------------- 1 | __all__ = [ 2 | 'Foo', 3 | 'Bar', 4 | 'baz', 5 | ] 6 | 7 | 8 | class Foo: 9 | '''Awesome Foo class''' 10 | 11 | 12 | class Bar: 13 | '''Awesome Bar class''' 14 | 15 | 16 | def baz(): 17 | '''Awesome baz function''' 18 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/__init__.py: -------------------------------------------------------------------------------- 1 | from .classes import * # noqa 2 | from .functions import * # noqa 3 | from .variables import * # noqa 4 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/_private.py: -------------------------------------------------------------------------------- 1 | class Camelot: 2 | """ 3 | It's a silly place anyway 4 | """ 5 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/abstract_classes.py: -------------------------------------------------------------------------------- 1 | from collections.abc import Sequence 2 | 3 | __all__ = ['SequenceSubclass'] 4 | 5 | 6 | class SequenceSubclass(Sequence): 7 | """ 8 | Inherits from an ABC. 9 | """ 10 | 11 | def __init__(self): 12 | self._items = [] 13 | 14 | def __len__(self): 15 | """ 16 | Must be defined for the collections.abc.Sequence base class. 17 | """ 18 | return len(self._items) 19 | 20 | def __getitem__(self, key): 21 | """ 22 | Must be defined for the collections.abc.Sequence base class. 23 | """ 24 | return self._items[key] 25 | 26 | def my_method(self, parameter): 27 | """ 28 | An example method. 29 | """ 30 | pass 31 | 32 | @property 33 | def my_property(self): 34 | """ 35 | An example property. 36 | """ 37 | return 42 38 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/attribute_class.py: -------------------------------------------------------------------------------- 1 | class ClassWithAttribute(object): 2 | """A class with an attribute.""" 3 | my_attribute = 1 4 | 5 | def my_method(self): 6 | """A method.""" 7 | pass 8 | 9 | @property 10 | def my_property(self): 11 | """A property.""" 12 | return 1 13 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/classes.py: -------------------------------------------------------------------------------- 1 | __all__ = ['Spam', 'Egg'] 2 | 3 | 4 | class BaseSpam(object): 5 | """ 6 | Base class for Spam 7 | """ 8 | 9 | def eat(self, time): 10 | """ 11 | Eat some spam in the required time. 12 | """ 13 | pass 14 | 15 | def buy(self, price): 16 | """ 17 | Buy some MOAR spam. 18 | """ 19 | pass 20 | 21 | 22 | class Spam(BaseSpam): 23 | """ 24 | The main spam 25 | """ 26 | pass 27 | 28 | 29 | class Egg(object): 30 | """ 31 | An egg (no inheritance) 32 | """ 33 | 34 | def eat(self, time): 35 | """ 36 | Eat some egg in the required time. 37 | """ 38 | pass 39 | 40 | def buy(self, price): 41 | """ 42 | Buy some MOAR egg. 43 | """ 44 | pass 45 | 46 | @property 47 | def weight(self): 48 | """ 49 | The weight of an egg 50 | """ 51 | return 0 52 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/functions.py: -------------------------------------------------------------------------------- 1 | """ 2 | A collection of useful functions 3 | """ 4 | 5 | __all__ = ['add', 'subtract', 'multiply'] 6 | 7 | 8 | def add(a, b): 9 | """ 10 | Add two numbers 11 | """ 12 | return a + b 13 | 14 | 15 | def subtract(a, b): 16 | """ 17 | Subtract two numbers 18 | """ 19 | return a - b 20 | 21 | 22 | def multiply(c, d): 23 | """ 24 | Multiply two numbers 25 | """ 26 | return c * d 27 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/functions_with_ref.py: -------------------------------------------------------------------------------- 1 | """ 2 | A collection of useful functions 3 | """ 4 | 5 | __all__ = ['add', 'multiply'] 6 | 7 | 8 | def add(a, b): 9 | """ 10 | Add two numbers 11 | 12 | Here is an example reference: astropy_ 13 | """ 14 | return a + b 15 | 16 | 17 | def multiply(c, d): 18 | """ 19 | Multiply two numbers 20 | 21 | Here is an example reference: astropy_ 22 | """ 23 | return c * d 24 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/mixed.py: -------------------------------------------------------------------------------- 1 | """ 2 | A collection of useful classes and functions 3 | """ 4 | 5 | __all__ = ['add', 'MixedSpam'] 6 | 7 | 8 | def add(a, b): 9 | """ 10 | Add two numbers 11 | """ 12 | return a + b 13 | 14 | 15 | class MixedSpam(object): 16 | """ 17 | Special spam 18 | """ 19 | 20 | def eat(self, time): 21 | """ 22 | Eat special spam in the required time. 23 | """ 24 | pass 25 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/noall.py: -------------------------------------------------------------------------------- 1 | """ 2 | A collection of useful classes and functions 3 | """ 4 | from collections import OrderedDict 5 | 6 | 7 | def add(a, b): 8 | """ 9 | Add two numbers 10 | """ 11 | return a + b 12 | 13 | 14 | class MixedSpam(OrderedDict): 15 | """ 16 | Special spam 17 | """ 18 | 19 | def eat(self, time): 20 | """ 21 | Eat special spam in the required time. 22 | """ 23 | pass 24 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/nonascii.py: -------------------------------------------------------------------------------- 1 | __all__ = ['NonAsciiÄöüßő'] 2 | 3 | 4 | class NonAsciiÄöüßő(object): 5 | def get_äöü(self): 6 | """ 7 | Return a string with common umlauts like äöüß 8 | """ 9 | return 'äöü' 10 | 11 | def get_ß(self): 12 | """ 13 | Return a string with the eszett symbol 14 | """ 15 | return 'ß' 16 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/other_classes.py: -------------------------------------------------------------------------------- 1 | __all__ = ['Foo'] 2 | 3 | 4 | class BaseFoo(object): 5 | """ 6 | Base class for Foo 7 | """ 8 | 9 | def bar(self, time): 10 | """ 11 | Eat some spam in the required time. 12 | """ 13 | pass 14 | 15 | 16 | class Foo(BaseFoo): 17 | """ 18 | The main foo 19 | """ 20 | def hmm(self): 21 | pass 22 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/public.py: -------------------------------------------------------------------------------- 1 | from ._private import Camelot 2 | from .classes import Spam 3 | 4 | __all__ = [ 5 | 'Camelot', 6 | 'Spam' 7 | ] 8 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/slots.py: -------------------------------------------------------------------------------- 1 | """Test classes containing __slots__ 2 | 3 | Instance attributes named in ``__slots__`` can be introspected and are listed 4 | in the Attributes section of the class documentation. Class attributes are 5 | listed in the same section of the generated docs so docstrings should be used 6 | to distinguish class attributes vs instance attributes. Regular instance 7 | attributes are dynamically inserted into ``__dict__`` and cannot be reliably 8 | introspected so they're not included in the documentation. 9 | """ 10 | from __future__ import annotations 11 | 12 | __all__ = ['SlotDict', 'DerivedParam', 'DerivedSlotParam',] 13 | 14 | 15 | class SlotDict(object): 16 | """ 17 | A class that uses __slots__ and __dict__ for its attribute namespace. 18 | """ 19 | __slots__ = { 20 | "instance_attr": "instance attribute docstring can be added here", 21 | "__dict__": None, # Allows additional instance attributes to be added 22 | } 23 | 24 | class_attr = "class attribute value" 25 | """(class attr) this is a class attribute.""" 26 | 27 | def __init__(self, param: str, other_param: str): 28 | """ 29 | Initializes a SlotDict object. 30 | 31 | Parameters 32 | ---------- 33 | param : str 34 | A parameter 35 | other_param : str 36 | Another parameter 37 | """ 38 | 39 | self.instance_attr = param 40 | """Instance attributes declared in slots can also define their docstring 41 | here 42 | """ 43 | 44 | if other_param is not None: 45 | self.other_attr = other_param 46 | """This instance attribute is dynamic (not declared in a slot) so 47 | it's not included in the docs 48 | """ 49 | 50 | def my_method(self): 51 | """ 52 | Prints the SlotDict parameters. 53 | """ 54 | print(f"instance_attr: {self.instance_attr}") 55 | print(f"other_attr: {self.other_attr}") 56 | 57 | 58 | class DerivedParam(SlotDict): 59 | """ 60 | Extends SlotDict by adding an extra parameter 61 | """ 62 | def __init__(self, param: str, other_param: str, extra_param: str): 63 | """ 64 | Initializes a DerivedParam object. 65 | 66 | Parameters 67 | ---------- 68 | param : str 69 | A parameter 70 | other_param : str 71 | Another parameter 72 | extra_param : str 73 | An extra parameter 74 | """ 75 | super(DerivedParam, self).__init__(param, other_param) 76 | self.extra_attr = extra_param 77 | 78 | def derived_from_slot_class_method(self): 79 | """ 80 | Prints the DerivedParam parameters. 81 | """ 82 | print(f"instance_attr: {self.instance_attr}") 83 | print(f"other_attr: {self.other_attr}") 84 | print(f"extra_attr: {self.extra_attr}") 85 | 86 | 87 | class DerivedSlotParam(SlotDict): 88 | """ 89 | Extends SlotDict by adding a slot parameter 90 | """ 91 | 92 | __slots__ = ('extra_attr',) 93 | 94 | def __init__(self, param: str, other_param: str, extra_param: str): 95 | """ 96 | Initializes a DerivedSlotParam object. 97 | 98 | Parameters 99 | ---------- 100 | param : str 101 | A parameter 102 | other_param : str 103 | Another parameter 104 | extra_param : str 105 | An extra parameter 106 | """ 107 | super(DerivedSlotParam, self).__init__(param, other_param) 108 | self.extra_attr = extra_param 109 | 110 | def derived_from_slot_class_method(self): 111 | """ 112 | Prints the DerivedSlotParam parameters. 113 | """ 114 | print(f"instance_attr: {self.instance_attr}") 115 | print(f"other_attr: {self.other_attr}") 116 | print(f"extra_attr: {self.extra_attr}") 117 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/stdlib.py: -------------------------------------------------------------------------------- 1 | """ 2 | A module that imports objects from the standard library. 3 | """ 4 | from pathlib import Path 5 | from datetime import time 6 | 7 | 8 | __all__ = ['Path', 'time', 'add'] 9 | 10 | 11 | def add(a, b): 12 | """ 13 | Add two numbers 14 | """ 15 | return a + b 16 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/example_module/variables.py: -------------------------------------------------------------------------------- 1 | """ 2 | A collection of useful variables. 3 | """ 4 | 5 | __all__ = ['PARROT_STATE', 'FUNNY_WALK_STEPS'] 6 | 7 | 8 | PARROT_STATE = 'dead' 9 | """The global state of the parrot.""" 10 | 11 | FUNNY_WALK_STEPS = [['left', 'right'], 12 | ['left', 'jump', 'right', 'jump'], 13 | ['swim']] 14 | """List of different possible walk. 15 | 16 | Each item contains a list of steps. 17 | """ 18 | 19 | # A variable not in __all__ should not be propagated. 20 | NOTHING_HAPPENS = 0 21 | 22 | # Even if it has a docstring 23 | REALLY_NOTHING = 1 24 | """Really nothing.""" 25 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/helpers.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # Licensed under a 3-clause BSD style license - see LICENSE.rst 3 | 4 | import os 5 | from copy import deepcopy 6 | 7 | from sphinx.cmd.build import build_main 8 | 9 | from . import cython_testpackage # noqa 10 | 11 | __all__ = ['write_conf', 'run_sphinx_in_tmpdir'] 12 | 13 | 14 | intersphinx_mapping = { 15 | 'python': ('https://docs.python.org/3/', None) 16 | } 17 | 18 | DEFAULT_CONF = {'source_suffix': '.rst', 19 | 'master_doc': 'index', 20 | 'nitpicky': True, 21 | 'extensions': ['sphinx.ext.intersphinx', 'sphinx_automodapi.automodapi'], 22 | 'suppress_warnings': ['app.add_directive', 'app.add_node'], 23 | 'intersphinx_mapping': intersphinx_mapping, 24 | 'automodapi_toctreedirnm': 'api', 25 | 'automodapi_writereprocessed': True, 26 | 'automodapi_inheritance_diagram': True, 27 | 'automodsumm_writereprocessed': True} 28 | 29 | 30 | def write_conf(filename, conf): 31 | with open(filename, 'w') as f: 32 | for key, value in conf.items(): 33 | f.write("{0} = {1}\n".format(key, repr(conf[key]))) 34 | 35 | 36 | def run_sphinx_in_tmpdir(tmpdir, additional_conf={}, expect_error=False): 37 | 38 | start_dir = os.path.abspath('.') 39 | 40 | conf = deepcopy(DEFAULT_CONF) 41 | conf.update(additional_conf) 42 | 43 | write_conf(tmpdir.join('conf.py').strpath, conf) 44 | 45 | argv = ['-W', '-b', 'html', '.', '_build/html'] 46 | 47 | try: 48 | os.chdir(tmpdir.strpath) 49 | status = build_main(argv=argv) 50 | finally: 51 | os.chdir(start_dir) 52 | 53 | if expect_error: 54 | assert status != 0 55 | else: 56 | assert status == 0 57 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/test_autodoc_enhancements.py: -------------------------------------------------------------------------------- 1 | from textwrap import dedent 2 | 3 | import pytest 4 | 5 | from ..autodoc_enhancements import type_object_attrgetter 6 | 7 | 8 | # Define test classes outside the class; otherwise there is flakiness with the 9 | # details of how exec works on different Python versions 10 | class Meta(type): 11 | @property 12 | def foo(cls): 13 | return 'foo' 14 | 15 | 16 | class MyClass(metaclass=Meta): 17 | @property 18 | def foo(self): 19 | """Docstring for MyClass.foo property.""" 20 | return 'myfoo' 21 | 22 | 23 | def test_type_attrgetter(): 24 | """ 25 | This test essentially reproduces the docstring for 26 | `type_object_attrgetter`. 27 | 28 | Sphinx itself tests the custom attrgetter feature; see: 29 | https://bitbucket.org/birkenfeld/sphinx/src/40bd03003ac6fe274ccf3c80d7727509e00a69ea/tests/test_autodoc.py?at=default#cl-502 30 | so rather than a full end-to-end functional test it's simple enough to just 31 | test that this function does what it needs to do. 32 | """ 33 | 34 | assert getattr(MyClass, 'foo') == 'foo' 35 | obj = type_object_attrgetter(MyClass, 'foo') 36 | assert isinstance(obj, property) 37 | assert obj.__doc__ == 'Docstring for MyClass.foo property.' 38 | 39 | with pytest.raises(AttributeError): 40 | type_object_attrgetter(MyClass, 'susy') 41 | 42 | assert type_object_attrgetter(MyClass, 'susy', 'default') == 'default' 43 | assert type_object_attrgetter(MyClass, '__dict__') == MyClass.__dict__ 44 | 45 | 46 | def test_type_attrgetter_for_dataclass(): 47 | """ 48 | This tests the attribute getter for non-default dataclass fields 49 | """ 50 | import dataclasses 51 | 52 | @dataclasses.dataclass 53 | class MyDataclass: 54 | foo: int 55 | bar: str = "bar value" 56 | 57 | with pytest.raises(AttributeError): 58 | getattr(MyDataclass, 'foo') 59 | assert type_object_attrgetter(MyDataclass, 'foo') == dataclasses.MISSING 60 | assert getattr(MyDataclass, 'bar') == 'bar value' 61 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/test_automodapi.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # Licensed under a 3-clause BSD style license - see LICENSE.rst 3 | 4 | from copy import copy 5 | 6 | import pytest 7 | from docutils.parsers.rst import directives, roles 8 | 9 | from . import cython_testpackage # noqa 10 | from .helpers import run_sphinx_in_tmpdir 11 | 12 | 13 | def setup_function(func): 14 | # This can be replaced with the docutils_namespace context manager once 15 | # it is in a stable release of Sphinx 16 | func._directives = copy(directives._directives) 17 | func._roles = copy(roles._roles) 18 | 19 | 20 | def teardown_function(func): 21 | directives._directives = func._directives 22 | roles._roles = func._roles 23 | 24 | 25 | am_replacer_str = """ 26 | This comes before 27 | 28 | .. automodapi:: sphinx_automodapi.tests.example_module.mixed 29 | {options} 30 | 31 | This comes after 32 | """ 33 | 34 | am_replacer_basic_expected = """ 35 | This comes before 36 | 37 | 38 | sphinx_automodapi.tests.example_module.mixed Module 39 | --------------------------------------------------- 40 | 41 | .. automodule:: sphinx_automodapi.tests.example_module.mixed 42 | 43 | Functions 44 | ^^^^^^^^^ 45 | 46 | .. automodsumm:: sphinx_automodapi.tests.example_module.mixed 47 | :functions-only: 48 | :toctree: api 49 | 50 | Classes 51 | ^^^^^^^ 52 | 53 | .. automodsumm:: sphinx_automodapi.tests.example_module.mixed 54 | :classes-only: 55 | :toctree: api 56 | 57 | Class Inheritance Diagram 58 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 59 | 60 | .. automod-diagram:: sphinx_automodapi.tests.example_module.mixed 61 | :private-bases: 62 | :parts: 1 63 | 64 | This comes after 65 | """ 66 | 67 | 68 | def test_am_replacer_basic(tmpdir): 69 | """ 70 | Tests replacing an ".. automodapi::" with the automodapi no-option 71 | template 72 | """ 73 | 74 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 75 | f.write(am_replacer_str.format(options='')) 76 | 77 | run_sphinx_in_tmpdir(tmpdir) 78 | 79 | with open(tmpdir.join('index.rst.automodapi').strpath) as f: 80 | result = f.read() 81 | 82 | assert result == am_replacer_basic_expected 83 | 84 | 85 | am_replacer_repr_str = u""" 86 | This comes before with spéciàl çhars 87 | 88 | .. automodapi:: sphinx_automodapi.tests.example_module.mixed 89 | {options} 90 | 91 | This comes after 92 | """ 93 | 94 | 95 | @pytest.mark.parametrize('writereprocessed', [False, True]) 96 | def test_am_replacer_writereprocessed(tmpdir, writereprocessed): 97 | """ 98 | Tests the automodapi_writereprocessed option 99 | """ 100 | 101 | with open(tmpdir.join('index.rst').strpath, 'w', encoding='utf-8') as f: 102 | f.write(am_replacer_repr_str.format(options='')) 103 | 104 | run_sphinx_in_tmpdir(tmpdir, additional_conf={'automodapi_writereprocessed': writereprocessed}) 105 | 106 | assert tmpdir.join('index.rst.automodapi').isfile() is writereprocessed 107 | 108 | 109 | am_replacer_noinh_expected = """ 110 | This comes before 111 | 112 | 113 | sphinx_automodapi.tests.example_module.mixed Module 114 | --------------------------------------------------- 115 | 116 | .. automodule:: sphinx_automodapi.tests.example_module.mixed 117 | 118 | Functions 119 | ^^^^^^^^^ 120 | 121 | .. automodsumm:: sphinx_automodapi.tests.example_module.mixed 122 | :functions-only: 123 | :toctree: api 124 | 125 | Classes 126 | ^^^^^^^ 127 | 128 | .. automodsumm:: sphinx_automodapi.tests.example_module.mixed 129 | :classes-only: 130 | :toctree: api 131 | 132 | 133 | This comes after 134 | """.format(empty='') 135 | 136 | 137 | def test_am_replacer_noinh(tmpdir): 138 | """ 139 | Tests replacing an ".. automodapi::" with no-inheritance-diagram 140 | option 141 | """ 142 | 143 | ops = ['', ':no-inheritance-diagram:'] 144 | ostr = '\n '.join(ops) 145 | 146 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 147 | f.write(am_replacer_str.format(options=ostr)) 148 | 149 | run_sphinx_in_tmpdir(tmpdir) 150 | 151 | with open(tmpdir.join('index.rst.automodapi').strpath) as f: 152 | result = f.read() 153 | 154 | assert result == am_replacer_noinh_expected 155 | 156 | 157 | am_replacer_titleandhdrs_expected = """ 158 | This comes before 159 | 160 | 161 | sphinx_automodapi.tests.example_module.mixed Module 162 | &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&& 163 | 164 | .. automodule:: sphinx_automodapi.tests.example_module.mixed 165 | 166 | Functions 167 | ********* 168 | 169 | .. automodsumm:: sphinx_automodapi.tests.example_module.mixed 170 | :functions-only: 171 | :toctree: api 172 | 173 | Classes 174 | ******* 175 | 176 | .. automodsumm:: sphinx_automodapi.tests.example_module.mixed 177 | :classes-only: 178 | :toctree: api 179 | 180 | Class Inheritance Diagram 181 | ************************* 182 | 183 | .. automod-diagram:: sphinx_automodapi.tests.example_module.mixed 184 | :private-bases: 185 | :parts: 1 186 | 187 | 188 | This comes after 189 | """ 190 | 191 | 192 | def test_am_replacer_titleandhdrs(tmpdir): 193 | """ 194 | Tests replacing an ".. automodapi::" entry with title-setting and header 195 | character options. 196 | """ 197 | 198 | ops = ['', ':headings: &*'] 199 | ostr = '\n '.join(ops) 200 | 201 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 202 | f.write(am_replacer_str.format(options=ostr)) 203 | 204 | run_sphinx_in_tmpdir(tmpdir) 205 | 206 | with open(tmpdir.join('index.rst.automodapi').strpath) as f: 207 | result = f.read() 208 | 209 | assert result == am_replacer_titleandhdrs_expected 210 | 211 | 212 | def test_am_replacer_titleandhdrs_invalid(tmpdir, capsys): 213 | """ 214 | Tests replacing an ".. automodapi::" entry with title-setting and header 215 | character options. 216 | """ 217 | 218 | ops = ['', ':headings: &'] 219 | ostr = '\n '.join(ops) 220 | 221 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 222 | f.write(am_replacer_str.format(options=ostr)) 223 | 224 | run_sphinx_in_tmpdir(tmpdir, expect_error=True) 225 | 226 | stdout, stderr = capsys.readouterr() 227 | assert "Not enough headings (got 1, need 2), using default -^" in stderr 228 | 229 | 230 | am_replacer_nomain_str = """ 231 | This comes before 232 | 233 | .. automodapi:: sphinx_automodapi.tests.example_module.functions 234 | :no-main-docstr: 235 | 236 | This comes after 237 | """ 238 | 239 | am_replacer_nomain_expected = """ 240 | This comes before 241 | 242 | 243 | sphinx_automodapi.tests.example_module.functions Module 244 | ------------------------------------------------------- 245 | 246 | 247 | 248 | Functions 249 | ^^^^^^^^^ 250 | 251 | .. automodsumm:: sphinx_automodapi.tests.example_module.functions 252 | :functions-only: 253 | :toctree: api 254 | 255 | 256 | This comes after 257 | """.format(empty='') 258 | 259 | 260 | def test_am_replacer_nomain(tmpdir): 261 | """ 262 | Tests replacing an ".. automodapi::" with "no-main-docstring" . 263 | """ 264 | 265 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 266 | f.write(am_replacer_nomain_str.format(options='')) 267 | 268 | run_sphinx_in_tmpdir(tmpdir) 269 | 270 | with open(tmpdir.join('index.rst.automodapi').strpath) as f: 271 | result = f.read() 272 | 273 | assert result == am_replacer_nomain_expected 274 | 275 | 276 | am_replacer_skip_str = """ 277 | This comes before 278 | 279 | .. automodapi:: sphinx_automodapi.tests.example_module.functions 280 | :skip: add 281 | :skip: subtract 282 | 283 | This comes after 284 | """ 285 | 286 | am_replacer_skip_expected = """ 287 | This comes before 288 | 289 | 290 | sphinx_automodapi.tests.example_module.functions Module 291 | ------------------------------------------------------- 292 | 293 | .. automodule:: sphinx_automodapi.tests.example_module.functions 294 | 295 | Functions 296 | ^^^^^^^^^ 297 | 298 | .. automodsumm:: sphinx_automodapi.tests.example_module.functions 299 | :functions-only: 300 | :toctree: api 301 | :skip: add,subtract 302 | 303 | 304 | This comes after 305 | """.format(empty='') 306 | 307 | 308 | def test_am_replacer_skip(tmpdir): 309 | """ 310 | Tests using the ":skip: option in an ".. automodapi::" . 311 | """ 312 | 313 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 314 | f.write(am_replacer_skip_str.format(options='')) 315 | 316 | run_sphinx_in_tmpdir(tmpdir) 317 | 318 | with open(tmpdir.join('index.rst.automodapi').strpath) as f: 319 | result = f.read() 320 | 321 | assert result == am_replacer_skip_expected 322 | 323 | 324 | am_replacer_skip_stdlib_str = """ 325 | This comes before 326 | 327 | .. automodapi:: sphinx_automodapi.tests.example_module.stdlib 328 | :skip: time 329 | :skip: Path 330 | 331 | This comes after 332 | """ 333 | 334 | 335 | am_replacer_skip_stdlib_expected = """ 336 | This comes before 337 | 338 | 339 | sphinx_automodapi.tests.example_module.stdlib Module 340 | ---------------------------------------------------- 341 | 342 | .. automodule:: sphinx_automodapi.tests.example_module.stdlib 343 | 344 | Functions 345 | ^^^^^^^^^ 346 | 347 | .. automodsumm:: sphinx_automodapi.tests.example_module.stdlib 348 | :functions-only: 349 | :toctree: api 350 | :skip: time,Path 351 | 352 | 353 | This comes after 354 | """.format(empty='') 355 | 356 | 357 | def test_am_replacer_skip_stdlib(tmpdir): 358 | """ 359 | Tests using the ":skip:" option in an ".. automodapi::" 360 | that skips objects imported from the standard library. 361 | This is a regression test for #141 362 | """ 363 | 364 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 365 | f.write(am_replacer_skip_stdlib_str.format(options='')) 366 | 367 | run_sphinx_in_tmpdir(tmpdir) 368 | 369 | with open(tmpdir.join('index.rst.automodapi').strpath) as f: 370 | result = f.read() 371 | 372 | assert result == am_replacer_skip_stdlib_expected 373 | 374 | 375 | am_replacer_include_stdlib_str = """ 376 | This comes before 377 | 378 | .. automodapi:: sphinx_automodapi.tests.example_module.stdlib 379 | :include: add 380 | :allowed-package-names: pathlib, datetime, sphinx_automodapi 381 | 382 | This comes after 383 | """ 384 | 385 | am_replacer_include_stdlib_expected = """ 386 | This comes before 387 | 388 | 389 | sphinx_automodapi.tests.example_module.stdlib Module 390 | ---------------------------------------------------- 391 | 392 | .. automodule:: sphinx_automodapi.tests.example_module.stdlib 393 | 394 | Functions 395 | ^^^^^^^^^ 396 | 397 | .. automodsumm:: sphinx_automodapi.tests.example_module.stdlib 398 | :functions-only: 399 | :toctree: api 400 | :skip: Path,time 401 | :allowed-package-names: pathlib,datetime,sphinx_automodapi 402 | 403 | 404 | This comes after 405 | """.format(empty='') 406 | 407 | 408 | def test_am_replacer_include_stdlib(tmpdir): 409 | """ 410 | Tests using the ":include: option in an ".. automodapi::" 411 | in the presence of objects imported from the standard library. 412 | """ 413 | 414 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 415 | f.write(am_replacer_include_stdlib_str.format(options='')) 416 | 417 | run_sphinx_in_tmpdir(tmpdir) 418 | 419 | with open(tmpdir.join('index.rst.automodapi').strpath) as f: 420 | result = f.read() 421 | 422 | assert result == am_replacer_include_stdlib_expected 423 | 424 | 425 | am_replacer_include_str = """ 426 | This comes before 427 | 428 | .. automodapi:: sphinx_automodapi.tests.example_module.functions 429 | :include: add 430 | :include: subtract 431 | 432 | This comes after 433 | """ 434 | 435 | am_replacer_include_expected = """ 436 | This comes before 437 | 438 | 439 | sphinx_automodapi.tests.example_module.functions Module 440 | ------------------------------------------------------- 441 | 442 | .. automodule:: sphinx_automodapi.tests.example_module.functions 443 | 444 | Functions 445 | ^^^^^^^^^ 446 | 447 | .. automodsumm:: sphinx_automodapi.tests.example_module.functions 448 | :functions-only: 449 | :toctree: api 450 | :skip: multiply 451 | 452 | 453 | This comes after 454 | """.format(empty='') 455 | 456 | 457 | def test_am_replacer_include(tmpdir): 458 | """ 459 | Tests using the ":include: option in an ".. automodapi::" . 460 | """ 461 | 462 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 463 | f.write(am_replacer_include_str.format(options='')) 464 | 465 | run_sphinx_in_tmpdir(tmpdir) 466 | 467 | with open(tmpdir.join('index.rst.automodapi').strpath) as f: 468 | result = f.read() 469 | 470 | assert result == am_replacer_include_expected 471 | 472 | 473 | am_replacer_invalidop_str = """ 474 | This comes before 475 | 476 | .. automodapi:: sphinx_automodapi.tests.example_module.functions 477 | :invalid-option: 478 | 479 | This comes after 480 | """ 481 | 482 | 483 | def test_am_replacer_invalidop(tmpdir, capsys): 484 | """ 485 | Tests that a sphinx warning is produced with an invalid option. 486 | """ 487 | 488 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 489 | f.write(am_replacer_invalidop_str.format(options='')) 490 | 491 | run_sphinx_in_tmpdir(tmpdir, expect_error=True) 492 | 493 | stdout, stderr = capsys.readouterr() 494 | assert "Found additional options invalid-option in automodapi." in stderr 495 | 496 | 497 | am_replacer_cython_str = """ 498 | This comes before 499 | 500 | .. automodapi:: apyhtest_eva.unit02 501 | {options} 502 | 503 | This comes after 504 | """ 505 | 506 | am_replacer_cython_expected = """ 507 | This comes before 508 | 509 | 510 | apyhtest_eva.unit02 Module 511 | -------------------------- 512 | 513 | .. automodule:: apyhtest_eva.unit02 514 | 515 | Functions 516 | ^^^^^^^^^ 517 | 518 | .. automodsumm:: apyhtest_eva.unit02 519 | :functions-only: 520 | :toctree: api 521 | 522 | This comes after 523 | """.format(empty='') 524 | 525 | 526 | def test_am_replacer_cython(tmpdir, cython_testpackage): # noqa 527 | """ 528 | Tests replacing an ".. automodapi::" for a Cython module. 529 | """ 530 | 531 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 532 | f.write(am_replacer_cython_str.format(options='')) 533 | 534 | run_sphinx_in_tmpdir(tmpdir) 535 | 536 | with open(tmpdir.join('index.rst.automodapi').strpath) as f: 537 | result = f.read() 538 | 539 | assert result == am_replacer_cython_expected 540 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/test_automodsumm.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # Licensed under a 3-clause BSD style license - see LICENSE.rst 3 | 4 | from copy import copy 5 | 6 | import pytest 7 | from docutils.parsers.rst import directives, roles 8 | 9 | from . import cython_testpackage # noqa 10 | from .helpers import run_sphinx_in_tmpdir 11 | 12 | 13 | def setup_function(func): 14 | # This can be replaced with the docutils_namespace context manager once 15 | # it is in a stable release of Sphinx 16 | func._directives = copy(directives._directives) 17 | func._roles = copy(roles._roles) 18 | 19 | 20 | def teardown_function(func): 21 | directives._directives = func._directives 22 | roles._roles = func._roles 23 | 24 | 25 | # nosignatures 26 | 27 | ADD_RST = """ 28 | :orphan: 29 | 30 | add 31 | === 32 | 33 | .. currentmodule:: sphinx_automodapi.tests.example_module.mixed 34 | 35 | .. autofunction:: add 36 | """.strip() 37 | 38 | MIXEDSPAM_RST = """ 39 | :orphan: 40 | 41 | MixedSpam 42 | ========= 43 | 44 | .. currentmodule:: sphinx_automodapi.tests.example_module.mixed 45 | 46 | .. autoclass:: MixedSpam 47 | :show-inheritance: 48 | """.strip() 49 | 50 | 51 | def write_api_files_to_tmpdir(tmpdir): 52 | apidir = tmpdir.mkdir('api') 53 | with open(apidir.join('sphinx_automodapi.tests.example_module.mixed.add.rst').strpath, 'w') as f: 54 | f.write(ADD_RST) 55 | with open(apidir.join('sphinx_automodapi.tests.example_module.mixed.MixedSpam.rst').strpath, 'w') as f: 56 | f.write(MIXEDSPAM_RST) 57 | 58 | 59 | ams_to_asmry_str = """ 60 | Before 61 | 62 | .. automodsumm:: sphinx_automodapi.tests.example_module.mixed 63 | {options} 64 | 65 | And After 66 | """ 67 | 68 | ams_to_asmry_expected = """\ 69 | .. currentmodule:: sphinx_automodapi.tests.example_module.mixed 70 | 71 | .. autosummary:: 72 | 73 | add 74 | MixedSpam 75 | 76 | """ 77 | 78 | 79 | def test_ams_to_asmry(tmpdir): 80 | 81 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 82 | f.write(ams_to_asmry_str.format(options='')) 83 | 84 | write_api_files_to_tmpdir(tmpdir) 85 | 86 | run_sphinx_in_tmpdir(tmpdir) 87 | 88 | with open(tmpdir.join('index.rst.automodsumm').strpath) as f: 89 | result = f.read() 90 | 91 | assert result == ams_to_asmry_expected 92 | 93 | 94 | def test_too_many_options(tmpdir, capsys): 95 | 96 | ops = ['', ':classes-only:', ':functions-only:'] 97 | ostr = '\n '.join(ops) 98 | 99 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 100 | f.write(ams_to_asmry_str.format(options=ostr)) 101 | 102 | write_api_files_to_tmpdir(tmpdir) 103 | 104 | run_sphinx_in_tmpdir(tmpdir, expect_error=True) 105 | 106 | stdout, stderr = capsys.readouterr() 107 | assert ("[automodsumm] Defined more than one of functions-only, " 108 | "classes-only, and variables-only. Skipping this directive." in stderr) 109 | 110 | 111 | ORDEREDDICT_RST = """ 112 | :orphan: 113 | 114 | OrderedDict 115 | =========== 116 | 117 | .. currentmodule:: sphinx_automodapi.tests.example_module.noall 118 | 119 | .. autoclass:: OrderedDict 120 | :show-inheritance: 121 | """.strip() 122 | 123 | 124 | @pytest.mark.parametrize('options,expect', [ 125 | ('', ['add', 'MixedSpam']), 126 | (':allowed-package-names: sphinx_automodapi', ['add', 'MixedSpam']), 127 | (':allowed-package-names: collections', ['OrderedDict']), 128 | (':allowed-package-names: sphinx_automodapi,collections', 129 | ['add', 'MixedSpam', 'OrderedDict']), 130 | ]) 131 | def test_am_allowed_package_names(options, expect, tmpdir): 132 | """ 133 | Test that allowed_package_names is interpreted correctly. 134 | """ 135 | def mixed2noall(s): 136 | return s.replace('example_module.mixed', 'example_module.noall') 137 | 138 | am_str = ams_to_asmry_str 139 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 140 | f.write(mixed2noall(am_str).format(options=(' '+options if options else ''))) 141 | 142 | apidir = tmpdir.mkdir('api') 143 | with open(apidir.join('sphinx_automodapi.tests.example_module.noall.add.rst').strpath, 'w') as f: 144 | f.write(mixed2noall(ADD_RST)) 145 | with open(apidir.join('sphinx_automodapi.tests.example_module.noall.MixedSpam.rst').strpath, 'w') as f: 146 | f.write(mixed2noall(MIXEDSPAM_RST)) 147 | with open(apidir.join('sphinx_automodapi.tests.example_module.noall.OrderedDict.rst').strpath, 'w') as f: 148 | f.write(ORDEREDDICT_RST) 149 | 150 | run_sphinx_in_tmpdir(tmpdir) 151 | 152 | with open(tmpdir.join('index.rst.automodsumm').strpath) as f: 153 | result = f.read() 154 | 155 | for x in expect: 156 | assert ' '+x in result 157 | 158 | 159 | PILOT_RST = """ 160 | :orphan: 161 | 162 | pilot 163 | ===== 164 | 165 | .. currentmodule:: apyhtest_eva.unit02 166 | 167 | .. autofunction:: pilot 168 | """.strip() 169 | 170 | ams_cython_str = """ 171 | Before 172 | 173 | .. automodsumm:: apyhtest_eva.unit02 174 | :functions-only: 175 | 176 | And After 177 | """ 178 | 179 | ams_cython_expected = """\ 180 | .. currentmodule:: apyhtest_eva.unit02 181 | 182 | .. autosummary:: 183 | 184 | pilot 185 | 186 | """ 187 | 188 | 189 | def test_ams_cython(tmpdir, cython_testpackage): # noqa 190 | 191 | with open(tmpdir.join('index.rst').strpath, 'w') as f: 192 | f.write(ams_cython_str) 193 | 194 | apidir = tmpdir.mkdir('api') 195 | with open(apidir.join('apyhtest_eva.unit02.pilot.rst').strpath, 'w') as f: 196 | f.write(PILOT_RST) 197 | 198 | run_sphinx_in_tmpdir(tmpdir) 199 | 200 | with open(tmpdir.join('index.rst.automodsumm').strpath) as f: 201 | result = f.read() 202 | 203 | assert result == ams_cython_expected 204 | 205 | 206 | # ============================================================================= 207 | 208 | CLASS_RST = """ 209 | :orphan: 210 | 211 | .. currentmodule:: {mod} 212 | 213 | .. autoclass:: {cls} 214 | """.strip() 215 | 216 | sorted_str = """ 217 | Before 218 | 219 | .. automodsumm:: sphinx_automodapi.tests.example_module.classes 220 | :sort: 221 | 222 | And After 223 | """ 224 | 225 | sorted_expected = """\ 226 | .. currentmodule:: sphinx_automodapi.tests.example_module.classes 227 | 228 | .. autosummary:: 229 | 230 | Egg 231 | Spam 232 | 233 | """ 234 | 235 | 236 | def test_sort(tmpdir): 237 | with open(tmpdir.join("index.rst").strpath, "w") as f: 238 | f.write(sorted_str) 239 | 240 | apidir = tmpdir.mkdir('api') 241 | mod = 'sphinx_automodapi.tests.example_module.classes' 242 | for cls in "Spam", "Egg": 243 | with open(apidir.join(f'{mod}.{cls}.rst').strpath, 'w') as f: 244 | f.write(CLASS_RST.format(mod=mod, cls=cls)) 245 | 246 | run_sphinx_in_tmpdir(tmpdir) 247 | 248 | with open(tmpdir.join("index.rst.automodsumm").strpath) as f: 249 | result = f.read() 250 | 251 | assert result == sorted_expected 252 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/test_cases.py: -------------------------------------------------------------------------------- 1 | # The following tests use a plain Python example module that is at 2 | # sphinx_automodapi.tests.example_module. 3 | 4 | # We store different cases in the cases sub-directory of the tests directory 5 | 6 | import os 7 | import glob 8 | import shutil 9 | from itertools import product 10 | 11 | import pytest 12 | 13 | from copy import deepcopy, copy 14 | from sphinx.util.osutil import ensuredir 15 | from docutils.parsers.rst import directives, roles 16 | 17 | from .helpers import build_main, write_conf 18 | 19 | CASES_ROOT = os.path.join(os.path.dirname(__file__), 'cases') 20 | 21 | CASES_DIRS = glob.glob(os.path.join(CASES_ROOT, '*')) 22 | 23 | PARALLEL = {False, True} 24 | PROP_ATTR = {True, False} 25 | 26 | 27 | intersphinx_mapping = { 28 | 'python': ('https://docs.python.org/3/', None) 29 | } 30 | 31 | DEFAULT_CONF = {'source_suffix': '.rst', 32 | 'master_doc': 'index', 33 | 'nitpicky': True, 34 | 'extensions': ['sphinx.ext.intersphinx', 'sphinx_automodapi.automodapi'], 35 | 'suppress_warnings': ['app.add_directive', 'app.add_node'], 36 | 'intersphinx_mapping': intersphinx_mapping, 37 | 'nitpick_ignore': [('py:class', 'sphinx_automodapi.tests.example_module.classes.BaseSpam'), 38 | ('py:class', 'sphinx_automodapi.tests.example_module.other_classes.BaseFoo'), 39 | # See the following links for why these classes need to be ignored. 40 | # This only seems to be necessary for Python 2.7. 41 | # 42 | # https://trac.sagemath.org/ticket/19211 43 | # https://stackoverflow.com/q/11417221/3776794 44 | ('py:class', '_abcoll.Sequence'), 45 | ('py:class', '_abcoll.Iterable'), 46 | ('py:class', '_abcoll.Container'), 47 | ('py:class', '_abcoll.Sized')]} 48 | 49 | 50 | def setup_function(func): 51 | # This can be replaced with the docutils_namespace context manager once 52 | # it is in a stable release of Sphinx 53 | func._directives = copy(directives._directives) 54 | func._roles = copy(roles._roles) 55 | 56 | 57 | def teardown_function(func): 58 | directives._directives = func._directives 59 | roles._roles = func._roles 60 | 61 | 62 | @pytest.mark.parametrize(('case_dir', 'parallel', 'prop_attr'), product(CASES_DIRS, PARALLEL, PROP_ATTR)) 63 | def test_run_full_case(tmpdir, case_dir, parallel, prop_attr): 64 | 65 | input_dir = os.path.join(case_dir, 'input') 66 | 67 | output_folder = "output_prop_is_attr" if prop_attr else "output_prop_is_not_attr" 68 | output_dir = os.path.join(case_dir, output_folder) 69 | if not os.path.isdir(output_dir): 70 | output_dir = os.path.join(case_dir, 'output') 71 | 72 | docs_dir = tmpdir.mkdir('docs').strpath 73 | 74 | conf = deepcopy(DEFAULT_CONF) 75 | conf.update({'automodapi_toctreedirnm': 'api', 76 | 'automodapi_writereprocessed': True, 77 | 'automodsumm_writereprocessed': True, 78 | 'automodsumm_properties_are_attributes': prop_attr}) 79 | 80 | if os.path.basename(case_dir) in ('mixed_toplevel', 81 | 'mixed_toplevel_all_objects', 82 | 'allowed_names'): 83 | conf['extensions'].append('sphinx_automodapi.smart_resolver') 84 | 85 | start_dir = os.path.abspath('.') 86 | 87 | src_dir = 'src' if 'source_dir' in case_dir else '.' 88 | 89 | ensuredir(os.path.join(docs_dir, src_dir)) 90 | 91 | write_conf(os.path.join(os.path.join(docs_dir, src_dir), 'conf.py'), conf) 92 | 93 | for root, dirnames, filenames in os.walk(input_dir): 94 | for filename in filenames: 95 | root_dir = os.path.join(docs_dir, os.path.relpath(root, input_dir)) 96 | ensuredir(root_dir) 97 | input_file = os.path.join(root, filename) 98 | shutil.copy(input_file, root_dir) 99 | 100 | argv = ['-W', '-b', 'html', src_dir, '_build/html'] 101 | if parallel: 102 | argv.insert(0, '-j 4') 103 | 104 | try: 105 | os.chdir(docs_dir) 106 | status = build_main(argv=argv) 107 | finally: 108 | os.chdir(start_dir) 109 | 110 | assert status == 0 111 | 112 | # Check that all expected output files are there and match the reference files 113 | for root, dirnames, filenames in os.walk(output_dir): 114 | for filename in filenames: 115 | path_reference = os.path.join(root, filename) 116 | path_relative = os.path.relpath(path_reference, output_dir) 117 | path_actual = os.path.join(docs_dir, path_relative) 118 | assert os.path.exists(path_actual) 119 | with open(path_actual, encoding='utf8') as f: 120 | actual = f.read() 121 | with open(path_reference, encoding='utf8') as f: 122 | reference = f.read() 123 | assert actual.strip() == reference.strip() 124 | 125 | 126 | def test_duplicated_warning(tmpdir): 127 | input_dir = os.path.join(os.path.dirname(__file__), 'duplicated_warning', 'docs') 128 | docs_dir = tmpdir.mkdir('docs').strpath 129 | 130 | start_dir = os.path.abspath('.') 131 | src_dir = '.' 132 | 133 | for root, dirnames, filenames in os.walk(input_dir): 134 | for filename in filenames: 135 | root_dir = os.path.join(docs_dir, os.path.relpath(root, input_dir)) 136 | ensuredir(root_dir) 137 | input_file = os.path.join(root, filename) 138 | shutil.copy(input_file, root_dir) 139 | 140 | argv = ['-W', '-b', 'html', src_dir, '_build/html'] 141 | 142 | try: 143 | os.chdir(docs_dir) 144 | status = build_main(argv=argv) 145 | finally: 146 | os.chdir(start_dir) 147 | 148 | assert status == 0 149 | 150 | 151 | def test_slots_example(): 152 | """Basic tests for slots example module""" 153 | from sphinx_automodapi.tests.example_module.slots import ( 154 | SlotDict, DerivedParam, DerivedSlotParam 155 | ) 156 | SlotDict('param', 'other_param').my_method() 157 | DerivedParam('param', 'other_param', 'extra_param').derived_from_slot_class_method() 158 | DerivedSlotParam('param', 'other_param', 'extra_param').derived_from_slot_class_method() 159 | -------------------------------------------------------------------------------- /sphinx_automodapi/tests/test_utils.py: -------------------------------------------------------------------------------- 1 | # namedtuple is needed for find_mod_objs so it can have a non-local module 2 | 3 | from collections import namedtuple 4 | 5 | from ..utils import find_mod_objs 6 | 7 | 8 | def test_find_mod_objs(): 9 | lnms, fqns, objs = find_mod_objs('sphinx_automodapi') 10 | 11 | # just check for astropy.test ... other things might be added, so we 12 | # shouldn't check that it's the only thing 13 | assert lnms == [] 14 | 15 | lnms, fqns, objs = find_mod_objs( 16 | 'sphinx_automodapi.tests.test_utils', onlylocals=False) 17 | 18 | assert namedtuple in objs 19 | 20 | lnms, fqns, objs = find_mod_objs( 21 | 'sphinx_automodapi.tests.test_utils', onlylocals=True) 22 | assert 'namedtuple' not in lnms 23 | assert 'collections.namedtuple' not in fqns 24 | assert namedtuple not in objs 25 | 26 | 27 | def test_find_mod_objs_with_list_of_modules(): 28 | lnms, fqns, objs = find_mod_objs( 29 | 'sphinx_automodapi.tests.test_utils', onlylocals=['sphinx_automodapi']) 30 | 31 | assert namedtuple not in objs 32 | assert find_mod_objs in objs 33 | 34 | lnms, fqns, objs = find_mod_objs( 35 | 'sphinx_automodapi.tests.test_utils', onlylocals=['collections']) 36 | 37 | assert namedtuple in objs 38 | assert find_mod_objs not in objs 39 | 40 | lnms, fqns, objs = find_mod_objs( 41 | 'sphinx_automodapi.tests.test_utils', onlylocals=['collections', 42 | 'sphinx_automodapi']) 43 | 44 | assert namedtuple in objs 45 | assert find_mod_objs in objs 46 | -------------------------------------------------------------------------------- /sphinx_automodapi/utils.py: -------------------------------------------------------------------------------- 1 | import sys 2 | import re 3 | import os 4 | from inspect import ismodule 5 | from warnings import warn 6 | 7 | from sphinx.ext.autosummary.generate import find_autosummary_in_docstring 8 | 9 | __all__ = ['cleanup_whitespace', 10 | 'find_mod_objs', 'find_autosummary_in_lines_for_automodsumm'] 11 | 12 | # We use \n instead of os.linesep because even on Windows, the generated files 13 | # use \n as the newline character. 14 | SPACE_NEWLINE = ' \n' 15 | SINGLE_NEWLINE = '\n' 16 | DOUBLE_NEWLINE = '\n\n' 17 | TRIPLE_NEWLINE = '\n\n\n' 18 | 19 | 20 | def cleanup_whitespace(text): 21 | """ 22 | Make sure there are never more than two consecutive newlines, and that 23 | there are no trailing whitespaces. 24 | """ 25 | 26 | # Get rid of overall leading/trailing whitespace 27 | text = text.strip() + '\n' 28 | 29 | # Get rid of trailing whitespace on each line 30 | while SPACE_NEWLINE in text: 31 | text = text.replace(SPACE_NEWLINE, SINGLE_NEWLINE) 32 | 33 | # Avoid too many consecutive newlines 34 | while TRIPLE_NEWLINE in text: 35 | text = text.replace(TRIPLE_NEWLINE, DOUBLE_NEWLINE) 36 | 37 | return text 38 | 39 | 40 | def find_mod_objs(modname, onlylocals=False, sort=False): 41 | """ Returns all the public attributes of a module referenced by name. 42 | 43 | .. note:: 44 | The returned list *not* include subpackages or modules of 45 | `modname`,nor does it include private attributes (those that 46 | beginwith '_' or are not in `__all__`). 47 | 48 | Parameters 49 | ---------- 50 | modname : str 51 | The name of the module to search. 52 | onlylocals : bool or list 53 | If `True`, only attributes that are either members of `modname` OR one of 54 | its modules or subpackages will be included. If a list, only members 55 | of packages in the list are included. If `False`, selection is done. 56 | This option is ignored if a module defines __all__ - in that case, __all__ 57 | is used to determine whether objects are public. 58 | 59 | Returns 60 | ------- 61 | localnames : list of str 62 | A list of the names of the attributes as they are named in the 63 | module `modname` . 64 | fqnames : list of str 65 | A list of the full qualified names of the attributes (e.g., 66 | ``astropy.utils.misc.find_mod_objs``). For attributes that are 67 | simple variables, this is based on the local name, but for 68 | functions or classes it can be different if they are actually 69 | defined elsewhere and just referenced in `modname`. 70 | objs : list of objects 71 | A list of the actual attributes themselves (in the same order as 72 | the other arguments) 73 | 74 | """ 75 | 76 | __import__(modname) 77 | mod = sys.modules[modname] 78 | 79 | # Note: use getattr instead of mod.__dict__[k] for modules that 80 | # define their own __getattr__ and __dir__. 81 | if hasattr(mod, '__all__'): 82 | pkgitems = [(k, getattr(mod, k)) for k in mod.__all__] 83 | # Optionally sort the items alphabetically 84 | if sort: 85 | pkgitems.sort() 86 | onlylocals = False 87 | else: 88 | pkgitems = [(k, getattr(mod, k)) for k in dir(mod) if k[0] != "_"] 89 | 90 | # filter out modules and pull the names and objs out 91 | localnames = [k for k, v in pkgitems if not ismodule(v)] 92 | objs = [v for k, v in pkgitems if not ismodule(v)] 93 | 94 | # fully qualified names can be determined from the object's module 95 | fqnames = [] 96 | for obj, lnm in zip(objs, localnames): 97 | if hasattr(obj, '__module__') and hasattr(obj, '__name__'): 98 | fqnames.append(obj.__module__ + '.' + obj.__name__) 99 | else: 100 | fqnames.append(modname + '.' + lnm) 101 | 102 | if onlylocals: 103 | if isinstance(onlylocals, (tuple, list)): 104 | modname = tuple(onlylocals) 105 | valids = [fqn.startswith(modname) for fqn in fqnames] 106 | localnames = [e for i, e in enumerate(localnames) if valids[i]] 107 | fqnames = [e for i, e in enumerate(fqnames) if valids[i]] 108 | objs = [e for i, e in enumerate(objs) if valids[i]] 109 | 110 | return localnames, fqnames, objs 111 | 112 | 113 | def find_autosummary_in_lines_for_automodsumm(lines, module=None, filename=None): 114 | """Find out what items appear in autosummary:: directives in the 115 | given lines. 116 | Returns a list of (name, toctree, template, inherited_members, noindex) 117 | where *name* is a name 118 | of an object and *toctree* the :toctree: path of the corresponding 119 | autosummary directive (relative to the root of the file name), 120 | *template* the value of the :template: option, and *inherited_members* 121 | is the value of the :inherited-members: option. 122 | *toctree*, *template*, and *inherited_members* are ``None`` if the 123 | directive does not have the corresponding options set. 124 | 125 | .. note:: 126 | 127 | This is a slightly modified version of 128 | ``sphinx.ext.autosummary.generate.find_autosummary_in_lines`` 129 | which recognizes the ``inherited-members`` option. 130 | """ 131 | autosummary_re = re.compile(r'^(\s*)\.\.\s+autosummary::\s*') 132 | automodule_re = re.compile( 133 | r'^\s*\.\.\s+automodule::\s*([A-Za-zäüöÄÜÖßő0-9_.]+)\s*$') 134 | module_re = re.compile( 135 | r'^\s*\.\.\s+(current)?module::\s*([a-zA-ZäüöÄÜÖßő0-9_.]+)\s*$') 136 | autosummary_item_re = re.compile(r'^\s+(~?[_a-zA-ZäüöÄÜÖßő][a-zA-ZäüöÄÜÖßő0-9_.]*)\s*.*?') 137 | toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$') 138 | template_arg_re = re.compile(r'^\s+:template:\s*(.*?)\s*$') 139 | inherited_members_arg_re = re.compile(r'^\s+:inherited-members:\s*$') 140 | no_inherited_members_arg_re = re.compile(r'^\s+:no-inherited-members:\s*$') 141 | noindex_arg_re = re.compile(r'^\s+:noindex:\s*$') 142 | other_options_re = re.compile(r'^\s+:nosignatures:\s*$') 143 | 144 | documented = [] 145 | 146 | toctree = None 147 | template = None 148 | inherited_members = None 149 | noindex = None 150 | current_module = module 151 | in_autosummary = False 152 | base_indent = "" 153 | 154 | for line in lines: 155 | if in_autosummary: 156 | m = toctree_arg_re.match(line) 157 | if m: 158 | toctree = m.group(1) 159 | if filename: 160 | toctree = os.path.join(os.path.dirname(filename), 161 | toctree) 162 | continue 163 | 164 | m = template_arg_re.match(line) 165 | if m: 166 | template = m.group(1).strip() 167 | continue 168 | 169 | m = inherited_members_arg_re.match(line) 170 | if m: 171 | inherited_members = True 172 | continue 173 | 174 | m = no_inherited_members_arg_re.match(line) 175 | if m: 176 | inherited_members = False 177 | continue 178 | 179 | m = noindex_arg_re.match(line) 180 | if m: 181 | noindex = True 182 | continue 183 | 184 | if line.strip().startswith(':'): 185 | if other_options_re.match(line): 186 | continue # skip known options 187 | else: 188 | warn(line) # warn about unknown options 189 | 190 | m = autosummary_item_re.match(line) 191 | if m: 192 | name = m.group(1).strip() 193 | if name.startswith('~'): 194 | name = name[1:] 195 | if current_module and \ 196 | not name.startswith(current_module + '.'): 197 | name = "%s.%s" % (current_module, name) 198 | documented.append((name, toctree, template, 199 | inherited_members, noindex)) 200 | continue 201 | 202 | if not line.strip() or line.startswith(base_indent + " "): 203 | continue 204 | 205 | in_autosummary = False 206 | 207 | m = autosummary_re.match(line) 208 | if m: 209 | in_autosummary = True 210 | base_indent = m.group(1) 211 | toctree = None 212 | template = None 213 | inherited_members = None 214 | continue 215 | 216 | m = automodule_re.search(line) 217 | if m: 218 | current_module = m.group(1).strip() 219 | # recurse into the automodule docstring 220 | documented.extend(find_autosummary_in_docstring( 221 | current_module, filename=filename)) 222 | continue 223 | 224 | m = module_re.match(line) 225 | if m: 226 | current_module = m.group(2) 227 | continue 228 | 229 | return documented 230 | -------------------------------------------------------------------------------- /tox.ini: -------------------------------------------------------------------------------- 1 | [tox] 2 | envlist = py{38,39,310,311,312,313}-test-sphinx{_oldest,53,62,70,71,72,80,81,dev}{-cov}{-clocale} 3 | requires = pip >= 18.0 4 | setuptools >= 30.3.0 5 | isolated_build = true 6 | 7 | [testenv] 8 | changedir = .tmp/{envname} 9 | deps = 10 | sphinx_oldest: sphinx==4.0.0 11 | sphinx53: sphinx==5.3.* 12 | sphinx62: sphinx==6.2.* 13 | sphinx70: sphinx==7.0.* 14 | sphinx71: sphinx==7.1.* 15 | sphinx72: sphinx==7.2.* 16 | sphinx80: sphinx==8.0.* 17 | sphinx81: sphinx==8.1.* 18 | sphinxdev: git+https://github.com/sphinx-doc/sphinx.git 19 | extras = 20 | test: test 21 | commands = 22 | pip freeze 23 | !cov: pytest --pyargs sphinx_automodapi {posargs} 24 | cov: pytest --pyargs sphinx_automodapi --cov sphinx_automodapi --cov-config={toxinidir}/setup.cfg {posargs} 25 | cov: coverage xml -o {toxinidir}/coverage.xml 26 | passenv = HOME, WINDIR, LC_ALL, LC_CTYPE, LANG, CC, CI 27 | setenv = 28 | cov: CFLAGS = --coverage -fno-inline-functions -O0 29 | clocale: LC_CTYPE=C 30 | clocale: LC_ALL=C 31 | clocale: LANG=C 32 | platform = 33 | clocale: linux|darwin 34 | 35 | [testenv:codestyle] 36 | skip_install = true 37 | changedir = {toxinidir} 38 | description = Run all style and file checks with pre-commit 39 | deps = flake8 40 | commands = flake8 sphinx_automodapi --count 41 | --------------------------------------------------------------------------------