pax_global_header00006660000000000000000000000064146077143620014524gustar00rootroot0000000000000052 comment=4c613df9b9210c5b6395b9152c62d494be928f28 autodoc-traits-1.2.2/000077500000000000000000000000001460771436200144705ustar00rootroot00000000000000autodoc-traits-1.2.2/.flake8000066400000000000000000000002461460771436200156450ustar00rootroot00000000000000[flake8] # Ignore style and complexity # E: style errors # W: style warnings # C: complexity # F841: local variable assigned but never used ignore = E, C, W, D, F841 autodoc-traits-1.2.2/.github/000077500000000000000000000000001460771436200160305ustar00rootroot00000000000000autodoc-traits-1.2.2/.github/dependabot.yaml000066400000000000000000000010011460771436200210110ustar00rootroot00000000000000# dependabot.yaml reference: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file # # Notes: # - Status and logs from dependabot are provided at # https://github.com/jupyterhub/autodoc-traits/network/updates. # version: 2 updates: # Maintain dependencies in our GitHub Workflows - package-ecosystem: github-actions directory: / labels: [ci] schedule: interval: monthly time: "05:00" timezone: Etc/UTC autodoc-traits-1.2.2/.github/workflows/000077500000000000000000000000001460771436200200655ustar00rootroot00000000000000autodoc-traits-1.2.2/.github/workflows/release.yaml000066400000000000000000000024111460771436200223670ustar00rootroot00000000000000# This is a GitHub workflow defining a set of jobs with a set of steps. # ref: https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions # # Test build release artifacts (PyPI package) and publish them on pushed git # tags. # name: Release on: pull_request: paths-ignore: - "**.md" - ".github/workflows/*" - "!.github/workflows/release.yaml" push: paths-ignore: - "**.md" - ".github/workflows/*" - "!.github/workflows/release.yaml" branches-ignore: - "dependabot/**" - "pre-commit-ci-update-config" tags: - "**" workflow_dispatch: jobs: build-release: runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.11" - name: install build package run: | pip install --upgrade pip pip install build pip freeze - name: build release run: | python -m build --sdist --wheel . ls -l dist - name: publish to pypi uses: pypa/gh-action-pypi-publish@release/v1 if: startsWith(github.ref, 'refs/tags/') with: user: __token__ password: ${{ secrets.pypi_password }} autodoc-traits-1.2.2/.github/workflows/test.yaml000066400000000000000000000032451460771436200217340ustar00rootroot00000000000000# This is a GitHub workflow defining a set of jobs with a set of steps. # ref: https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions # name: Test on: pull_request: paths-ignore: - "**.md" - ".github/workflows/*" - "!.github/workflows/test.yaml" push: paths-ignore: - "**.md" - ".github/workflows/*" - "!.github/workflows/test.yaml" branches-ignore: - "dependabot/**" - "pre-commit-ci-update-config" tags: - "**" workflow_dispatch: jobs: pytest: runs-on: ubuntu-22.04 strategy: fail-fast: false matrix: include: - python-version: "3.8" sphinx-version: "4.*" traitlets-version: "4.*" pip-install-addition: "" - python-version: "3.9" sphinx-version: "5.*" traitlets-version: "4.*" pip-install-addition: "" - python-version: "3.10" sphinx-version: "6.*" traitlets-version: "5.*" pip-install-addition: "" - python-version: "3.11" sphinx-version: "7.*" traitlets-version: "5.*" pip-install-addition: "" - python-version: "3.12" sphinx-version: "7.*" traitlets-version: "5.*" pip-install-addition: "" steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "${{ matrix.python-version }}" - run: pip install ".[test]" "sphinx==${{ matrix.sphinx-version }}" "traitlets==${{ matrix.traitlets-version }}" ${{ matrix.pip-install-addition }} - run: pytest autodoc-traits-1.2.2/.gitignore000066400000000000000000000064051460771436200164650ustar00rootroot00000000000000# Manually added parts to .gitignore # ---------------------------------- # # Python .gitignore from https://github.com/github/gitignore/blob/HEAD/Python.gitignore # ------------------------------------------------------------------------------------- # # Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] *$py.class # C extensions *.so # Distribution / packaging .Python build/ develop-eggs/ dist/ downloads/ eggs/ .eggs/ lib/ lib64/ parts/ sdist/ var/ wheels/ share/python-wheels/ *.egg-info/ .installed.cfg *.egg MANIFEST # PyInstaller # Usually these files are written by a python script from a template # before PyInstaller builds the exe, so as to inject date/other infos into it. *.manifest *.spec # Installer logs pip-log.txt pip-delete-this-directory.txt # Unit test / coverage reports htmlcov/ .tox/ .nox/ .coverage .coverage.* .cache nosetests.xml coverage.xml *.cover *.py,cover .hypothesis/ .pytest_cache/ cover/ # Translations *.mo *.pot # Django stuff: *.log local_settings.py db.sqlite3 db.sqlite3-journal # Flask stuff: instance/ .webassets-cache # Scrapy stuff: .scrapy # Sphinx documentation docs/_build/ # PyBuilder .pybuilder/ target/ # Jupyter Notebook .ipynb_checkpoints # IPython profile_default/ ipython_config.py # pyenv # For a library or package, you might want to ignore these files since the code is # intended to run in multiple environments; otherwise, check them in: # .python-version # pipenv # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. # However, in case of collaboration, if having platform-specific dependencies or dependencies # having no cross-platform support, pipenv may install dependencies that don't work, or not # install all needed dependencies. #Pipfile.lock # poetry # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. # This is especially recommended for binary packages to ensure reproducibility, and is more # commonly ignored for libraries. # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control #poetry.lock # pdm # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. #pdm.lock # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it # in version control. # https://pdm.fming.dev/#use-with-ide .pdm.toml # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm __pypackages__/ # Celery stuff celerybeat-schedule celerybeat.pid # SageMath parsed files *.sage.py # Environments .env .venv env/ venv/ ENV/ env.bak/ venv.bak/ # Spyder project settings .spyderproject .spyproject # Rope project settings .ropeproject # mkdocs documentation /site # mypy .mypy_cache/ .dmypy.json dmypy.json # Pyre type checker .pyre/ # pytype static type analyzer .pytype/ # Cython debug symbols cython_debug/ # PyCharm # JetBrains specific template is maintained in a separate JetBrains.gitignore that can # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore # and can be added to the global gitignore or merged into this file. For a more nuclear # option (not recommended) you can uncomment the following to ignore the entire idea folder. #.idea/ autodoc-traits-1.2.2/.pre-commit-config.yaml000066400000000000000000000031631460771436200207540ustar00rootroot00000000000000# pre-commit is a tool to perform a predefined set of tasks manually and/or # automatically before git commits are made. # # Config reference: https://pre-commit.com/#pre-commit-configyaml---top-level # # Common tasks # # - Run on all files: pre-commit run --all-files # - Register git hooks: pre-commit install --install-hooks # repos: # Autoformat: Python code, syntax patterns are modernized - repo: https://github.com/asottile/pyupgrade rev: v3.15.2 hooks: - id: pyupgrade args: - --py37-plus # Autoformat: Python code - repo: https://github.com/PyCQA/autoflake rev: v2.3.1 hooks: - id: autoflake # args ref: https://github.com/PyCQA/autoflake#advanced-usage args: - --in-place # Autoformat: Python code - repo: https://github.com/pycqa/isort rev: 5.13.2 hooks: - id: isort # Autoformat: Python code - repo: https://github.com/psf/black rev: 24.3.0 hooks: - id: black # Autoformat: markdown, yaml - repo: https://github.com/pre-commit/mirrors-prettier rev: v4.0.0-alpha.8 hooks: - id: prettier # Autoformat and linting, misc. details - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.5.0 hooks: - id: end-of-file-fixer - id: requirements-txt-fixer - id: check-case-conflict - id: check-executables-have-shebangs # Linting: Python code (see the file .flake8) - repo: https://github.com/PyCQA/flake8 rev: "7.0.0" hooks: - id: flake8 # pre-commit.ci config reference: https://pre-commit.ci/#configuration ci: autoupdate_schedule: monthly autodoc-traits-1.2.2/CHANGELOG.md000066400000000000000000000207421460771436200163060ustar00rootroot00000000000000# Changes in autodoc-traits ## 1.2 ### 1.2.2 - 2024-04-17 ([full changelog](https://github.com/jupyterhub/autodoc-traits/compare/1.2.1...1.2.2)) #### Maintenance and upkeep improvements - Remove no longer needed upper bound pin on traitlets [#64](https://github.com/jupyterhub/autodoc-traits/pull/64) ([@consideRatio](https://github.com/consideRatio)) #### Continuous integration improvements - build(deps): bump actions/setup-python from 4 to 5 [#61](https://github.com/jupyterhub/autodoc-traits/pull/61) ([@consideRatio](https://github.com/consideRatio)) - build(deps): bump actions/checkout from 3 to 4 [#57](https://github.com/jupyterhub/autodoc-traits/pull/57) ([@consideRatio](https://github.com/consideRatio)) ### 1.2.1 - 2023-09-27 ([full changelog](https://github.com/jupyterhub/autodoc-traits/compare/1.2.0...1.2.1)) #### Maintenance and upkeep improvements - Bound `traitlets<5.10` and add test for issue observed in newer versions [#54](https://github.com/jupyterhub/autodoc-traits/pull/54) ([@consideRatio](https://github.com/consideRatio), [@manics](https://github.com/manics)) ### 1.2.0 - 2023-09-08 1.2.0 fixes compatibility with sphinx 7.2 and increases the minimum required sphinx version from 2 to 4. ([full changelog](https://github.com/jupyterhub/autodoc-traits/compare/1.1.0...1.2.0)) #### Bugs fixed - sphinx 7.2 compatibility, require sphinx 4 [#52](https://github.com/jupyterhub/autodoc-traits/pull/52) ([@minrk](https://github.com/minrk), [@manics](https://github.com/manics), [@consideRatio](https://github.com/consideRatio)) #### Contributors to this release The following people contributed discussions, new ideas, code and documentation contributions, and review. See [our definition of contributors](https://github-activity.readthedocs.io/en/latest/#how-does-this-tool-define-contributions-in-the-reports). ([GitHub contributors page for this release](https://github.com/jupyterhub/autodoc-traits/graphs/contributors?from=2022-12-20&to=2023-09-08&type=c)) @consideRatio ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3AconsideRatio+updated%3A2022-12-20..2023-09-08&type=Issues)) | @manics ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3Amanics+updated%3A2022-12-20..2023-09-08&type=Issues)) | @minrk ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3Aminrk+updated%3A2022-12-20..2023-09-08&type=Issues)) ## 1.1 ### 1.1.0 - 2022-12-20 ([full changelog](https://github.com/jupyterhub/autodoc-traits/compare/1.0.0...1.1.0)) #### Enhancements made - Automatically register the sphinx.ext.autodoc extension [#18](https://github.com/jupyterhub/autodoc-traits/pull/18) ([@consideRatio](https://github.com/consideRatio)) #### Bugs fixed - register traits with a help string as documented for `autoclass` [#33](https://github.com/jupyterhub/autodoc-traits/pull/33) ([@minrk](https://github.com/minrk)) - avoid putting `c.Class.trait` annotation on non-config traits [#32](https://github.com/jupyterhub/autodoc-traits/pull/32) ([@minrk](https://github.com/minrk)) - Add tests, add docstrings, and fix small bugs [#28](https://github.com/jupyterhub/autodoc-traits/pull/28) ([@consideRatio](https://github.com/consideRatio)) #### Maintenance and upkeep improvements - Add tests, add docstrings, and fix small bugs [#28](https://github.com/jupyterhub/autodoc-traits/pull/28) ([@consideRatio](https://github.com/consideRatio)) - single file module [#25](https://github.com/jupyterhub/autodoc-traits/pull/25) ([@minrk](https://github.com/minrk)) - maint: refactor `__init__.py` and add \_version.py, drop setup.py, require python 3.7+ [#21](https://github.com/jupyterhub/autodoc-traits/pull/21) ([@consideRatio](https://github.com/consideRatio)) #### Documentation improvements - Add tests, add docstrings, and fix small bugs [#28](https://github.com/jupyterhub/autodoc-traits/pull/28) ([@consideRatio](https://github.com/consideRatio)) - docs: add fixme note about unexpected inherited-members option [#16](https://github.com/jupyterhub/autodoc-traits/pull/16) ([@consideRatio](https://github.com/consideRatio)) #### Continuous integration improvements - Bump pypa/gh-action-pypi-publish from 1.4.1 to 1.6.4 [#23](https://github.com/jupyterhub/autodoc-traits/pull/23) ([@dependabot](https://github.com/dependabot)) - ci: add dependabot.yaml and update release workflow [#20](https://github.com/jupyterhub/autodoc-traits/pull/20) ([@consideRatio](https://github.com/consideRatio)) #### Contributors to this release ([GitHub contributors page for this release](https://github.com/jupyterhub/autodoc-traits/graphs/contributors?from=2022-12-06&to=2022-12-20&type=c)) [@consideRatio](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3AconsideRatio+updated%3A2022-12-06..2022-12-20&type=Issues) | [@minrk](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3Aminrk+updated%3A2022-12-06..2022-12-20&type=Issues) ## 1.0 ### 1.0.0 - 2022-12-06 Let's call it 1.0! ([full changelog](https://github.com/jupyterhub/autodoc-traits/compare/0.1.0...1.0.0)) #### Bugs fixed - Fix failure to use autoclass on non-traitlets configurable classes [#10](https://github.com/jupyterhub/autodoc-traits/pull/10) ([@blink1073](https://github.com/blink1073), [@consideRatio](https://github.com/consideRatio)) #### Maintenance and upkeep improvements - pre-commit: add typical jupyterhub org config [#15](https://github.com/jupyterhub/autodoc-traits/pull/15) ([@consideRatio](https://github.com/consideRatio), [@minrk](https://github.com/minrk)) #### Documentation improvements - Refresh README, RELEASE, and CHANGELOG [#14](https://github.com/jupyterhub/autodoc-traits/pull/14) ([@consideRatio](https://github.com/consideRatio), [@minrk](https://github.com/minrk)) - Point url to the GitHub repo [#8](https://github.com/jupyterhub/autodoc-traits/pull/8) ([@yuvipanda](https://github.com/yuvipanda), [@consideRatio](https://github.com/consideRatio)) - add changelog.md, release.md, README badges [#7](https://github.com/jupyterhub/autodoc-traits/pull/7) ([@minrk](https://github.com/minrk), [@yuvipanda](https://github.com/yuvipanda), [@consideRatio](https://github.com/consideRatio)) #### Contributors to this release ([GitHub contributors page for this release](https://github.com/jupyterhub/autodoc-traits/graphs/contributors?from=2021-10-22&to=2022-12-06&type=c)) [@blink1073](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3Ablink1073+updated%3A2021-10-22..2022-12-06&type=Issues) | [@consideRatio](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3AconsideRatio+updated%3A2021-10-22..2022-12-06&type=Issues) | [@minrk](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3Aminrk+updated%3A2021-10-22..2022-12-06&type=Issues) | [@willingc](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3Awillingc+updated%3A2021-10-22..2022-12-06&type=Issues) | [@yuvipanda](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3Ayuvipanda+updated%3A2021-10-22..2022-12-06&type=Issues) ## 0.1 ### 0.1.0 - 2021-10-22 0.1.0 is the first stable release of autodoc-traits. It fixes compatibility with sphinx 4 from the previously published 0.1.0dev prerelease. #### Merged PRs - add publish github action [#4](https://github.com/jupyterhub/autodoc-traits/pull/4) ([@minrk](https://github.com/minrk)) - Remove unused import of deprecated PyClassmember [#3](https://github.com/jupyterhub/autodoc-traits/pull/3) ([@minrk](https://github.com/minrk)) - Remove duplicates in documenting trait members [#1](https://github.com/jupyterhub/autodoc-traits/pull/1) ([@rkdarst](https://github.com/rkdarst)) #### Contributors to this release ([GitHub contributors page for this release](https://github.com/jupyterhub/autodoc-traits/graphs/contributors?from=2019-09-06&to=2021-10-22&type=c)) [@betatim](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3Abetatim+updated%3A2019-09-06..2021-10-22&type=Issues) | [@minrk](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3Aminrk+updated%3A2019-09-06..2021-10-22&type=Issues) | [@rkdarst](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3Arkdarst+updated%3A2019-09-06..2021-10-22&type=Issues) | [@welcome](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3Awelcome+updated%3A2019-09-06..2021-10-22&type=Issues) | [@willingc](https://github.com/search?q=repo%3Ajupyterhub%2Fautodoc-traits+involves%3Awillingc+updated%3A2019-09-06..2021-10-22&type=Issues) autodoc-traits-1.2.2/LICENSE000066400000000000000000000027621460771436200155040ustar00rootroot00000000000000BSD 3-Clause License Copyright (c) Project Jupyter Contributors All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. autodoc-traits-1.2.2/MANIFEST.in000066400000000000000000000002621460771436200162260ustar00rootroot00000000000000include MANIFEST.in include autodoc_traits.py include LICENSE include *.md # Exclude what we don't want to include prune */__pycache__ global-exclude *.pyc *~ *.bak *.swp *.pyo autodoc-traits-1.2.2/README.md000066400000000000000000000071051460771436200157520ustar00rootroot00000000000000# autodoc-traits [![Latest PyPI version](https://img.shields.io/pypi/v/autodoc-traits?logo=pypi)](https://pypi.python.org/pypi/autodoc-traits) [![GitHub](https://img.shields.io/badge/issue_tracking-github-blue?logo=github)](https://github.com/jupyterhub/autodoc-traits/issues) [![Discourse](https://img.shields.io/badge/help_forum-discourse-blue?logo=discourse)](https://discourse.jupyter.org/c/jupyterhub) [![Gitter](https://img.shields.io/badge/social_chat-gitter-blue?logo=gitter)](https://gitter.im/jupyterhub/jupyterhub) `autodoc-traits` is a Sphinx extension that builds on [`sphinx.ext.autodoc`][] to better document classes with [Traitlets][] based configuration. `autodoc-traits` provides the [Sphinx directives][] `autoconfigurable` (use with classes) and `autotrait` (use with the traitlets based configuration options). The `sphinx.ext.autodoc` provided directive [`automodule`][], which can overview classes, will with `autodoc-traits` enabled use `autoconfigurable` over [`autoclass`][] for classes has trait based configuration. Similarly, the `sphinx.ext.autodoc` provided `autoclass` directive will use `autotrait` over [`autoattribute`][] if configured to present the traitlets attributes normally not presented. The `autoattribute` directive will provide a header looking like `trait c.SampleConfigurable.trait = Bool(False)`, and as docstring it will use the trait's configured help text. ## How to use it 1. Install `autodoc-traits`: ```shell pip install autodoc-traits ``` 2. Configure Sphinx to use the `autodoc_traits` extensions in a Sphinx project's `conf.py` file: ```python # -- General Sphinx configuration -------------------------------------------- # ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration # extensions = [ "autodoc_traits", # sphinx.ext.autodoc will be registered by autodoc_traits, # but can safely be registered again. # ... ] ``` 3. Make use of the `sphinx.ext.autodoc` Sphinx directive like `automodule` that document classes, the `autodoc_traits` provided `autoconfigurable` that documents traitlets configurable classes, or the `autodoc_traits` provided `autotrait` that documents individual traitlets configuration options: From a .rst document: ```rst .. automodule:: sample_module :members: .. autoconfigurable:: sample_module.SampleConfigurable .. autotrait:: sample_module.SampleConfigurable.trait ``` ## Use with MyST Parser While you can use [`myst-parser`][], `sphinx.ext.autodoc`'s directives emits unparsed rST, forcing us to parse the autodoc directives in a rST context. From a .md document, with `myst-parser`: ````markdown ```{eval-rst} .. autoconfigurable:: sample_module.SampleConfigurable ``` ```` Due to this, also the Python docstrings are required to be in rST as well. Addressing this can be tracked from [executablebooks/team-compass issue #6](https://github.com/executablebooks/team-compass/issues/6). [`sphinx.ext.autodoc`]: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html [sphinx directives]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives [`autoclass`]: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoclass [`autoattribute`]: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoattribute [traitlets]: https://github.com/ipython/traitlets [`traitlets.traittype`]: https://traitlets.readthedocs.io/en/stable/trait_types.html#traitlets.TraitType [`myst-parser`]: https://myst-parser.readthedocs.io/en/latest/ autodoc-traits-1.2.2/RELEASE.md000066400000000000000000000023241460771436200160730ustar00rootroot00000000000000# How to make a release `autodoc-traits` is a package available on [PyPI][]. These are instructions on how to make a release. ## Pre-requisites - Push rights to [jupyterhub/autodoc-traits][] ## Steps to make a release 1. Create a PR updating `CHANGELOG.md` with [github-activity][] and continue only when its merged. ```shell pip install github-activity github-activity --heading-level=3 jupyterhub/autodoc-traits ``` 1. Checkout main and make sure it is up to date. ```shell git checkout main git fetch origin main git reset --hard origin/main ``` 1. Update the version, make commits, and push a git tag with `tbump`. ```shell pip install tbump tbump --dry-run ${VERSION} tbump ${VERSION} ``` Following this, the [CI system][] will build and publish a release. 1. Reset the version back to dev, e.g. `2.1.0.dev` after releasing `2.0.0` ```shell tbump --no-tag ${NEXT_VERSION}.dev ``` [pypi]: https://pypi.org/project/jupyterhub/ [jupyterhub/autodoc-traits]: https://github.com/jupyterhub/autodoc-traits [github-activity]: https://github.com/executablebooks/github-activity [ci system]: https://github.com/jupyterhub/autodoc-traits/actions/workflows/release.yaml autodoc-traits-1.2.2/autodoc_traits.py000066400000000000000000000251411460771436200200710ustar00rootroot00000000000000""" sphinx.ext.autodoc extension for classes with configurable traits. The code here is similar to the official code example in https://www.sphinx-doc.org/en/master/development/tutorials/autodoc_ext.html#writing-the-extension. """ import warnings from sphinx.ext.autodoc import AttributeDocumenter, ClassDocumenter, ObjectMember from sphinx.util.inspect import safe_getattr from traitlets import MetaHasTraits, TraitType, Undefined # __version__ should be updated using tbump, based on configuration in # pyproject.toml, according to instructions in RELEASE.md. # __version__ = "1.2.2" class ConfigurableDocumenter(ClassDocumenter): """ Specialized Documenter subclass for traits with config=True Links to relevant source code in sphinx.ext.autodoc: - Documenter: https://github.com/sphinx-doc/sphinx/blob/v6.0.0b2/sphinx/ext/autodoc/__init__.py#L270-L299 - ClassDocumenter: https://github.com/sphinx-doc/sphinx/blob/v6.0.0b2/sphinx/ext/autodoc/__init__.py#L1395-L1408 """ # objtype: The suffix to "auto" for a Sphinx directive name that will be # created (and the default value for "directivetype"). objtype = "configurable" # directivetype: Clarifies that this Documenter class could be capable of # documenting this kind of members of other parent like # Documenter classes. directivetype = "class" # priority: Declares this class' priority for use if multiple classes # "can_document_member" of the "directivetype". This is only # relevant if a parent class has a member. # # ConfigurableDocumenter can document traitlets configurable # classes, so a parent like Documenter class can be the # ModuleDocumenter. # priority = 100 # higher priority than ClassDocumenter's 10 @classmethod def can_document_member(cls, member, membername, isattr, parent): """ If the member is a class with traitlets then we can document it, and we will document it thanks to a high priority. This function is not considered if the ``autoconfigurable`` or ``autoclass`` directives are called directly. can_document_member is only used by other parent like Documenter classes having members of this class' configured "documentertype" - such as ModuleDocumenter. """ return isinstance(member, MetaHasTraits) def get_object_members(self, want_all): """ This get_object_members function override is a hack, manipulating __doc__ values of trait configuration objects, but otherwise behaving exactly like the super class get_object_members. It sets truthy strings to the class' traits __doc__ attributes. They will otherwise be filtered out by the Documenter.filter_members function, unless ``undoc-members`` option is set. Links to relevant source code in sphinx.ext.autodoc: - Documenter.filter_members: https://github.com/sphinx-doc/sphinx/blob/v6.0.0b2/sphinx/ext/autodoc/__init__.py#L616-L769 - Documenter.get_object_members: https://github.com/sphinx-doc/sphinx/blob/v6.0.0b2/sphinx/ext/autodoc/__init__.py#L607-L614 - ClassDocumenter.get_object_members: https://github.com/sphinx-doc/sphinx/blob/v6.0.0b2/sphinx/ext/autodoc/__init__.py#L1656-L1674 - traitlets.HasTraits.class_traits: https://github.com/ipython/traitlets/blob/v5.6.0/traitlets/traitlets.py#L1620-L1652 """ check, members = super().get_object_members(want_all) existing_member_names = {m.__name__ for m in members} # We add all _configurable_ traits, including inherited, even if they # weren't included via :members: or :inherited-members: options. # # Being added at this stage doesn't mean they are presented. Any members # added here must also have a truthy __doc__ string attribute and not be # part of the :exclude-members: option. # # FIXME: We have been adding the configurable trait_members # unconditionally, but should we keep doing that? # # See https://github.com/jupyterhub/autodoc-traits/issues/27 # config_trait_members = self.object.class_traits(config=True).items() for trait_tuple in config_trait_members: name, trait = trait_tuple if not trait.__doc__: warnings.warn( f""" Documenting {self.object.__name__}.{trait.name} without a help string because it has config=True. Including undocumented config=True traits is deprecated in autodoc-traits 1.1. Add a help string: {trait.name} = {trait.__class__.__name__}( help="...", ) to keep this trait in your docs, or include it explicitly via :members: """, FutureWarning, ) # FIXME: in the unlikely event that the patched trait # is documented multiple times in the same build, # this patch will cause it to have a truthy help string # elsewhere, not just in this autoconfigurable instance. trait.__doc__ = trait.help = "No help string is provided." if name not in existing_member_names: existing_member_names.add(name) members.append(ObjectMember(name, trait)) return check, members class TraitDocumenter(AttributeDocumenter): """ Links to relevant source code in sphinx.ext.autodoc: - Documenter: https://github.com/sphinx-doc/sphinx/blob/v6.0.0b2/sphinx/ext/autodoc/__init__.py#L270-L299 - AttributeDocumenter: https://github.com/sphinx-doc/sphinx/blob/v6.0.0b2/sphinx/ext/autodoc/__init__.py#L2509-L2524 """ # objtype: The suffix to "auto" for a Sphinx directive name that will be # created (and the default value for "directivetype"). objtype = "trait" # directivetype: Clarifies that this Documenter class could be capable of # documenting this kind of members of other parent like # Documenter classes. directivetype = "attribute" # priority: Declares this class' priority for use if multiple classes # "can_document_member" of the "directivetype". This is only # relevant if a parent class has a member. # # TraitsDocumenter can document traitlets type attributes, so the # parent like Documenter class is typically ClassDocumenter, but # can also be the ConfigurableDocumenter. # priority = 100 # AttributeDocumenter has 10 # order: order if the autodoc_member_order in conf.py is set to "groupwise", # by default it is "alphabetical", where lowest order comes first. # Since traits are relevant configuration, we declare the lowest # order for high visual priority. member_order = 0 # AttributeDocumenter has 60 @classmethod def can_document_member(cls, member, membername, isattr, parent): """ If the member is a traitlets type we can document it, and we will document it thanks to a high priority. This function is not considered if the ``autotrait`` or ``autoattribute`` directives are called directly. can_document_member is only used by other parent like Documenter classes having members of this class' configured "documentertype" - such as ClassDocumenter. """ return isinstance(member, TraitType) def add_directive_header(self, sig): """ add_directive_header is called by the base class' Documenter.generate method. It is provided by both AttributeDocumenter and Documenter. This override retains use of the super classes implementations, but influence them. For functions, the directive header describes the function's call signature, but not the function's docstring. Similarly, we look to emit rST to describe how the traitlets configuration option can be configured and its default value. - Documenter.generate: https://github.com/sphinx-doc/sphinx/blob/v6.0.0b2/sphinx/ext/autodoc/__init__.py#L918-L929 - AttributeDocumenter.add_directive_header: https://github.com/sphinx-doc/sphinx/blob/v6.0.0b2/sphinx/ext/autodoc/__init__.py#L2592-L2620 - Documenter.add_directive_header: https://github.com/sphinx-doc/sphinx/blob/v6.0.0b2/sphinx/ext/autodoc/__init__.py#L504-L524 """ default_value = self.object.default_value if default_value is Undefined: default_value = "" else: default_value = repr(default_value) traitlets_type = self.object.__class__.__name__ # Bool if self.object.metadata.get("config"): # add config prefix (c.TestConfigurator.trait = ) if it's configurable config_prefix = f"c.{self.format_name()} = " else: config_prefix = "" self.options.annotation = f"{config_prefix}{traitlets_type}({default_value})" super().add_directive_header(sig) def hastraits_attrgetter(obj, name, *defargs): """getattr for trait Ensures when HasTraits are documented, their __doc__ attr is defined as the .help string. This backports a change in traitlets 5.8.0. """ attr = safe_getattr(obj, name, *defargs) if isinstance(attr, TraitType): # ensure __doc__ is defined as the trait's help string # if help is empty, that's the same as undocumented attr.__doc__ = attr.help return attr def setup(app): """ The setup function is required for Sphinx extensions. In this function we register the sphinx.ext.autodoc extension that this extension needs to function, and we register our sphinx.ext.autodoc Documenter classes we provide. """ # setup_extension reference: # https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.setup_extension app.setup_extension("sphinx.ext.autodoc") # add_autodocumenter reference: # https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_autodocumenter app.add_autodocumenter(ConfigurableDocumenter) app.add_autodocumenter(TraitDocumenter) # add_autodoc_attrgetter reference: # https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_autodoc_attrgetter app.add_autodoc_attrgetter(MetaHasTraits, hastraits_attrgetter) autodoc-traits-1.2.2/pyproject.toml000066400000000000000000000054401460771436200174070ustar00rootroot00000000000000# project # - ref 1: https://peps.python.org/pep-0621/ # - ref 2: https://hatch.pypa.io/latest/config/metadata/#project-metadata # [project] name = "autodoc-traits" description = "Sphinx extension to autodoc traitlets" keywords = ["sphinx", "extension", "autodoc", "traitlets"] authors = [ {name = "Jupyter Development Team", email = "jupyter@googlegroups.com"}, ] classifiers = [ "Development Status :: 5 - Production/Stable", "Operating System :: OS Independent", "Programming Language :: Python :: 3", ] readme = "README.md" license = {file = "LICENSE"} dynamic = ["version"] requires-python = ">=3.7" dependencies = [ "sphinx>=4", "traitlets>=4", ] [project.optional-dependencies] test = [ "pytest", ] [project.urls] Documentation = "https://github.com/jupyterhub/autodoc-traits#readme" Issues = "https://github.com/jupyterhub/autodoc-traits/issues" Source = "https://github.com/jupyterhub/autodoc-traits" # build-system # - ref 1: https://peps.python.org/pep-0517/ # [build-system] requires = ["hatchling"] build-backend = "hatchling.build" # hatch ref: https://hatch.pypa.io/latest/ # [tool.hatch.version] path = "autodoc_traits.py" # autoflake is used for autoformatting Python code # # ref: https://github.com/PyCQA/autoflake#readme # [tool.autoflake] ignore-init-module-imports = true remove-all-unused-imports = true remove-duplicate-keys = true #remove-unused-variables = true # isort is used for autoformatting Python code # # ref: https://pycqa.github.io/isort/ # [tool.isort] profile = "black" # black is used for autoformatting Python code # # ref: https://black.readthedocs.io/en/stable/ # [tool.black] skip-string-normalization = true # target-version should be all supported versions, see # https://github.com/psf/black/issues/751#issuecomment-473066811 target_version = [ "py37", "py38", "py39", "py310", "py311", ] # pytest is used for running Python based tests # # ref: https://docs.pytest.org/en/stable/ # [tool.pytest.ini_options] addopts = "--verbose --color=yes --durations=10 --ignore=tests/docs/sample_module.py" # tbump is used to simplify and standardize the release process when updating # the version, making a git commit and tag, and pushing changes. # # ref: https://github.com/your-tools/tbump#readme # [tool.tbump.version] current = "1.2.2" # Example of a pep440 regexp. # Make sure this matches current_version before # using tbump regex = ''' (?P\d+) \. (?P\d+) \. (?P\d+) (?P
((a|b|rc)\d+)|)
  \.?
  (?P(?<=\.)dev\d*|)
'''

[tool.tbump.git]
message_template = "Bump to {new_version}"
tag_template = "{new_version}"

# For each file to patch, add a [[tool.tbump.file]] config
# section containing the path of the file, relative to the
# tbump.toml location.
[[tool.tbump.file]]
src = "autodoc_traits.py"
autodoc-traits-1.2.2/tests/000077500000000000000000000000001460771436200156325ustar00rootroot00000000000000autodoc-traits-1.2.2/tests/README.md000066400000000000000000000016541460771436200171170ustar00rootroot00000000000000# About the test suite

We use `pytest` to run `sphinx-build` against the Sphinx project in the `docs/`
folder. Besides concluding that the build succeeds without warnings, we look for
strings in the .html files to estimate if it has rendered as it should or not.

The test .rst documents include some descriptions about whats tested.

## Inspecting the test documentation

`sphinx-autobuild` is convenient to use when looking to inspect or expand the
content in the docs/ folder, which rendered is whats inspected by the test
suite.

```shell
pip install sphinx-autobuild

cd docs
# --watch:     we watch python files influencing the built documentation
# --pre-build: we rebuild from scratch as changes to the python files
#              can influence all built html
sphinx-autobuild \
    --open-browser \
    --watch="test_module.py" \
    --watch="../../autodoc_traits.py" \
    --pre-build="rm -rf build" \
    source \
    build
```
autodoc-traits-1.2.2/tests/conftest.py000066400000000000000000000051511460771436200200330ustar00rootroot00000000000000import glob
import os
import shutil
import sys
import tempfile
from functools import partial

import pytest

if sys.version_info >= (3, 8):
    copy_tree = partial(shutil.copytree, dirs_exist_ok=True)
else:
    # use deprecated distutils on Python < 3.8
    # when shutil.copytree added dirs_exist_ok support
    from distutils.dir_util import copy_tree


@pytest.fixture
def temp_docs_dir():
    """
    This fixture provides a temporary directory with files copied from the
    tests/docs directory.
    """
    with tempfile.TemporaryDirectory() as temp_dir:
        tests_dir = os.path.abspath(os.path.dirname(__file__))
        test_docs_dir = os.path.join(tests_dir, "docs")

        # populate content
        copy_tree(test_docs_dir, temp_dir)

        yield temp_dir


@pytest.fixture
def get_glob_filtered_temp_docs_dir(temp_docs_dir):
    """
    This fixture provides function that returns a path to a temp docs directory
    based on tests/docs, but filtered to only retain .rst files globbed by
    provide glob_patterns relative to the source/ directory.

    Note that to test specific documents, including those that are expected to
    raise errors, we could use the Sphinx configuration "include_patterns".
    Sadly its only available in Sphinx 5.1+ so it would constrain us to test
    against Sphinx 5.1+. Due to that, we rely on this fixture instead.
    """

    def _filter_source_dir_func(glob_patterns):
        old_cwd = os.getcwd()
        try:
            os.chdir(os.path.join(temp_docs_dir, "source"))
            source_rst_files = set(glob.glob("**/*.rst", recursive=True))
            files_to_retain = set()
            for p in glob_patterns:
                files_to_retain = files_to_retain.union(
                    set(glob.glob(p, recursive=True))
                )

            if not source_rst_files.intersection(files_to_retain):
                print("glob_patterns", glob_patterns)
                print("source_rst_files", source_rst_files)
                print("files_to_retain", files_to_retain)
                raise ValueError(
                    "provided glob_patterns found no .rst in the source folder to retain!"
                )

            for f in source_rst_files.difference(files_to_retain):
                os.remove(f)

            print()
            print(
                f"Fixture get_glob_filtered_temp_docs_dir provided the directory {temp_docs_dir}:"
            )
            for f in glob.glob("**/*.rst", recursive=True):
                print(f"- {f}")
            print()
        finally:
            os.chdir(old_cwd)
        return temp_docs_dir

    yield _filter_source_dir_func
autodoc-traits-1.2.2/tests/docs/000077500000000000000000000000001460771436200165625ustar00rootroot00000000000000autodoc-traits-1.2.2/tests/docs/sample_module.py000066400000000000000000000065711460771436200217730ustar00rootroot00000000000000"""
sample_module docstring

This module provides a module and classes with and without traits to test
autodoc_traits against. It does not contain tests.
"""

from traitlets import Bool, Dict, Instance, Integer, Unicode, Union
from traitlets.config.configurable import Configurable


class SampleConfigurable(Configurable):
    """SampleConfigurable docstring"""

    non_trait = False

    @property
    def non_trait_property(self):
        """non_trait_property docstring"""

    trait = Bool(
        help="""trait help text""",
        config=True,
    )
    trait_nohelp = Bool(
        config=True,
    )
    trait_noconfig = Bool(
        help="""trait_noconfig help text""",
    )

    def method(self):
        """method docstring"""


class SampleConfigurableSubclass(SampleConfigurable):
    """SampleConfigurableSubclass docstring"""

    subclass_non_trait = False

    @property
    def subclass_non_trait_property(self):
        """subclass_non_trait_property docstring"""

    subclass_trait = Bool(
        config=True,
        help="""subclass_trait help text""",
    )
    subclass_trait_nohelp = Bool(
        config=True,
    )
    subclass_trait_noconfig = Bool(
        help="""subclass_trait_noconfig help text""",
    )

    def subclass_method(self):
        """subclass_method docstring"""


class SampleNonConfigurable:
    """SampleNonConfigurable docstring"""

    non_trait = False

    @property
    def non_trait_property(self):
        """non_trait_property docstring"""

    def method(self):
        """method docstring"""


class SampleNonConfigurableSubclass(SampleNonConfigurable):
    """SampleNonConfigurableSubclass docstring"""

    non_trait = False

    @property
    def subclass_non_trait_property(self):
        """subclass_non_trait_property docstring"""

    def subclass_method(self):
        """subclass_method docstring"""


class TraitTypesSampleConfigurable(Configurable):
    """TraitTypesSampleConfigurable docstring"""

    trait_integer = Integer(
        help="""trait_integer help text""",
        config=True,
    )
    trait_integer_nohelp = Integer(
        config=True,
    )
    trait_integer_noconfig = Integer(
        help="""trait_integer_noconfig help text""",
    )

    trait_unicode = Unicode(
        help="""trait_unicode help text""",
        config=True,
    )
    trait_unicode_nohelp = Unicode(
        config=True,
    )
    trait_unicode_noconfig = Unicode(
        help="""trait_unicode_noconfig help text""",
    )

    trait_dict = Dict(
        help="""trait_dict help text""",
        config=True,
    )
    trait_dict_nohelp = Dict(
        config=True,
    )
    trait_dict_noconfig = Dict(
        help="""trait_dict_noconfig help text""",
    )

    trait_instance = Instance(
        klass=SampleConfigurable,
        help="""trait_instance help text""",
        config=True,
    )
    trait_instance_nohelp = Instance(
        klass=SampleConfigurable,
        config=True,
    )
    trait_instance_noconfig = Instance(
        klass=SampleConfigurable,
        help="""trait_instance_noconfig help text""",
    )

    trait_union = Union(
        [Integer(), Unicode()],
        help="""trait_union help text""",
        config=True,
    )
    trait_union_nohelp = Union(
        [Integer(), Unicode()],
        config=True,
    )
    trait_union_noconfig = Union(
        [Integer(), Unicode()],
        help="""trait_union_noconfig help text""",
    )
autodoc-traits-1.2.2/tests/docs/source/000077500000000000000000000000001460771436200200625ustar00rootroot00000000000000autodoc-traits-1.2.2/tests/docs/source/autoclass/000077500000000000000000000000001460771436200220605ustar00rootroot00000000000000autodoc-traits-1.2.2/tests/docs/source/autoclass/members.rst000066400000000000000000000003711460771436200242450ustar00rootroot00000000000000autoclass - members
===================

The ``members`` option without specified members should present all class
members.

In this test expect no trait members to show up.

.. autoclass:: sample_module.SampleConfigurable
   :noindex:
   :members:
autodoc-traits-1.2.2/tests/docs/source/autoclass/undoc_members.rst000066400000000000000000000005561460771436200254420ustar00rootroot00000000000000autoclass - undoc-members
=========================

The ``members`` and ``undoc-members`` option combined should present all class
members, including the traits. And with autodoc_traits installed, the attributes
should be presented with their help strings as docstrings.

.. autoclass:: sample_module.SampleConfigurable
   :noindex:
   :members:
   :undoc-members:
autodoc-traits-1.2.2/tests/docs/source/autoconfigurable/000077500000000000000000000000001460771436200234135ustar00rootroot00000000000000autodoc-traits-1.2.2/tests/docs/source/autoconfigurable/exclude_members.rst000066400000000000000000000010021460771436200273010ustar00rootroot00000000000000autoconfigurable - exclude-members
==================================

The ``exclude-members`` option should work to exclude specific members, trait
members and and non-traits members alike.

In this test we provide ``members`` and then exclude the members ``trait``
and ``method`` by specifying them with ``exclude-members`` that otherwise ought
to show up, and check that they aren't showing up.

.. autoconfigurable:: sample_module.SampleConfigurable
   :noindex:
   :members:
   :exclude-members: trait,method
autodoc-traits-1.2.2/tests/docs/source/autoconfigurable/inherited_members.rst000066400000000000000000000005141460771436200276320ustar00rootroot00000000000000autoconfigurable - inherited-members
====================================

With the ``inherited-members`` option, we expect traits from the superclass
SampleConfigurable to show up as well as traits from SampleConfigurableSubclass.

.. autoconfigurable:: sample_module.SampleConfigurableSubclass
   :noindex:
   :inherited-members:
autodoc-traits-1.2.2/tests/docs/source/autoconfigurable/members.rst000066400000000000000000000005271460771436200256030ustar00rootroot00000000000000autoconfigurable - members
==========================

The ``members`` option without specified members should present all class
members.

In this test expect all trait members with ``.config(True)`` to show up, even
those inherited from super classes.

.. autoconfigurable:: sample_module.SampleConfigurableSubclass
   :noindex:
   :members:
autodoc-traits-1.2.2/tests/docs/source/autoconfigurable/no_members.rst000066400000000000000000000005741460771436200263010ustar00rootroot00000000000000autoconfigurable - no members
=============================

Without the ``members`` option, one may expect no members to show up, but we
present all configurable traits still, including inherited configurable traits,
see `Issue27`_.

.. _Issue27: https://github.com/jupyterhub/autodoc-traits/issues/27

.. autoconfigurable:: sample_module.SampleConfigurableSubclass
   :noindex:
autodoc-traits-1.2.2/tests/docs/source/autoconfigurable/non_configurable_raises_error.rst000066400000000000000000000005551460771436200322430ustar00rootroot00000000000000autoconfigurable - non configurable class
=========================================

Test that we error when used on non-configurable classes.

.. note::
   This file is targeted by ``exclude_patterns`` in ``source/conf.py``
   to avoid failing unless we want to explicitly test such failure.

.. autoconfigurable:: sample_module.SampleNonConfigurable
   :noindex:
autodoc-traits-1.2.2/tests/docs/source/autoconfigurable/specified_members.rst000066400000000000000000000010061460771436200276070ustar00rootroot00000000000000autoconfigurable - specified members
====================================

The ``members`` option with specified members should only present the specified
members.

In this test we list the member ``method`` and ``trait_nohelp``. One may expect
no members besides these to show up, but we present them and all trait members
still, see `Issue27`_.

.. _Issue27: https://github.com/jupyterhub/autodoc-traits/issues/27

.. autoconfigurable:: sample_module.SampleConfigurable
   :noindex:
   :members: method,trait_nohelp
autodoc-traits-1.2.2/tests/docs/source/automodule/000077500000000000000000000000001460771436200222405ustar00rootroot00000000000000autodoc-traits-1.2.2/tests/docs/source/automodule/members.rst000066400000000000000000000003441460771436200244250ustar00rootroot00000000000000automodule - members
====================

Test that we can present a module with a mix of traitlets configurable member
classes and normal classes, and they all show up.

.. automodule:: sample_module
   :noindex:
   :members:
autodoc-traits-1.2.2/tests/docs/source/autotrait/000077500000000000000000000000001460771436200220765ustar00rootroot00000000000000autodoc-traits-1.2.2/tests/docs/source/autotrait/help.rst000066400000000000000000000011051460771436200235550ustar00rootroot00000000000000autotrait - help
================

Test that we present the trait's provided ``help``.

.. autotrait:: sample_module.SampleConfigurable.trait
   :noindex:

.. autotrait:: sample_module.TraitTypesSampleConfigurable.trait_integer
   :noindex:

.. autotrait:: sample_module.TraitTypesSampleConfigurable.trait_unicode
   :noindex:

.. autotrait:: sample_module.TraitTypesSampleConfigurable.trait_dict
   :noindex:

.. autotrait:: sample_module.TraitTypesSampleConfigurable.trait_instance
   :noindex:

.. autotrait:: sample_module.TraitTypesSampleConfigurable.trait_union
   :noindex:
autodoc-traits-1.2.2/tests/docs/source/autotrait/noconfig.rst000066400000000000000000000003541460771436200244340ustar00rootroot00000000000000autotrait - no config
=====================

Test that we still present a trait without ``config=True`` if directly requested
via the ``autotrait`` directive.

.. autotrait:: sample_module.SampleConfigurable.trait_noconfig
   :noindex:
autodoc-traits-1.2.2/tests/docs/source/autotrait/nohelp.rst000066400000000000000000000006721460771436200241220ustar00rootroot00000000000000autotrait - no help
===================

Test that we fall back to present the trait's header even if it lacks a ``help``
string.

.. note::

   This may include the missing help string message
   if built together with autoconfigurable,
   which patches config=True traits to have a truthy help string.
   This is unrealistic in real docs, but also fairly harmless.

.. autotrait:: sample_module.SampleConfigurable.trait_nohelp
   :noindex:
autodoc-traits-1.2.2/tests/docs/source/autotrait/non_trait_raises_error.rst000066400000000000000000000005251460771436200274060ustar00rootroot00000000000000autotrait - non trait attribute
===============================

Test that we error when used on non-trait attributes.

.. note::
   This file is targeted by ``exclude_patterns`` in ``source/conf.py``
   to avoid failing unless we want to explicitly test such failure.

.. autotrait:: sample_module.SampleConfigurable.non_trait
   :noindex:
autodoc-traits-1.2.2/tests/docs/source/conf.py000066400000000000000000000012151460771436200213600ustar00rootroot00000000000000import os
import sys

project = "autodoc_traits tests"
extensions = [
    "autodoc_traits",
    # sphinx.ext.napoleon is added to avoid warnings if testing with
    # :inherited-members:` where the super classe traitlets.HasTraits has numpy
    # or google-format docstrings that the napoleon can help interpret.
    "sphinx.ext.napoleon",
]

# ensure sample_module.py is on path
tests_dir = os.path.join(os.path.dirname(__file__), "..")
tests_dir = os.path.abspath(tests_dir)
sys.path.insert(0, tests_dir)

# Don't parse .rst documents expected to raise an error unless we want to test
# that specifically.
exclude_patterns = ["**/*_raises_error.rst"]
autodoc-traits-1.2.2/tests/docs/source/index.rst000066400000000000000000000003101460771436200217150ustar00rootroot00000000000000autodoc_traits tests
====================

.. toctree ref: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree
.. toctree::
   :maxdepth: 2
   :glob:

   */*
autodoc-traits-1.2.2/tests/test_autodoc_traits.py000066400000000000000000000116271460771436200222760ustar00rootroot00000000000000import os
import subprocess

import pytest


def test_sphinx_build_all_docs(temp_docs_dir, monkeypatch):
    """
    Tests that the docs folder builds without warnings.
    """
    monkeypatch.chdir(temp_docs_dir)

    subprocess.run(
        ["sphinx-build", "--color", "-W", "--keep-going", "source", "build"],
        check=True,
        text=True,
    )


@pytest.mark.parametrize(
    "rst_file_to_test, strings_in_html, strings_not_in_html",
    [
        (
            "autoclass/members.rst",
            [
                "c.SampleConfigurable.trait",
                "trait_noconfig",
            ],
            [
                "c.SampleConfigurable.trait_nohelp",
            ],
        ),
        (
            "autoclass/undoc_members.rst",
            [
                "c.SampleConfigurable.trait",
                "c.SampleConfigurable.trait_nohelp",
            ],
            [],
        ),
        (
            "autoconfigurable/exclude_members.rst",
            ["c.SampleConfigurable.trait_nohelp"],
            [
                "trait help text",
                "method docstring",
            ],
        ),
        (
            "autoconfigurable/inherited_members.rst",
            [
                "c.SampleConfigurableSubclass.trait",
                "c.SampleConfigurableSubclass.subclass_trait",
                "trait_noconfig",
                "method docstring",
            ],
            [],
        ),
        (
            "autoconfigurable/members.rst",
            [
                "c.SampleConfigurableSubclass.subclass_trait",
                "c.SampleConfigurableSubclass.trait_nohelp",
                "trait_noconfig",
                "No help string is provided.",
                "c.SampleConfigurableSubclass.trait",
                "method docstring",
            ],
            [
                "c.SampleConfigurableSubclass.trait_noconfig",
            ],
        ),
        (
            "autoconfigurable/no_members.rst",
            [
                "c.SampleConfigurableSubclass.subclass_trait",
                "c.SampleConfigurableSubclass.trait",
            ],
            [
                "trait_noconfig",
                "method docstring",
            ],
        ),
        ("autoconfigurable/non_configurable_raises_error.rst", [], []),
        (
            "autoconfigurable/specified_members.rst",
            [
                "method docstring",
                "c.SampleConfigurable.trait_nohelp",
                "trait help text",
            ],
            [],
        ),
        (
            "automodule/members.rst",
            [
                "sample_module docstring",
                "SampleConfigurable docstring",
                "SampleConfigurableSubclass docstring",
                "SampleNonConfigurable docstring",
                "SampleNonConfigurableSubclass docstring",
                "TraitTypesSampleConfigurable docstring",
            ],
            [],
        ),
        (
            "autotrait/help.rst",
            [
                "c.SampleConfigurable.trait",
                "trait help text",
                "trait_integer help text",
                "trait_unicode help text",
                "trait_dict help text",
                "trait_instance help text",
                "trait_union help text",
            ],
            [],
        ),
        (
            "autotrait/noconfig.rst",
            [
                "trait_noconfig",
                "Bool(False)",
            ],
            [
                "c.SampleConfigurable.trait_noconfig",
            ],
        ),
        (
            "autotrait/nohelp.rst",
            [
                "c.SampleConfigurable.trait_nohelp",
            ],
            [
                "No help string is provided.",
            ],
        ),
        ("autotrait/non_trait_raises_error.rst", [], []),
    ],
)
def test_sphinx_build_file(
    get_glob_filtered_temp_docs_dir,
    monkeypatch,
    rst_file_to_test,
    strings_in_html,
    strings_not_in_html,
):
    """
    Tests that individual .rst documents in the docs folder builds without
    warnings, emits .html with certain strings, and emits .html without certain
    strings.
    """
    temp_docs_dir = get_glob_filtered_temp_docs_dir(["index.rst", rst_file_to_test])
    monkeypatch.chdir(temp_docs_dir)

    p = subprocess.run(
        [
            "sphinx-build",
            "--color",
            "-W",
            "--keep-going",
            "-D",
            "exclude_patterns=",
            "source",
            "build",
        ],
        text=True,
    )
    if "raises_error" in rst_file_to_test:
        assert p.returncode > 0
        return
    assert p.returncode == 0

    html_file_to_inspect = os.path.join(
        "build", rst_file_to_test.replace(".rst", ".html")
    )
    with open(html_file_to_inspect) as f:
        html = f.read()

    for s in strings_in_html:
        assert s in html

    for s in strings_not_in_html:
        assert s not in html
autodoc-traits-1.2.2/tests/test_fixtures.py000066400000000000000000000021031460771436200211100ustar00rootroot00000000000000import os


def test_temp_docs_dir(temp_docs_dir):
    """
    Verify that we get a reference to a temporary directory with source/conf.py
    in it.
    """
    assert os.path.isdir(os.path.join(temp_docs_dir, "source"))
    assert os.path.isfile(os.path.join(temp_docs_dir, "source/conf.py"))


def test_get_glob_filtered_temp_docs_dir(get_glob_filtered_temp_docs_dir):
    """
    Verify that we get a reference to a temporary directory with:
    - source/conf.py
    - index.rst files retained
    - filtered .rst files removed
    - non-filtered .rst files retained
    """
    temp_docs_dir = get_glob_filtered_temp_docs_dir(
        ["index.rst", "automodule/members.rst"]
    )
    assert os.path.isdir(os.path.join(temp_docs_dir, "source"))
    assert os.path.isfile(os.path.join(temp_docs_dir, "source/conf.py"))
    assert os.path.isfile(os.path.join(temp_docs_dir, "source/index.rst"))
    assert os.path.isfile(os.path.join(temp_docs_dir, "source/automodule/members.rst"))
    assert not os.path.isfile(
        os.path.join(temp_docs_dir, "source/autoclass/members.rst")
    )