pax_global_header00006660000000000000000000000064146345711510014521gustar00rootroot0000000000000052 comment=ce91d88c18657dc3135cdd58becfa65a0252e941 mkdocstrings-python-handlers-1.10.5/000077500000000000000000000000001463457115100174315ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/.copier-answers.yml000066400000000000000000000013421463457115100231730ustar00rootroot00000000000000# Changes here will be overwritten by Copier _commit: 1.1.2 _src_path: gh:mkdocstrings/handler-template author_email: dev@pawamoy.fr author_fullname: Timothée Mazzucotelli author_username: pawamoy copyright_date: '2021' copyright_holder: Timothée Mazzucotelli copyright_holder_email: dev@pawamoy.fr copyright_license: ISC License insiders: true insiders_email: insiders@pawamoy.fr insiders_repository_name: mkdocstrings-python language: Python project_description: A Python handler for mkdocstrings. project_name: mkdocstrings-python public_release: true python_package_distribution_name: mkdocstrings-python python_package_import_name: python repository_name: python repository_namespace: mkdocstrings repository_provider: github.com mkdocstrings-python-handlers-1.10.5/.envrc000066400000000000000000000000211463457115100205400ustar00rootroot00000000000000PATH_add scripts mkdocstrings-python-handlers-1.10.5/.github/000077500000000000000000000000001463457115100207715ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/.github/FUNDING.yml000066400000000000000000000001261463457115100226050ustar00rootroot00000000000000github: pawamoy ko_fi: pawamoy polar: pawamoy custom: - https://www.paypal.me/pawamoy mkdocstrings-python-handlers-1.10.5/.github/ISSUE_TEMPLATE/000077500000000000000000000000001463457115100231545ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/.github/ISSUE_TEMPLATE/bug_report.md000066400000000000000000000027171463457115100256550ustar00rootroot00000000000000--- name: Bug report about: Create a bug report to help us improve. title: "bug: " labels: unconfirmed assignees: [pawamoy] --- ### Description of the bug ### To Reproduce ``` WRITE MRE / INSTRUCTIONS HERE ``` ### Full traceback
Full traceback ```python PASTE TRACEBACK HERE ```
### Expected behavior ### Environment information ```bash python -m mkdocstrings_handlers.python.debug # | xclip -selection clipboard ``` PASTE OUTPUT HERE ### Additional context mkdocstrings-python-handlers-1.10.5/.github/ISSUE_TEMPLATE/config.yml000066400000000000000000000003301463457115100251400ustar00rootroot00000000000000blank_issues_enabled: false contact_links: - name: I have a question / I need help url: https://github.com/mkdocstrings/python/discussions/new?category=q-a about: Ask and answer questions in the Discussions tab. mkdocstrings-python-handlers-1.10.5/.github/ISSUE_TEMPLATE/feature_request.md000066400000000000000000000012131463457115100266760ustar00rootroot00000000000000--- name: Feature request about: Suggest an idea for this project. title: "feature: " labels: feature assignees: pawamoy --- ### Is your feature request related to a problem? Please describe. ### Describe the solution you'd like ### Describe alternatives you've considered ### Additional context mkdocstrings-python-handlers-1.10.5/.github/workflows/000077500000000000000000000000001463457115100230265ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/.github/workflows/ci.yml000066400000000000000000000051471463457115100241530ustar00rootroot00000000000000name: ci on: push: pull_request: branches: - main defaults: run: shell: bash env: LANG: en_US.utf-8 LC_ALL: en_US.utf-8 PYTHONIOENCODING: UTF-8 PYTHON_VERSIONS: "" jobs: quality: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Fetch all tags run: git fetch --depth=1 --tags - name: Set up Python uses: actions/setup-python@v5 with: python-version: "3.11" - name: Install uv run: pip install uv - name: Install dependencies run: make setup - name: Check if the documentation builds correctly run: make check-docs - name: Check the code quality run: make check-quality - name: Check if the code is correctly typed run: make check-types - name: Check for breaking changes in the API run: make check-api exclude-test-jobs: runs-on: ubuntu-latest outputs: jobs: ${{ steps.exclude-jobs.outputs.jobs }} steps: - id: exclude-jobs run: | if ${{ github.repository_owner == 'pawamoy-insiders' }}; then echo 'jobs=[ {"os": "macos-latest"}, {"os": "windows-latest"}, {"python-version": "3.9"}, {"python-version": "3.10"}, {"python-version": "3.11"}, {"python-version": "3.12"}, {"python-version": "3.13"} ]' | tr -d '[:space:]' >> $GITHUB_OUTPUT else echo 'jobs=[ {"os": "macos-latest", "resolution": "lowest-direct"}, {"os": "windows-latest", "resolution": "lowest-direct"} ]' | tr -d '[:space:]' >> $GITHUB_OUTPUT fi tests: needs: exclude-test-jobs strategy: max-parallel: 4 matrix: os: - ubuntu-latest - macos-latest - windows-latest python-version: - "3.8" - "3.9" - "3.10" - "3.11" - "3.12" - "3.13" resolution: - highest - lowest-direct exclude: ${{ fromJSON(needs.exclude-test-jobs.outputs.jobs) }} runs-on: ${{ matrix.os }} continue-on-error: ${{ matrix.python-version == '3.13' }} steps: - name: Checkout uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} allow-prereleases: true - name: Install uv run: pip install uv - name: Install dependencies env: UV_RESOLUTION: ${{ matrix.resolution }} run: make setup - name: Run the test suite run: make test mkdocstrings-python-handlers-1.10.5/.github/workflows/release.yml000066400000000000000000000025461463457115100252000ustar00rootroot00000000000000name: release on: push permissions: contents: write jobs: release: runs-on: ubuntu-latest if: startsWith(github.ref, 'refs/tags/') steps: - name: Checkout uses: actions/checkout@v4 - name: Fetch all tags run: git fetch --depth=1 --tags - name: Setup Python uses: actions/setup-python@v4 - name: Install build if: github.repository_owner == 'pawamoy-insiders' run: python -m pip install build - name: Build dists if: github.repository_owner == 'pawamoy-insiders' run: python -m build - name: Upload dists artifact uses: actions/upload-artifact@v4 if: github.repository_owner == 'pawamoy-insiders' with: name: python-insiders path: ./dist/* - name: Install git-changelog if: github.repository_owner != 'pawamoy-insiders' run: pip install git-changelog - name: Prepare release notes if: github.repository_owner != 'pawamoy-insiders' run: git-changelog --release-notes > release-notes.md - name: Create release with assets uses: softprops/action-gh-release@v1 if: github.repository_owner == 'pawamoy-insiders' with: files: ./dist/* - name: Create release uses: softprops/action-gh-release@v1 if: github.repository_owner != 'pawamoy-insiders' with: body_path: release-notes.md mkdocstrings-python-handlers-1.10.5/.gitignore000066400000000000000000000003211463457115100214150ustar00rootroot00000000000000# editors .idea/ .vscode/ # python *.egg-info/ *.py[cod] .venv/ .venvs/ /build/ /dist/ # tools .coverage* /.pdm-build/ /htmlcov/ /site/ # cache .cache/ .pytest_cache/ .mypy_cache/ .ruff_cache/ __pycache__/ mkdocstrings-python-handlers-1.10.5/.gitpod.dockerfile000066400000000000000000000001731463457115100230270ustar00rootroot00000000000000FROM gitpod/workspace-full USER gitpod ENV PIP_USER=no RUN pip3 install pipx; \ pipx install uv; \ pipx ensurepath mkdocstrings-python-handlers-1.10.5/.gitpod.yml000066400000000000000000000002171463457115100215200ustar00rootroot00000000000000vscode: extensions: - ms-python.python image: file: .gitpod.dockerfile ports: - port: 8000 onOpen: notify tasks: - init: make setup mkdocstrings-python-handlers-1.10.5/CHANGELOG.md000066400000000000000000001234371463457115100212540ustar00rootroot00000000000000# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). ## [1.10.5](https://github.com/mkdocstrings/python/releases/tag/1.10.5) - 2024-06-19 [Compare with 1.10.4](https://github.com/mkdocstrings/python/compare/1.10.4...1.10.5) ### Bug Fixes - Mix both previous checks for displaying objects: not imported or public ([587963b](https://github.com/mkdocstrings/python/commit/587963ba53f765c9d7eefbc2fb80bdbb11164850) by Timothée Mazzucotelli). [Issue-294](https://github.com/mkdocstrings/griffe/issues/294) ## [1.10.4](https://github.com/mkdocstrings/python/releases/tag/1.10.4) - 2024-06-18 [Compare with 1.10.3](https://github.com/mkdocstrings/python/compare/1.10.3...1.10.4) ### Code Refactoring - Only filter out imported objects instead of non-public ones after applying filters ([e2f4b35](https://github.com/mkdocstrings/python/commit/e2f4b35d29eca6f68afbd2e728ef7542a2abc992) by Timothée Mazzucotelli). [Issue-mkdocstrings/griffe-294](https://github.com/mkdocstrings/griffe/issues/294) - Update code for Griffe 0.46 to avoid deprecation warnings ([321b407](https://github.com/mkdocstrings/python/commit/321b407eb95195c44f3cf34d780784e0d6751998) by Timothée Mazzucotelli). - Change `load_external_modules` default value to `None` to support new default mode in Griffe ([ae5896c](https://github.com/mkdocstrings/python/commit/ae5896c1604e9089162d0d63ec97a510a6bcef89) by Timothée Mazzucotelli). ## [1.10.3](https://github.com/mkdocstrings/python/releases/tag/1.10.3) - 2024-05-22 [Compare with 1.10.2](https://github.com/mkdocstrings/python/compare/1.10.2...1.10.3) ### Bug Fixes - Don't crash when rendering the source of an object whose lineno is none ([64df00b](https://github.com/mkdocstrings/python/commit/64df00b9b757e9642d65cf425d32f5a2e0d75f38) by Timothée Mazzucotelli). [Issue-163](https://github.com/mkdocstrings/python/issues/163) ## [1.10.2](https://github.com/mkdocstrings/python/releases/tag/1.10.2) - 2024-05-16 [Compare with 1.10.1](https://github.com/mkdocstrings/python/compare/1.10.1...1.10.2) ### Bug Fixes - Actually make use of custom .html.jinja templates ([5668abb](https://github.com/mkdocstrings/python/commit/5668abba15b13b86fe67f70f6b4004b7b1feeb4f) by Timothée Mazzucotelli). ## [1.10.1](https://github.com/mkdocstrings/python/releases/tag/1.10.1) - 2024-05-14 [Compare with 1.10.0](https://github.com/mkdocstrings/python/compare/1.10.0...1.10.1) ### Build - Depend on mkdocstrings 0.25 which adds support for parameter `once` when logging messages ([2bc156b](https://github.com/mkdocstrings/python/commit/2bc156bd6f231ae13066651f4490d1e9c2ce3ca2) by Timothée Mazzucotelli). ### Code Refactoring - Set handler's name ([a71ab12](https://github.com/mkdocstrings/python/commit/a71ab12c8e52efe76e5c0a5e54065926a47cc0d2) by Timothée Mazzucotelli). - Update `*.html` top-level templates to extend the `*.html.jinja` base templates ([a8c540e](https://github.com/mkdocstrings/python/commit/a8c540e95693e8500da884c32ad159b3bbaaa7ba) by Timothée Mazzucotelli). [Issue-151](https://github.com/mkdocstrings/python/issues/151) - Update `*.html` base templates to extend their `*.html.jinja` counterpart, while overriding the `logs` block to issue a logging message (info) stating that extending `*.html` templates is deprecated ([e6f1b9c](https://github.com/mkdocstrings/python/commit/e6f1b9caf13754eca9dbb2f112727bef50876ed7) by Timothée Mazzucotelli). [Issue-151](https://github.com/mkdocstrings/python/issues/151) - Add `*.html.jinja` top-level (overridable) templates, extending their base counterpart ([7c14924](https://github.com/mkdocstrings/python/commit/7c14924c406d7b5f4f1c22d03019d4c566018d2d) by Timothée Mazzucotelli). [Issue-151](https://github.com/mkdocstrings/python/issues/151) - Add `*.html.jinja` base templates, which are copies of `*.html` templates, with an additional `logs` block, and using the updated `get_template` filter ([eced9a5](https://github.com/mkdocstrings/python/commit/eced9a54fc8a559b686cb1b1180a0d2e04ba452d) by Timothée Mazzucotelli). [Issue-151](https://github.com/mkdocstrings/python/issues/151) - Update `get_template` filter to support both `*.html` and `*.html.jinja` templates, logging a message (info) when `*.html` templates are overridden by users ([3546fd7](https://github.com/mkdocstrings/python/commit/3546fd70b2d4e45f77b166b2e67c333acc8af0d2) by Timothée Mazzucotelli). [Issue-151](https://github.com/mkdocstrings/python/issues/151) - Log a warning when base templates are overridden ([26e3d66](https://github.com/mkdocstrings/python/commit/26e3d66f5334a5aaff75bda030afe6dfa1cc94d7) by Timothée Mazzucotelli). [Issue-151](https://github.com/mkdocstrings/python/issues/151) ## [1.10.0](https://github.com/mkdocstrings/python/releases/tag/1.10.0) - 2024-04-19 [Compare with 1.9.2](https://github.com/mkdocstrings/python/compare/1.9.2...1.10.0) ### Features - Add CSS classes `doc-section-title` and `doc-section-item` in docstring sections ([d6e1d68](https://github.com/mkdocstrings/python/commit/d6e1d68c099e61c3bd6d93e583708335d84158f5) by Timothée Mazzucotelli). [Issue-17](https://github.com/mkdocstrings/python/issues/17) ### Bug Fixes - Render enumeration instance name instead of just "value", allowing proper cross-reference ([11d81d8](https://github.com/mkdocstrings/python/commit/11d81d8e056b7c074eb3a1c47606867156a338fa) by Timothée Mazzucotelli). [Issue-124](https://github.com/mkdocstrings/python/issues/124) ## [1.9.2](https://github.com/mkdocstrings/python/releases/tag/1.9.2) - 2024-04-02 [Compare with 1.9.1](https://github.com/mkdocstrings/python/compare/1.9.1...1.9.2) ### Dependencies - Remove cap on Python-Markdown 3.6 now that ToC labels are fixed by mkdocstrings ([0c1e2c1](https://github.com/mkdocstrings/python/commit/0c1e2c15b2497d99974cbb9bd68f25056bb8451b) by Timothée Mazzucotelli). ## [1.9.1](https://github.com/mkdocstrings/python/releases/tag/1.9.1) - 2024-04-02 [Compare with 1.9.0](https://github.com/mkdocstrings/python/compare/1.9.0...1.9.1) ### Bug Fixes - Don't try loading packages from relative paths ([bd73497](https://github.com/mkdocstrings/python/commit/bd7349714059afb1295e743dbc82380fa797a032) by Timothée Mazzucotelli). [Issue-145](https://github.com/mkdocstrings/python/issues/145) ### Code Refactoring - Allow first name in a separate signature to be highlighted as a function name ([f798a1e](https://github.com/mkdocstrings/python/commit/f798a1e19dbac548420dcbe1172e9a49232b615b) by Timothée Mazzucotelli). - Maintain original Pygments color for cross-refs in signatures ([7c8b885](https://github.com/mkdocstrings/python/commit/7c8b885fa2b704e719016acb35791723ea3a496a) by Timothée Mazzucotelli). ## [1.9.0](https://github.com/mkdocstrings/python/releases/tag/1.9.0) - 2024-03-13 [Compare with 1.8.0](https://github.com/mkdocstrings/python/compare/1.8.0...1.9.0) ### Dependencies - Add upper bound on Python-Markdown 3.6 to temporarily prevent breaking changes ([cd93ee3](https://github.com/mkdocstrings/python/commit/cd93ee31418a2752667d43bb5a05d22284522c24) by Timothée Mazzucotelli). ### Features - Add `show_labels` option to show/hide labels ([eaf9b82](https://github.com/mkdocstrings/python/commit/eaf9b8240069f7369f401fe048892043c8b173d3) by Viicos). [Issue #120](https://github.com/mkdocstrings/python/issues/120), [PR #130](https://github.com/mkdocstrings/python/pull/130) - Add option to search for stubs packages ([0c6aa32](https://github.com/mkdocstrings/python/commit/0c6aa323c9e57b8348765a5daa11c79d0c5edb07) by Romain). [PR #128](https://github.com/mkdocstrings/python/pull/128), PR griffe#221: : https://github.com/mkdocstrings/griffe/pull/221 ### Code Refactoring - Mark all Jinja blocks as scoped ([548bdad](https://github.com/mkdocstrings/python/commit/548bdaddd66ffc99b3b9a5a62228a2ff4ff0dd00) by Timothée Mazzucotelli). ## [1.8.0](https://github.com/mkdocstrings/python/releases/tag/1.8.0) - 2024-01-08 [Compare with 1.7.5](https://github.com/mkdocstrings/python/compare/1.7.5...1.8.0) ### Features - Release Insiders features of the $500/month funding goal ([bd30106](https://github.com/mkdocstrings/python/commit/bd301061fe9c647f9b91c2c9b4baa784c304eca7) by Timothée Mazzucotelli). The features and projects related to *mkdocstrings-python* are: - [Cross-references for type annotations in signatures](https://mkdocstrings.github.io/python/usage/configuration/signatures/#signature_crossrefs) - [Symbol types in headings and table of contents](https://mkdocstrings.github.io/python/usage/configuration/headings/#show_symbol_type_toc) - [`griffe-inherited-docstrings`](https://mkdocstrings.github.io/griffe-inherited-docstrings/), a Griffe extension for inheriting docstrings - [`griffe2md`](https://mkdocstrings.github.io/griffe2md/), a tool to output API docs to Markdown using Griffe See the complete list of features and projects here: https://pawamoy.github.io/insiders/#500-plasmavac-user-guide. ## [1.7.5](https://github.com/mkdocstrings/python/releases/tag/1.7.5) - 2023-11-21 [Compare with 1.7.4](https://github.com/mkdocstrings/python/compare/1.7.4...1.7.5) ### Bug Fixes - Add missing translations (fallback theme) for ReadTheDocs ([2fb6513](https://github.com/mkdocstrings/python/commit/2fb651304d0a80fa9d6a8c77c16b3004bda22972) by Timothée Mazzucotelli). [Issue #115](https://github.com/mkdocstrings/python/issues/115) ## [1.7.4](https://github.com/mkdocstrings/python/releases/tag/1.7.4) - 2023-11-12 [Compare with 1.7.3](https://github.com/mkdocstrings/python/compare/1.7.3...1.7.4) ### Bug Fixes - Make extension paths relative to config file ([5035e92](https://github.com/mkdocstrings/python/commit/5035e9269fe11664fd25e438ac8f746721b3de0a) by Waylan Limberg). [PR #112](https://github.com/mkdocstrings/python/pull/112), Co-authored-by: Timothée Mazzucotelli ### Code Refactoring - Prepare for Griffe 0.37 ([b5bb8a9](https://github.com/mkdocstrings/python/commit/b5bb8a982e7a2ec97c73335e453d0033bf4987b6) by Timothée Mazzucotelli). ## [1.7.3](https://github.com/mkdocstrings/python/releases/tag/1.7.3) - 2023-10-09 [Compare with 1.7.2](https://github.com/mkdocstrings/python/compare/1.7.2...1.7.3) ### Bug Fixes - Don't deepcopy the local config ([1300d2c](https://github.com/mkdocstrings/python/commit/1300d2c77dd49f5dea459ad844d72edcc856c4cd) by Timothée Mazzucotelli). ## [1.7.2](https://github.com/mkdocstrings/python/releases/tag/1.7.2) - 2023-10-05 [Compare with 1.7.1](https://github.com/mkdocstrings/python/compare/1.7.1...1.7.2) ### Bug Fixes - Prevent alias resolution error when source-ordering members ([67df10c](https://github.com/mkdocstrings/python/commit/67df10cbb86225e1e3efc251325cbff883a1ef3c) by Timothée Mazzucotelli). [Issue griffe#213](https://github.com/mkdocstrings/griffe/issues/213) ### Code Refactoring - Use package relative filepath if filepath is not relative ([aa5a3f7](https://github.com/mkdocstrings/python/commit/aa5a3f7b0928498ba9da10ed1211d1e55b7f6c4b) by Timothée Mazzucotelli). [Discussion mkdocstrings#622](https://github.com/mkdocstrings/mkdocstrings/discussions/622) ## [1.7.1](https://github.com/mkdocstrings/python/releases/tag/1.7.1) - 2023-09-28 [Compare with 1.7.0](https://github.com/mkdocstrings/python/compare/1.7.0...1.7.1) ### Bug Fixes - Stop propagation of annotation to next parameter in signature template ([3a760ac](https://github.com/mkdocstrings/python/commit/3a760acacfabaef5abc658ee579e1c205e674994) by Timothée Mazzucotelli). [Issue #110](https://github.com/mkdocstrings/python/issues/110) ### Code Refactoring - Look into inherited members for `__init__` methods when merging docstrings ([b97d51f](https://github.com/mkdocstrings/python/commit/b97d51f67c2ee3d1edfe6975274ead50fcb3fa8f) by Timothée Mazzucotelli). [Issue #106](https://github.com/mkdocstrings/python/issues/106) ## [1.7.0](https://github.com/mkdocstrings/python/releases/tag/1.7.0) - 2023-09-14 [Compare with 1.6.3](https://github.com/mkdocstrings/python/compare/1.6.3...1.7.0) ### Features - Add option to unwrap `Annotated` types ([53db04b](https://github.com/mkdocstrings/python/commit/53db04b6256db960aebc2a9f91129b82ca222e41) by Timothée Mazzucotelli). ## [1.6.3](https://github.com/mkdocstrings/python/releases/tag/1.6.3) - 2023-09-11 [Compare with 1.6.2](https://github.com/mkdocstrings/python/compare/1.6.2...1.6.3) ### Bug Fixes - Make `load_external_modules` a global-only option ([266f41f](https://github.com/mkdocstrings/python/commit/266f41f2033e034060001bc2bed376b4f3a8d7b8) by Timothée Mazzucotelli). [Issue #87](https://github.com/mkdocstrings/python/issues/87) - Never fail when trying to format code with Black ([df24bbc](https://github.com/mkdocstrings/python/commit/df24bbc640886e1da2d00a3b58c1aa7736cb1eeb) by Timothée Mazzucotelli). ### Code Refactoring - Wrap docstring section elements (list style) in code tags to prevent spell checker errors ([1ae8dd8](https://github.com/mkdocstrings/python/commit/1ae8dd89cddd67c09d7d30c59b9013516cea2924) by Timothée Mazzucotelli). ## [1.6.2](https://github.com/mkdocstrings/python/releases/tag/1.6.2) - 2023-09-05 [Compare with 1.6.1](https://github.com/mkdocstrings/python/compare/1.6.1...1.6.2) ### Bug Fixes - Don't render cross-ref spans when they're not enabled ([eed51ee](https://github.com/mkdocstrings/python/commit/eed51ee14bd973a08395f95377f9bd4cd38febfc) by Timothée Mazzucotelli). ## [1.6.1](https://github.com/mkdocstrings/python/releases/tag/1.6.1) - 2023-09-04 [Compare with 1.6.0](https://github.com/mkdocstrings/python/compare/1.6.0...1.6.1) ### Bug Fixes - Fix spacing for rendered named items in Yields, Receives and Returns sections (list style) ([e12688e](https://github.com/mkdocstrings/python/commit/e12688ecb7d868047f794300eb2638d052563e68) by Timothée Mazzucotelli). - Fix rendering Receives sections as lists ([9ff7e68](https://github.com/mkdocstrings/python/commit/9ff7e68b58e2ab0829c73e4e62254325a4f766ac) by Timothée Mazzucotelli). ## [1.6.0](https://github.com/mkdocstrings/python/releases/tag/1.6.0) - 2023-08-27 [Compare with 1.5.2](https://github.com/mkdocstrings/python/compare/1.5.2...1.6.0) ### Features - Add `doc-signature` CSS class to separate signature code blocks ([b6c648f](https://github.com/mkdocstrings/python/commit/b6c648f554f2e0dce609afc2a2c1a3b27a4fbeba) by Timothée Mazzucotelli). ### Code Refactoring - Add a `format_attribute` filter, preparing for cross-refs in attribute signatures ([8f0ade2](https://github.com/mkdocstrings/python/commit/8f0ade249638ee2f2d446f083c70b6c30799875a) by Timothée Mazzucotelli). ## [1.5.2](https://github.com/mkdocstrings/python/releases/tag/1.5.2) - 2023-08-25 [Compare with 1.5.1](https://github.com/mkdocstrings/python/compare/1.5.1...1.5.2) ### Bug Fixes - Regression in children template: fix condition for when members are specified ([beeebff](https://github.com/mkdocstrings/python/commit/beeebffa36288d1f71d122f78ecd9064b41a75d0) by Timothée Mazzucotelli). [Issue #100](https://github.com/mkdocstrings/python/issues/100) - Prevent whitespace removal before highlight filter ([c6f36c0](https://github.com/mkdocstrings/python/commit/c6f36c0c9e5141800f8c5c988c9b67720fccccb8) by Timothée Mazzucotelli). ### Code Refactoring - Never show full object path in ToC entry ([9aa758b](https://github.com/mkdocstrings/python/commit/9aa758bcc42dfcf7c416d87b8f7cd407b7fdf148) by Timothée Mazzucotelli). - Sync templates with insiders, remove useless lines ([38b317f](https://github.com/mkdocstrings/python/commit/38b317f4fc74b583a4788721a5559c51a5a47d86) by Timothée Mazzucotelli). ## [1.5.1](https://github.com/mkdocstrings/python/releases/tag/1.5.1) - 2023-08-24 [Compare with 1.5.0](https://github.com/mkdocstrings/python/compare/1.5.0...1.5.1) ### Code Refactoring - Never show full path in separate signature since it would appear in the heading already ([9e02049](https://github.com/mkdocstrings/python/commit/9e0204930cf4dc973ba8eb41c471fc0132e1631f) by Timothée Mazzucotelli). - Improve guessing whether an object is public ([35eb811](https://github.com/mkdocstrings/python/commit/35eb81162582d794f170cd7e8c68f10ecfd8ff9d) by Timothée Mazzucotelli). - Always sort modules alphabetically as source order wouldn't make sense ([70c81ce](https://github.com/mkdocstrings/python/commit/70c81cebb62366cbfc6124bc84d1563db176afb6) by Timothée Mazzucotelli). - Return anchors as a tuple, not a set, to preserve order ([736a2b5](https://github.com/mkdocstrings/python/commit/736a2b5e729d25bb184db8d42f2ad01025a5bc58) by Timothée Mazzucotelli). [Related-to #mkdocstrings/crystal#6](https://github.com/mkdocstrings/crystal/pull/6) ## [1.5.0](https://github.com/mkdocstrings/python/releases/tag/1.5.0) - 2023-08-20 [Compare with 1.4.0](https://github.com/mkdocstrings/python/compare/1.4.0...1.5.0) ### Features - Add support for new Griffe docstring sections: modules, classes, and functions (methods) ([d5337af](https://github.com/mkdocstrings/python/commit/d5337afdf68fc492b34f749aa69d1da33b49f9c2) by Timothée Mazzucotelli). ## [1.4.0](https://github.com/mkdocstrings/python/releases/tag/1.4.0) - 2023-08-18 [Compare with 1.3.0](https://github.com/mkdocstrings/python/compare/1.3.0...1.4.0) ### Features - Support new Griffe expressions (in v0.33) ([9b8e1b1](https://github.com/mkdocstrings/python/commit/9b8e1b1604b978cf2d89b7abf826cf4407f92394) by Timothée Mazzucotelli). ### Code Refactoring - Deprecate `crossref` and `multi_crossref` filters ([4fe3d20](https://github.com/mkdocstrings/python/commit/4fe3d2051047061780e20683da6513a7c8d91829) by Timothée Mazzucotelli). ## [1.3.0](https://github.com/mkdocstrings/python/releases/tag/1.3.0) - 2023-08-06 [Compare with 1.2.1](https://github.com/mkdocstrings/python/compare/1.2.1...1.3.0) ### Dependencies - Set upper bound on Griffe (0.33) ([ad8c2a3](https://github.com/mkdocstrings/python/commit/ad8c2a3ac8daf0b0c06579b6ba667e05feffa247) by Timothée Mazzucotelli). See https://github.com/mkdocstrings/griffe/discussions/195. ### Features - Show parameter default values within the "list" section style too ([55f08f3](https://github.com/mkdocstrings/python/commit/55f08f3e2cece815dd79d35c82515ba8003ec64c) by Antoine Dechaume). [PR #92](https://github.com/mkdocstrings/python/pull/92), Co-authored-by: Timothée Mazzucotelli ## [1.2.1](https://github.com/mkdocstrings/python/releases/tag/1.2.1) - 2023-07-20 [Compare with 1.2.0](https://github.com/mkdocstrings/python/compare/1.2.0...1.2.1) ### Bug Fixes - Fix members ordering when members are specified with a boolean ([c69f9c3](https://github.com/mkdocstrings/python/commit/c69f9c3b3ddde915619eded6620f7ddada977b00) by Timothée Mazzucotelli). [Issue #89](https://github.com/mkdocstrings/python/issues/89) ## [1.2.0](https://github.com/mkdocstrings/python/releases/tag/1.2.0) - 2023-07-14 [Compare with 1.1.2](https://github.com/mkdocstrings/python/compare/1.1.2...1.2.0) ### Features - Add Jinja blocks to module, class, function and attribute templates ([299fe48](https://github.com/mkdocstrings/python/commit/299fe483cc03ba76df29b843f88467f89db6dc72) by Timothée Mazzucotelli). - Setup infrastructure for I18N, add translations for simplified chinese and japanese ([b053b29](https://github.com/mkdocstrings/python/commit/b053b2900ef5c0069b68ad19bda9aaa98141a525) by Nyuan Zhang). [PR #77](https://github.com/mkdocstrings/python/pull/77) - Support inheritance ([ae42356](https://github.com/mkdocstrings/python/commit/ae4235689155a4b4f0c1e74b0014a466c6b1181f) by Timothée Mazzucotelli). [Issue mkdocstrings#157](https://github.com/mkdocstrings/mkdocstrings/issues/157), [Discussion mkdocstrings#536](https://github.com/mkdocstrings/mkdocstrings/discussions/536) ### Bug Fixes - Don't show `None` as return annotation of class signatures ([3d8724e](https://github.com/mkdocstrings/python/commit/3d8724ed1f4d040d7a3d9d02784cf0d1f80445b2) by Timothée Mazzucotelli). [Issue #85](https://github.com/mkdocstrings/python/issues/85) - Show labels in deterministic order ([02619a8](https://github.com/mkdocstrings/python/commit/02619a85ee4aab25f3241d983bdfff0534dd3f81) by Oleh Prypin). ## [1.1.2](https://github.com/mkdocstrings/python/releases/tag/1.1.2) - 2023-06-04 [Compare with 1.1.1](https://github.com/mkdocstrings/python/compare/1.1.1...1.1.2) ### Code Refactoring - Keep headings style consistent (CSS) ([92032e5](https://github.com/mkdocstrings/python/commit/92032e561861c3fc4e3fb0c6882bb076d0e6614d) by Timothée Mazzucotelli). ## [1.1.1](https://github.com/mkdocstrings/python/releases/tag/1.1.1) - 2023-06-04 [Compare with 1.1.0](https://github.com/mkdocstrings/python/compare/1.1.0...1.1.1) ### Bug Fixes - Fix mkdocs and readthedocs themes support ([14f18b2](https://github.com/mkdocstrings/python/commit/14f18b219f67f9b6d154d4a52051d8d7d7c49348) by Timothée Mazzucotelli). ### Code Refactoring - Improve display of paragraphs in docstring sections ([439f5e6](https://github.com/mkdocstrings/python/commit/439f5e6984fe94c28324ca57fbd1a52ef8f55b62) by Timothée Mazzucotelli). ## [1.1.0](https://github.com/mkdocstrings/python/releases/tag/1.1.0) - 2023-05-25 [Compare with 1.0.0](https://github.com/mkdocstrings/python/compare/1.0.0...1.1.0) ### Features - Support custom templates through objects' extra data ([8ff2b06](https://github.com/mkdocstrings/python/commit/8ff2b06295e848b9c84867802eb845adf061dc10) by Timothée Mazzucotelli). [PR #70](https://github.com/mkdocstrings/python/pull/70) ## [1.0.0](https://github.com/mkdocstrings/python/releases/tag/1.0.0) - 2023-05-11 [Compare with 0.10.1](https://github.com/mkdocstrings/python/compare/0.10.1...1.0.0) ### Breaking changes - The signature of the [`format_signature` filter](https://mkdocstrings.github.io/python/reference/mkdocstrings_handlers/python/rendering/#mkdocstrings_handlers.python.rendering.do_format_signature) has changed. If you override templates in your project to customize the output, make sure to update the following templates so that they use the new filter signature: - `class.html` - `expression.html` - `function.html` - `signature.html` You can see how to use the filter in this commit's changes: [f686f4e4](https://github.com/mkdocstrings/python/commit/f686f4e4599cea64686d4ef4863b507dd096a513). **We take this as an opportunity to go out of beta and bump the version to 1.0.0. This will allow users to rely on semantic versioning.** ### Bug Fixes - Bring compatibility with insiders signature crossrefs feature ([f686f4e](https://github.com/mkdocstrings/python/commit/f686f4e4599cea64686d4ef4863b507dd096a513) by Timothée Mazzucotelli). ## [0.10.1](https://github.com/mkdocstrings/python/releases/tag/0.10.1) - 2023-05-07 [Compare with 0.10.0](https://github.com/mkdocstrings/python/compare/0.10.0...0.10.1) ### Bug Fixes - Format signatures with full-path names ([685512d](https://github.com/mkdocstrings/python/commit/685512decf1a14c53fa6ca82048e65619aa6a463) by Timothée Mazzucotelli). ## [0.10.0](https://github.com/mkdocstrings/python/releases/tag/0.10.0) - 2023-05-07 [Compare with 0.9.0](https://github.com/mkdocstrings/python/compare/0.9.0...0.10.0) ### Features - Add option to disallow inspection ([40f2f26](https://github.com/mkdocstrings/python/commit/40f2f268876358941cf8221d01d219a0deb9de38) by Nyuan Zhang). [Issue #68](https://github.com/mkdocstrings/python/issues/68), [PR #69](https://github.com/mkdocstrings/python/pull/69) ### Bug Fixes - Make admonitions open by default ([79cd153](https://github.com/mkdocstrings/python/commit/79cd153cfceec860f6ce08d30817c21031983238) by Timothée Mazzucotelli). [Issue #22](https://github.com/mkdocstrings/python/issues/22) ### Code Refactoring - Match documented behavior for filtering (all members, list, none) ([c7f70c3](https://github.com/mkdocstrings/python/commit/c7f70c353c3dd2b82e1f34c70cd433e0bab4f6e6) by Timothée Mazzucotelli). - Switch to an info level log for when black's not installed ([f593bb0](https://github.com/mkdocstrings/python/commit/f593bb06c63860be14d2025c4bd795e0c8976ce0) by Faster Speeding). - Return anchors as a set ([e2b820c](https://github.com/mkdocstrings/python/commit/e2b820c5af3787518656d5f7f799ecb6b55aa033) by Timothée Mazzucotelli). ## [0.9.0](https://github.com/mkdocstrings/python/releases/tag/0.9.0) - 2023-04-03 [Compare with 0.8.3](https://github.com/mkdocstrings/python/compare/0.8.3...0.9.0) ### Features - Allow resolving alias to external modules ([02052e2](https://github.com/mkdocstrings/python/commit/02052e248b125a113ab788faa9a075adbdc92ca6) by Gilad). [PR #61](https://github.com/mkdocstrings/python/pull/61), [Follow-up of PR #60](https://github.com/mkdocstrings/python/pull/60) - Allow pre-loading modules ([36002cb](https://github.com/mkdocstrings/python/commit/36002cb9c89fba35d23afb07a866dd8c6877f742) by Gilad). [Issue mkdocstrings/mkdocstrings#503](https://github.com/mkdocstrings/mkdocstrings/issues/503), [PR #60](https://github.com/mkdocstrings/python/pull/60) - Add show options for docstrings ([a6c55fb](https://github.com/mkdocstrings/python/commit/a6c55fb52f362dd49b1a7e334a631f6ea3b1b963) by Jeremy Goh). [Issue mkdocstrings/mkdocstrings#466](https://github.com/mkdocstrings/mkdocstrings/issues/466), [PR #56](https://github.com/mkdocstrings/python/pull/56) - Allow custom list of domains for inventories ([f5ea6fd](https://github.com/mkdocstrings/python/commit/f5ea6fd81f7a531e8a97bb0e48267188d72936c1) by Sorin Sbarnea). [Issue mkdocstrings/mkdocstrings#510](https://github.com/mkdocstrings/mkdocstrings/issues/510), [PR #49](https://github.com/mkdocstrings/python/pull/49) ### Bug Fixes - Prevent alias resolution error when searching for anchors ([a190e2c](https://github.com/mkdocstrings/python/commit/a190e2c4a752e74a05ad03702837a0914c198742) by Timothée Mazzucotelli). [Issue #64](https://github.com/mkdocstrings/python/issues/64) ### Code Refactoring - Support Griffe 0.26 ([075735c](https://github.com/mkdocstrings/python/commit/075735ce8d86921fbf092d7ad1d009bbb3a2e0bb) by Timothée Mazzucotelli). - Log (debug) unresolved aliases ([9164742](https://github.com/mkdocstrings/python/commit/9164742f87362e8241dea11bec0fd96f6b9d9dda) by Timothée Mazzucotelli). ## [0.8.3](https://github.com/mkdocstrings/python/releases/tag/0.8.3) - 2023-01-04 [Compare with 0.8.2](https://github.com/mkdocstrings/python/compare/0.8.2...0.8.3) ### Code Refactoring - Change "unresolved aliases" log level to DEBUG ([dccb818](https://github.com/mkdocstrings/python/commit/dccb818f51278cc8799e2187a615d999a3ab86fb) by Timothée Mazzucotelli). ## [0.8.2](https://github.com/mkdocstrings/python/releases/tag/0.8.2) - 2022-11-19 [Compare with 0.8.1](https://github.com/mkdocstrings/python/compare/0.8.1...0.8.2) ### Bug Fixes - Fix base directory used to expand globs ([34cfa4b](https://github.com/mkdocstrings/python/commit/34cfa4b41f264437a338e66f6060ceeee134ba15) by Florian Hofer). [PR #45](https://github.com/mkdocstrings/python/pull/45) ## [0.8.1](https://github.com/mkdocstrings/python/releases/tag/0.8.1) - 2022-11-19 [Compare with 0.8.0](https://github.com/mkdocstrings/python/compare/0.8.0...0.8.1) ### Bug Fixes - Expand globs relative to configuration file path ([0dc45ae](https://github.com/mkdocstrings/python/commit/0dc45aeb7c7f9b2f15118ebf1584baa06d365c9b) by David Vegh). [Issue #42](https://github.com/mkdocstrings/python/issues/42), [PR #43](https://github.com/mkdocstrings/python/pull/43) ## [0.8.0](https://github.com/mkdocstrings/python/releases/tag/0.8.0) - 2022-11-13 [Compare with 0.7.1](https://github.com/mkdocstrings/python/compare/0.7.1...0.8.0) ### Features - Add support for globs in paths configuration ([29edd02](https://github.com/mkdocstrings/python/commit/29edd02e7a4d83f6b7e8555d4d5b03a79882eb07) by Andrew Guenther). [Issue #33](https://github.com/mkdocstrings/python/issues/33), [PR #34](https://github.com/mkdocstrings/python/pull/34) ### Code Refactoring - Support Griffe 0.24 ([3b9f701](https://github.com/mkdocstrings/python/commit/3b9f7013a7367f18e4354c37f029f9caf3ad0a4e) by Timothée Mazzucotelli). ## [0.7.1](https://github.com/mkdocstrings/python/releases/tag/0.7.1) - 2022-06-12 [Compare with 0.7.0](https://github.com/mkdocstrings/python/compare/0.7.0...0.7.1) ### Bug Fixes - Fix rendering of `/` in signatures ([3e927e4](https://github.com/mkdocstrings/python/commit/3e927e43192710218fe69f67ff832936c856a678) by Timothée Mazzucotelli). [Issue #25](https://github.com/mkdocstrings/python/issues/25) ## [0.7.0](https://github.com/mkdocstrings/python/releases/tag/0.7.0) - 2022-05-28 [Compare with 0.6.6](https://github.com/mkdocstrings/python/compare/0.6.6...0.7.0) ### Packaging / Dependencies - Depend on mkdocstrings 0.19 ([b6a9a47](https://github.com/mkdocstrings/python/commit/b6a9a4799980c4590a7ce2838e12653f40e43be3) by Timothée Mazzucotelli). ### Features - Add config option for annotations paths verbosity ([b6c9893](https://github.com/mkdocstrings/python/commit/b6c989315fb028813a919319ad1818b0b1f597ac) by Timothée Mazzucotelli). - Use sections titles in SpaCy-styled docstrings ([fe16b54](https://github.com/mkdocstrings/python/commit/fe16b54aea60473575343e3a3c428567b701bd7d) by Timothée Mazzucotelli). - Wrap objects names in spans to allow custom styling ([0822ff9](https://github.com/mkdocstrings/python/commit/0822ff9d3ffd3fb71fb619a8b557160661eff9c3) by Timothée Mazzucotelli). [Issue mkdocstrings/mkdocstrings#240](https://github.com/mkdocstrings/mkdocstrings/issues/240) - Add Jinja blocks around docstring section styles ([aaa79ee](https://github.com/mkdocstrings/python/commit/aaa79eea40d49a64a69badbe732bf5211fbf055a) by Timothée Mazzucotelli). - Add members and filters options ([24a6136](https://github.com/mkdocstrings/python/commit/24a6136ee6c04a6a49ee74b20e65177868a10ea7) by Timothée Mazzucotelli). - Add paths option ([dd41182](https://github.com/mkdocstrings/python/commit/dd41182c210f0bb2675ead162adaa01dbbb1949f) by Timothée Mazzucotelli). [Issue mkdocstrings/mkdocstrings#311](https://github.com/mkdocstrings/mkdocstrings/issues/311), [PR #20](https://github.com/mkdocstrings/python/issues/20) ### Bug Fixes - Fix CSS class on labels ([312a709](https://github.com/mkdocstrings/python/commit/312a7092394aab968032cf08195af7445a85052f) by Timothée Mazzucotelli). - Fix categories rendering ([6407cf4](https://github.com/mkdocstrings/python/commit/6407cf4f2375c894e0c528e932e9b76774a6455e) by Timothée Mazzucotelli). [Issue #14](https://github.com/mkdocstrings/python/issues/14) ### Code Refactoring - Disable `show_submodules` by default ([480d0c3](https://github.com/mkdocstrings/python/commit/480d0c373904713313ec76b6e2570dbc35eb527b) by Timothée Mazzucotelli). - Merge default configuration options in handler ([347ce76](https://github.com/mkdocstrings/python/commit/347ce76d074c0e3841df2d5162b54d3938d00453) by Timothée Mazzucotelli). - Reduce number of template debug logs ([8fed314](https://github.com/mkdocstrings/python/commit/8fed314243e3981fc7b527c69cee628e87b10220) by Timothée Mazzucotelli). - Respect `show_root_full_path` for ToC entries (hidden headings) ([8f4c853](https://github.com/mkdocstrings/python/commit/8f4c85328e8b4a45db77f9fc3e536a5008686f37) by Timothée Mazzucotelli). - Bring consistency on headings style ([59104c4](https://github.com/mkdocstrings/python/commit/59104c4c51c86c774eed76d8508f9f4d3db5463f) by Timothée Mazzucotelli). - Stop using deprecated base classes ([d5ea1c5](https://github.com/mkdocstrings/python/commit/d5ea1c5cf7884d8c019145f73685a84218e69840) by Timothée Mazzucotelli). ## [0.6.6](https://github.com/mkdocstrings/python/releases/tag/0.6.6) - 2022-03-06 [Compare with 0.6.5](https://github.com/mkdocstrings/python/compare/0.6.5...0.6.6) ### Code Refactoring - Always hide `self` and `cls` parameters ([7f579d1](https://github.com/mkdocstrings/python/commit/7f579d162e184adcfe25b2215bce4d38677f75b7) by Timothée Mazzucotelli). [Issue #7](https://github.com/mkdocstrings/python/issues/7) - Use `pycon` for examples code blocks ([6545900](https://github.com/mkdocstrings/python/commit/6545900eecc67c8a6ddd343c497ac22fdd6a26e2) by Timothée Mazzucotelli). ## [0.6.5](https://github.com/mkdocstrings/python/releases/tag/0.6.5) - 2022-02-24 [Compare with 0.6.4](https://github.com/mkdocstrings/python/compare/0.6.4...0.6.5) ### Bug Fixes - Don't escape signatures return annotations ([ac54bfc](https://github.com/mkdocstrings/python/commit/ac54bfc5761337aa606fb1aa6575745062ce26f8) by Timothée Mazzucotelli). [Issue #6](https://github.com/mkdocstrings/python/issues/6) ## [0.6.4](https://github.com/mkdocstrings/python/releases/tag/0.6.4) - 2022-02-22 [Compare with 0.6.3](https://github.com/mkdocstrings/python/compare/0.6.3...0.6.4) ### Bug Fixes - Fix rendering of signature return annotation ([b92ba3b](https://github.com/mkdocstrings/python/commit/b92ba3b370388aa6c956bcc70ba87b7aebb91a4c) by Timothée Mazzucotelli). [Issue #4](https://github.com/mkdocstrings/python/issues/4) ## [0.6.3](https://github.com/mkdocstrings/python/releases/tag/0.6.3) - 2022-02-20 [Compare with 0.6.2](https://github.com/mkdocstrings/python/compare/0.6.2...0.6.3) ### Bug Fixes - Fix examples rendering ([a06a7e3](https://github.com/mkdocstrings/python/commit/a06a7e34c7017374c5bed41f4757ed86ae64cb2e) by Timothée Mazzucotelli). [Issue mkdocstrings/griffe#46](https://github.com/mkdocstrings/griffe/issues/46) ## [0.6.2](https://github.com/mkdocstrings/python/releases/tag/0.6.2) - 2022-02-17 [Compare with 0.6.1](https://github.com/mkdocstrings/python/compare/0.6.1...0.6.2) ### Bug Fixes - Catch alias resolution errors ([b734dd0](https://github.com/mkdocstrings/python/commit/b734dd0dcd72f5b985b3afce01e852c9c74e451a) by Timothée Mazzucotelli). ## [0.6.1](https://github.com/mkdocstrings/python/releases/tag/0.6.1) - 2022-02-17 [Compare with 0.6.0](https://github.com/mkdocstrings/python/compare/0.6.0...0.6.1) ### Bug Fixes - Don't pop from fallback config ([bde32af](https://github.com/mkdocstrings/python/commit/bde32afb5d99539813b1884a4c735de5845f62ae) by Timothée Mazzucotelli). - Fix rendering init method source when merged into class ([4a20aea](https://github.com/mkdocstrings/python/commit/4a20aeaa60f3efbcb4781a369feef3b4826ff1df) by Timothée Mazzucotelli). ## [0.6.0](https://github.com/mkdocstrings/python/releases/tag/0.6.0) - 2022-02-13 [Compare with 0.5.4](https://github.com/mkdocstrings/python/compare/0.5.4...0.6.0) ### Features - Add option to merge `__init__` methods' docstrings into their classes' docstrings ([1b4d1c0](https://github.com/mkdocstrings/python/commit/1b4d1c0e9254fc51756caed3875fbc8c1da079a6) by Timothée Mazzucotelli). - Support separate attribute signature ([e962b88](https://github.com/mkdocstrings/python/commit/e962b885f48570762c5bfcefc9b61e5fc1df1c70) by Timothée Mazzucotelli). ### Bug Fixes - Restore full cross-refs paths on hover ([ac11970](https://github.com/mkdocstrings/python/commit/ac1197062f2e23e819f144fe74a774d504d0ac49) by Timothée Mazzucotelli). - Fix rendering of labels ([52919c5](https://github.com/mkdocstrings/python/commit/52919c559378a6006bbe931423c5f03eb5883eaf) by Timothée Mazzucotelli). ### Code Refactoring - Don't add trailing parentheses in functions heading when separate signature ([885696e](https://github.com/mkdocstrings/python/commit/885696e05606d07334e0428128ed688d54098da1) by Timothée Mazzucotelli). - Use more explicit template debug messages ([f2122d7](https://github.com/mkdocstrings/python/commit/f2122d7fa119ed055ffe2b2bac72d2c643daca1c) by Timothée Mazzucotelli). ## [0.5.4](https://github.com/mkdocstrings/python/releases/tag/0.5.4) - 2022-02-13 [Compare with 0.5.3](https://github.com/mkdocstrings/python/compare/0.5.3...0.5.4) ### Bug Fixes - Don't load additional modules during fallback ([69b8e25](https://github.com/mkdocstrings/python/commit/69b8e25cddc9e256c5edb8843592a466023aa124) by Timothée Mazzucotelli). ## [0.5.3](https://github.com/mkdocstrings/python/releases/tag/0.5.3) - 2022-02-08 [Compare with 0.5.2](https://github.com/mkdocstrings/python/compare/0.5.2...0.5.3) ### Bug Fixes - Allow passing `null` as docstring style ([f526816](https://github.com/mkdocstrings/python/commit/f526816ef1d499795c647e6fe184ba91c1d41b1b) by Timothée Mazzucotelli). [Issue #2](https://github.com/mkdocstrings/python/issues/2) ## [0.5.2](https://github.com/mkdocstrings/python/releases/tag/0.5.2) - 2022-02-05 [Compare with 0.5.1](https://github.com/mkdocstrings/python/compare/0.5.1...0.5.2) ### Dependencies - Require at least mkdocstrings 0.18 ([7abdda4](https://github.com/mkdocstrings/python/commit/7abdda416e25128eec06f3b15aae5058fbc7320c) by Timothée Mazzucotelli). ## [0.5.1](https://github.com/mkdocstrings/python/releases/tag/0.5.1) - 2022-02-03 [Compare with 0.5.0](https://github.com/mkdocstrings/python/compare/0.5.0...0.5.1) ### Dependencies - Depend on Griffe >= 0.11.1 ([1303557](https://github.com/mkdocstrings/python/commit/1303557928a27a3d9b063baee9d698458f471357) by Timothée Mazzucotelli). ### Code Refactoring - Move handler into its own module ([b787e78](https://github.com/mkdocstrings/python/commit/b787e78e31652438039775850e55ea956c22e8d0) by Timothée Mazzucotelli). ## [0.5.0](https://github.com/mkdocstrings/python/releases/tag/0.5.0) - 2022-02-03 [Compare with 0.4.1](https://github.com/mkdocstrings/python/compare/0.4.1...0.5.0) ### Features - Allow changing docstring style of an object ([39240c1](https://github.com/mkdocstrings/python/commit/39240c1497dced15c03f9046138f2829fc10e139) by Timothée Mazzucotelli). ### Bug Fixes - Warn if Black is not installed when formatting signature ([b848277](https://github.com/mkdocstrings/python/commit/b84827789b2bf66a4b76ff63a514ec6ba98cae68) by Timothée Mazzucotelli). - Fix missing default for `docstring_section_style` option ([774988e](https://github.com/mkdocstrings/python/commit/774988ef06a9bf3446949da63611ad7bc5a712fc) by Timothée Mazzucotelli). ### Code Refactoring - Change to new way of stripping paragraphs ([33d4594](https://github.com/mkdocstrings/python/commit/33d45945bf8ffce2435a6b3749795397fa7c3fc8) by Timothée Mazzucotelli). ## [0.4.1](https://github.com/mkdocstrings/python/releases/tag/0.4.1) - 2022-02-01 [Compare with 0.4.0](https://github.com/mkdocstrings/python/compare/0.4.0...0.4.1) ### Bug Fixes - Fix docstring admonitions rendering ([a24ae2e](https://github.com/mkdocstrings/python/commit/a24ae2e95f4c0451a44037120451cf06c973ba65) by Timothée Mazzucotelli). ## [0.4.0](https://github.com/mkdocstrings/python/releases/tag/0.4.0) - 2022-02-01 [Compare with 0.3.0](https://github.com/mkdocstrings/python/compare/0.3.0...0.4.0) ### Code Refactoring - Use the new `mkdocstrings_handlers` namespace ([23c9023](https://github.com/mkdocstrings/python/commit/23c9023780535251778077cd7d957c0067ecb0dc) by Timothée Mazzucotelli). ## [0.3.0](https://github.com/mkdocstrings/python/releases/tag/0.3.0) - 2022-01-14 [Compare with 0.2.0](https://github.com/mkdocstrings/python/compare/0.2.0...0.3.0) ### Features - Support griffe 0.10 ([28061de](https://github.com/mkdocstrings/python/commit/28061de20094c510f27bb375b2e1dc44a699809d) by Timothée Mazzucotelli). ### Dependencies - Require griffe 0.10 ([cfbd7bb](https://github.com/mkdocstrings/python/commit/cfbd7bb4761691ef36100962c775ed1d0a247514) by Timothée Mazzucotelli). ### Code Refactoring - Use new logger patching utility ([4cdb292](https://github.com/mkdocstrings/python/commit/4cdb2921b3a9292db3ef0663c63f148a4eec3966) by Timothée Mazzucotelli). ## [0.2.0](https://github.com/mkdocstrings/python/releases/tag/0.2.0) - 2021-12-28 [Compare with 0.1.0](https://github.com/mkdocstrings/python/compare/0.1.0...0.2.0) ### Dependencies - Depend on griffe >= 0.7.1 ([34f7ebd](https://github.com/mkdocstrings/python/commit/34f7ebd41f3ebda025ad87e3b52a7226fcb93720) by Timothée Mazzucotelli). - Upgrade griffe, no upper bound ([8f0aa42](https://github.com/mkdocstrings/python/commit/8f0aa42eed07424a1377708897d92f9894f4abdb) by Timothée Mazzucotelli). ### Features - Add `show_signature` rendering option ([0f07c2e](https://github.com/mkdocstrings/python/commit/0f07c2e51a51a56eeb5d32fdf05dbed7243f0bc5) by Will Da Silva). ### Bug Fixes - Fix templates for named docstring elements ([47868a1](https://github.com/mkdocstrings/python/commit/47868a143bf2c462abd5ad85bd0ab8dca7bc5f82) by Timothée Mazzucotelli). ## [0.1.0](https://github.com/mkdocstrings/python/releases/tag/0.1.0) - 2021-12-19 [Compare with first commit](https://github.com/mkdocstrings/python/compare/0032f18c9f902c3e75e0e00114ca8fa6a810c8f5...0.1.0) ### Features - Implement handler and add templates ([dbb580a](https://github.com/mkdocstrings/python/commit/dbb580aa79f6b2f8a089c80bdc67d0f7457c2d30) by Timothée Mazzucotelli). ### Bug Fixes - Fix separate signature feature ([da6e81c](https://github.com/mkdocstrings/python/commit/da6e81c897899f09e1dae7bb8930ce6782aeb306) by Timothée Mazzucotelli). - Fix signature template (parameters annotations) ([b34ead0](https://github.com/mkdocstrings/python/commit/b34ead008773880fd8d1d7a2a41768ec27820520) by Timothée Mazzucotelli). - Only show source when present ([c270d68](https://github.com/mkdocstrings/python/commit/c270d68c9e17204606ae12a2159c04563a18ec2b) by Timothée Mazzucotelli). ### Code Refactoring - Return all known anchors ([9bbfe14](https://github.com/mkdocstrings/python/commit/9bbfe1442e2aab28bd6fb2618c943d3f698750ab) by Timothée Mazzucotelli). - Update for griffe 0.4.0 ([831aabb](https://github.com/mkdocstrings/python/commit/831aabb135db7e75729954adc675af6379f58e24) by Timothée Mazzucotelli). mkdocstrings-python-handlers-1.10.5/CODE_OF_CONDUCT.md000066400000000000000000000125501463457115100222330ustar00rootroot00000000000000# Contributor Covenant Code of Conduct ## Our Pledge We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. ## Our Standards Examples of behavior that contributes to a positive environment for our community include: * Demonstrating empathy and kindness toward other people * Being respectful of differing opinions, viewpoints, and experiences * Giving and gracefully accepting constructive feedback * Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience * Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: * The use of sexualized language or imagery, and sexual attention or advances of any kind * Trolling, insulting or derogatory comments, and personal or political attacks * Public or private harassment * Publishing others' private information, such as a physical or email address, without their explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Responsibilities Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. ## Scope This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at dev@pawamoy.fr. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. ## Enforcement Guidelines Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: ### 1. Correction **Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. **Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. ### 2. Warning **Community Impact**: A violation through a single incident or series of actions. **Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. ### 3. Temporary Ban **Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. **Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. ### 4. Permanent Ban **Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. **Consequence**: A permanent ban from any sort of public interaction within the community. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC]. For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations]. [homepage]: https://www.contributor-covenant.org [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html [Mozilla CoC]: https://github.com/mozilla/diversity [FAQ]: https://www.contributor-covenant.org/faq [translations]: https://www.contributor-covenant.org/translations mkdocstrings-python-handlers-1.10.5/CONTRIBUTING.md000066400000000000000000000102241463457115100216610ustar00rootroot00000000000000# Contributing Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. ## Environment setup Nothing easier! Fork and clone the repository, then: ```bash cd python make setup ``` > NOTE: > If it fails for some reason, > you'll need to install > [uv](https://github.com/astral-sh/uv) > manually. > > You can install it with: > > ```bash > python3 -m pip install --user pipx > pipx install uv > ``` > > Now you can try running `make setup` again, > or simply `uv install`. You now have the dependencies installed. Run `make help` to see all the available actions! ## Tasks This project uses [duty](https://github.com/pawamoy/duty) to run tasks. A Makefile is also provided. The Makefile will try to run certain tasks on multiple Python versions. If for some reason you don't want to run the task on multiple Python versions, you run the task directly with `make run duty TASK`. The Makefile detects if a virtual environment is activated, so `make` will work the same with the virtualenv activated or not. If you work in VSCode, we provide [an action to configure VSCode](https://pawamoy.github.io/copier-uv/work/#vscode-setup) for the project. ## Development As usual: 1. create a new branch: `git switch -c feature-or-bugfix-name` 1. edit the code and/or the documentation **Before committing:** 1. run `make format` to auto-format the code 1. run `make check` to check everything (fix any warning) 1. run `make test` to run the tests (fix any issue) 1. if you updated the documentation or the project dependencies: 1. run `make docs` 1. go to http://localhost:8000 and check that everything looks good 1. follow our [commit message convention](#commit-message-convention) If you are unsure about how to fix or ignore a warning, just let the continuous integration fail, and we will help you during review. Don't bother updating the changelog, we will take care of this. ## Commit message convention Commit messages must follow our convention based on the [Angular style](https://gist.github.com/stephenparish/9941e89d80e2bc58a153#format-of-the-commit-message) or the [Karma convention](https://karma-runner.github.io/4.0/dev/git-commit-msg.html): ``` [(scope)]: Subject [Body] ``` **Subject and body must be valid Markdown.** Subject must have proper casing (uppercase for first letter if it makes sense), but no dot at the end, and no punctuation in general. Scope and body are optional. Type can be: - `build`: About packaging, building wheels, etc. - `chore`: About packaging or repo/files management. - `ci`: About Continuous Integration. - `deps`: Dependencies update. - `docs`: About documentation. - `feat`: New feature. - `fix`: Bug fix. - `perf`: About performance. - `refactor`: Changes that are not features or bug fixes. - `style`: A change in code style/format. - `tests`: About tests. If you write a body, please add trailers at the end (for example issues and PR references, or co-authors), without relying on GitHub's flavored Markdown: ``` Body. Issue #10: https://github.com/namespace/project/issues/10 Related to PR namespace/other-project#15: https://github.com/namespace/other-project/pull/15 ``` These "trailers" must appear at the end of the body, without any blank lines between them. The trailer title can contain any character except colons `:`. We expect a full URI for each trailer, not just GitHub autolinks (for example, full GitHub URLs for commits and issues, not the hash or the #issue-number). We do not enforce a line length on commit messages summary and body, but please avoid very long summaries, and very long lines in the body, unless they are part of code blocks that must not be wrapped. ## Pull requests guidelines Link to any related issue in the Pull Request message. During the review, we recommend using fixups: ```bash # SHA is the SHA of the commit you want to fix git commit --fixup=SHA ``` Once all the changes are approved, you can squash your commits: ```bash git rebase -i --autosquash main ``` And force-push: ```bash git push -f ``` If this seems all too complicated, you can push or force-push each new commit, and we will squash them ourselves if needed, before merging. mkdocstrings-python-handlers-1.10.5/LICENSE000066400000000000000000000013621463457115100204400ustar00rootroot00000000000000ISC License Copyright (c) 2021, Timothée Mazzucotelli Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. mkdocstrings-python-handlers-1.10.5/Makefile000066400000000000000000000007601463457115100210740ustar00rootroot00000000000000# If you have `direnv` loaded in your shell, and allow it in the repository, # the `make` command will point at the `scripts/make` shell script. # This Makefile is just here to allow auto-completion in the terminal. actions = \ allrun \ changelog \ check \ check-api \ check-docs \ check-quality \ check-types \ clean \ coverage \ docs \ docs-deploy \ format \ help \ multirun \ release \ run \ setup \ test \ vscode .PHONY: $(actions) $(actions): @python scripts/make "$@" mkdocstrings-python-handlers-1.10.5/README.md000066400000000000000000000077041463457115100207200ustar00rootroot00000000000000

mkdocstrings-python

A Python handler for mkdocstrings.

[![ci](https://github.com/mkdocstrings/python/workflows/ci/badge.svg)](https://github.com/mkdocstrings/python/actions?query=workflow%3Aci) [![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://mkdocstrings.github.io/python/) [![pypi version](https://img.shields.io/pypi/v/mkdocstrings-python.svg)](https://pypi.org/project/mkdocstrings-python/) [![gitpod](https://img.shields.io/badge/gitpod-workspace-708FCC.svg?style=flat)](https://gitpod.io/#https://github.com/mkdocstrings/python) [![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#python:gitter.im) ---

The Python handler uses [Griffe](https://mkdocstrings.github.io/griffe) to collect documentation from Python source code. The word "griffe" can sometimes be used instead of "signature" in French. Griffe is able to visit the Abstract Syntax Tree (AST) of the source code to extract useful information. It is also able to execute the code (by importing it) and introspect objects in memory when source code is not available. Finally, it can parse docstrings following different styles. ## Installation You can install this handler as a *mkdocstrings* extra: ```toml title="pyproject.toml" # PEP 621 dependencies declaration # adapt to your dependencies manager [project] dependencies = [ "mkdocstrings[python]>=0.18", ] ``` You can also explicitly depend on the handler: ```toml title="pyproject.toml" # PEP 621 dependencies declaration # adapt to your dependencies manager [project] dependencies = [ "mkdocstrings-python", ] ``` ## Preview ![mkdocstrings_python_gif](https://user-images.githubusercontent.com/3999221/77157838-7184db80-6aa2-11ea-9f9a-fe77405202de.gif) ## Features - **Data collection from source code**: collection of the object-tree and the docstrings is done thanks to [Griffe](https://github.com/mkdocstrings/griffe). - **Support for type annotations:** Griffe collects your type annotations and *mkdocstrings* uses them to display parameter types or return types. It is even able to automatically add cross-references to other objects from your API, from the standard library or third-party libraries! See [how to load inventories](https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories) to enable it. - **Recursive documentation of Python objects:** just use the module dotted-path as an identifier, and you get the full module docs. You don't need to inject documentation for each class, function, etc. - **Support for documented attributes:** attributes (variables) followed by a docstring (triple-quoted string) will be recognized by Griffe in modules, classes and even in `__init__` methods. - **Multiple docstring-styles support:** common support for Google-style, Numpydoc-style, and Sphinx-style docstrings. See [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/) on docstrings support. - **Admonition support in Google docstrings:** blocks like `Note:` or `Warning:` will be transformed to their [admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) equivalent. *We do not support nested admonitions in docstrings!* - **Every object has a TOC entry:** we render a heading for each object, meaning *MkDocs* picks them into the Table of Contents, which is nicely displayed by the Material theme. Thanks to *mkdocstrings* cross-reference ability, you can reference other objects within your docstrings, with the classic Markdown syntax: `[this object][package.module.object]` or directly with `[package.module.object][]` - **Source code display:** *mkdocstrings* can add a collapsible div containing the highlighted source code of the Python object. mkdocstrings-python-handlers-1.10.5/config/000077500000000000000000000000001463457115100206765ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/config/black.toml000066400000000000000000000000721463457115100226460ustar00rootroot00000000000000[tool.black] line-length = 120 exclude = "tests/fixtures" mkdocstrings-python-handlers-1.10.5/config/coverage.ini000066400000000000000000000006521463457115100231750ustar00rootroot00000000000000[coverage:run] branch = true parallel = true source = src/mkdocstrings_handlers tests/ [coverage:paths] equivalent = src/ .venv/lib/*/site-packages/ .venvs/*/lib/*/site-packages/ [coverage:report] include_namespace_packages = true precision = 2 omit = src/*/__init__.py src/*/__main__.py tests/__init__.py exclude_lines = pragma: no cover if TYPE_CHECKING [coverage:json] output = htmlcov/coverage.json mkdocstrings-python-handlers-1.10.5/config/git-changelog.toml000066400000000000000000000003401463457115100243000ustar00rootroot00000000000000bump = "auto" convention = "angular" in-place = true output = "CHANGELOG.md" parse-refs = false parse-trailers = true sections = ["build", "deps", "feat", "fix", "refactor"] template = "keepachangelog" versioning = "pep440" mkdocstrings-python-handlers-1.10.5/config/mypy.ini000066400000000000000000000002521463457115100223740ustar00rootroot00000000000000[mypy] ignore_missing_imports = true exclude = tests/fixtures/ warn_unused_ignores = true show_error_codes = true namespace_packages = true explicit_package_bases = true mkdocstrings-python-handlers-1.10.5/config/pytest.ini000066400000000000000000000004341463457115100227300ustar00rootroot00000000000000[pytest] python_files = test_*.py addopts = --cov --cov-config config/coverage.ini testpaths = tests # action:message_regex:warning_class:module_regex:line filterwarnings = error # TODO: remove once pytest-xdist 4 is released ignore:.*rsyncdir:DeprecationWarning:xdist mkdocstrings-python-handlers-1.10.5/config/ruff.toml000066400000000000000000000041401463457115100225340ustar00rootroot00000000000000target-version = "py38" line-length = 120 [lint] exclude = [ "tests/fixtures/*.py", ] select = [ "A", "ANN", "ARG", "B", "BLE", "C", "C4", "COM", "D", "DTZ", "E", "ERA", "EXE", "F", "FBT", "G", "I", "ICN", "INP", "ISC", "N", "PGH", "PIE", "PL", "PLC", "PLE", "PLR", "PLW", "PT", "PYI", "Q", "RUF", "RSE", "RET", "S", "SIM", "SLF", "T", "T10", "T20", "TCH", "TID", "TRY", "UP", "W", "YTT", ] ignore = [ "A001", # Variable is shadowing a Python builtin "ANN101", # Missing type annotation for self "ANN102", # Missing type annotation for cls "ANN204", # Missing return type annotation for special method __str__ "ANN401", # Dynamically typed expressions (typing.Any) are disallowed "ARG005", # Unused lambda argument "C901", # Too complex "D105", # Missing docstring in magic method "D417", # Missing argument description in the docstring "E501", # Line too long "ERA001", # Commented out code "G004", # Logging statement uses f-string "PLR0911", # Too many return statements "PLR0912", # Too many branches "PLR0913", # Too many arguments to function call "PLR0915", # Too many statements "SLF001", # Private member accessed "TRY003", # Avoid specifying long messages outside the exception class ] [lint.per-file-ignores] "src/*/cli.py" = [ "T201", # Print statement ] "src/*/debug.py" = [ "T201", # Print statement ] "scripts/*.py" = [ "INP001", # File is part of an implicit namespace package "T201", # Print statement ] "tests/*.py" = [ "ARG005", # Unused lambda argument "FBT001", # Boolean positional arg in function definition "PLR2004", # Magic value used in comparison "S101", # Use of assert detected ] [lint.flake8-quotes] docstring-quotes = "double" [lint.flake8-tidy-imports] ban-relative-imports = "all" [lint.isort] known-first-party = ["mkdocstrings_handlers.python"] [lint.pydocstyle] convention = "google" [format] exclude = [ "tests/fixtures/*.py", ] docstring-code-format = true docstring-code-line-length = 80 mkdocstrings-python-handlers-1.10.5/config/vscode/000077500000000000000000000000001463457115100221615ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/config/vscode/launch.json000066400000000000000000000021771463457115100243350ustar00rootroot00000000000000{ "version": "0.2.0", "configurations": [ { "name": "python (current file)", "type": "debugpy", "request": "launch", "program": "${file}", "console": "integratedTerminal", "justMyCode": false }, { "name": "docs", "type": "debugpy", "request": "launch", "module": "mkdocs", "justMyCode": false, "args": [ "serve", "-v" ] }, { "name": "test", "type": "debugpy", "request": "launch", "module": "pytest", "justMyCode": false, "args": [ "-c=config/pytest.ini", "-vvv", "--no-cov", "--dist=no", "tests", "-k=${input:tests_selection}" ] } ], "inputs": [ { "id": "tests_selection", "type": "promptString", "description": "Tests selection", "default": "" } ] }mkdocstrings-python-handlers-1.10.5/config/vscode/settings.json000066400000000000000000000017041463457115100247160ustar00rootroot00000000000000{ "files.watcherExclude": { "**/.venv*/**": true, "**/.venvs*/**": true, "**/venv*/**": true }, "mypy-type-checker.args": [ "--config-file=config/mypy.ini" ], "python.testing.unittestEnabled": false, "python.testing.pytestEnabled": true, "python.testing.pytestArgs": [ "--config-file=config/pytest.ini" ], "ruff.enable": true, "ruff.format.args": [ "--config=config/ruff.toml" ], "ruff.lint.args": [ "--config=config/ruff.toml" ], "yaml.schemas": { "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml" }, "yaml.customTags": [ "!ENV scalar", "!ENV sequence", "!relative scalar", "tag:yaml.org,2002:python/name:materialx.emoji.to_svg", "tag:yaml.org,2002:python/name:materialx.emoji.twemoji", "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format" ] }mkdocstrings-python-handlers-1.10.5/config/vscode/tasks.json000066400000000000000000000046051463457115100242060ustar00rootroot00000000000000{ "version": "2.0.0", "tasks": [ { "label": "changelog", "type": "process", "command": "scripts/make", "args": ["changelog"] }, { "label": "check", "type": "process", "command": "scripts/make", "args": ["check"] }, { "label": "check-quality", "type": "process", "command": "scripts/make", "args": ["check-quality"] }, { "label": "check-types", "type": "process", "command": "scripts/make", "args": ["check-types"] }, { "label": "check-docs", "type": "process", "command": "scripts/make", "args": ["check-docs"] }, { "label": "check-api", "type": "process", "command": "scripts/make", "args": ["check-api"] }, { "label": "clean", "type": "process", "command": "scripts/make", "args": ["clean"] }, { "label": "docs", "type": "process", "command": "scripts/make", "args": ["docs"] }, { "label": "docs-deploy", "type": "process", "command": "scripts/make", "args": ["docs-deploy"] }, { "label": "format", "type": "process", "command": "scripts/make", "args": ["format"] }, { "label": "release", "type": "process", "command": "scripts/make", "args": ["release", "${input:version}"] }, { "label": "setup", "type": "process", "command": "scripts/make", "args": ["setup"] }, { "label": "test", "type": "process", "command": "scripts/make", "args": ["test", "coverage"], "group": "test" }, { "label": "vscode", "type": "process", "command": "scripts/make", "args": ["vscode"] } ], "inputs": [ { "id": "version", "type": "promptString", "description": "Version" } ] }mkdocstrings-python-handlers-1.10.5/devdeps.txt000066400000000000000000000010251463457115100216220ustar00rootroot00000000000000# dev editables>=0.5 # maintenance build>=1.2 git-changelog>=2.5 twine>=5.1; python_version < '3.13' # ci duty>=1.4 ruff>=0.4 pytest>=8.2 pytest-cov>=5.0 pytest-randomly>=3.15 pytest-xdist>=3.6 mypy>=1.10 types-markdown>=3.6 types-pyyaml>=6.0 # docs black>=24.4 markdown-callouts>=0.4 markdown-exec>=1.8 mkdocs>=1.6 mkdocs-coverage>=1.0 mkdocs-gen-files>=0.5 mkdocs-git-committers-plugin-2>=2.3 mkdocs-literate-nav>=0.6 mkdocs-material>=9.5 mkdocs-minify-plugin>=0.8 mkdocstrings[python]>=0.25 tomli>=2.0; python_version < '3.11' mkdocstrings-python-handlers-1.10.5/docs/000077500000000000000000000000001463457115100203615ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/docs/.glossary.md000066400000000000000000000015251463457115100226270ustar00rootroot00000000000000[__all__]: https://docs.python.org/3/tutorial/modules.html#importing-from-a-package [class template]: https://github.com/mkdocstrings/python/blob/master/src/mkdocstrings_handlers/python/templates/material/_base/class.html [function template]: https://github.com/mkdocstrings/python/blob/master/src/mkdocstrings_handlers/python/templates/material/_base/function.html [autodoc syntax]: https://mkdocstrings.github.io/usage/#autodoc-syntax [autopages recipe]: https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages [Griffe]: https://github.com/mkdocstrings/griffe [ReadTheDocs Sphinx theme]: https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html [Spacy's documentation]: https://spacy.io/api/doc/ [Black]: https://pypi.org/project/black/ [Material for MkDocs]: https://squidfunk.github.io/mkdocs-material *[ToC]: Table of Contents mkdocstrings-python-handlers-1.10.5/docs/.overrides/000077500000000000000000000000001463457115100224415ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/docs/.overrides/main.html000066400000000000000000000010471463457115100242550ustar00rootroot00000000000000{% extends "base.html" %} {% block announce %} Sponsorship is now available! {% include ".icons/octicons/heart-fill-16.svg" %} — For updates follow @pawamoy on {% include ".icons/fontawesome/brands/mastodon.svg" %} Fosstodon {% endblock %} mkdocstrings-python-handlers-1.10.5/docs/changelog.md000066400000000000000000000000261463457115100226300ustar00rootroot00000000000000--8<-- "CHANGELOG.md" mkdocstrings-python-handlers-1.10.5/docs/code_of_conduct.md000066400000000000000000000000341463457115100240150ustar00rootroot00000000000000--8<-- "CODE_OF_CONDUCT.md" mkdocstrings-python-handlers-1.10.5/docs/contributing.md000066400000000000000000000000311463457115100234040ustar00rootroot00000000000000--8<-- "CONTRIBUTING.md" mkdocstrings-python-handlers-1.10.5/docs/credits.md000066400000000000000000000002011463457115100223310ustar00rootroot00000000000000--- hide: - toc --- ```python exec="yes" --8<-- "scripts/gen_credits.py" ``` mkdocstrings-python-handlers-1.10.5/docs/css/000077500000000000000000000000001463457115100211515ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/docs/css/insiders.css000066400000000000000000000037311463457115100235070ustar00rootroot00000000000000@keyframes heart { 0%, 40%, 80%, 100% { transform: scale(1); } 20%, 60% { transform: scale(1.15); } } @keyframes vibrate { 0%, 2%, 4%, 6%, 8%, 10%, 12%, 14%, 16%, 18% { -webkit-transform: translate3d(-2px, 0, 0); transform: translate3d(-2px, 0, 0); } 1%, 3%, 5%, 7%, 9%, 11%, 13%, 15%, 17%, 19% { -webkit-transform: translate3d(2px, 0, 0); transform: translate3d(2px, 0, 0); } 20%, 100% { -webkit-transform: translate3d(0, 0, 0); transform: translate3d(0, 0, 0); } } .heart { color: #e91e63; } .pulse { animation: heart 1000ms infinite; } .vibrate { animation: vibrate 2000ms infinite; } .new-feature svg { fill: var(--md-accent-fg-color) !important; } a.insiders { color: #e91e63; } .sponsorship-list { width: 100%; } .sponsorship-item { border-radius: 100%; display: inline-block; height: 1.6rem; margin: 0.1rem; overflow: hidden; width: 1.6rem; } .sponsorship-item:focus, .sponsorship-item:hover { transform: scale(1.1); } .sponsorship-item img { filter: grayscale(100%) opacity(75%); height: auto; width: 100%; } .sponsorship-item:focus img, .sponsorship-item:hover img { filter: grayscale(0); } .sponsorship-item.private { background: var(--md-default-fg-color--lightest); color: var(--md-default-fg-color); font-size: .6rem; font-weight: 700; line-height: 1.6rem; text-align: center; } .mastodon { color: #897ff8; border-radius: 100%; box-shadow: inset 0 0 0 .05rem currentcolor; display: inline-block; height: 1.2rem !important; padding: .25rem; transition: all .25s; vertical-align: bottom !important; width: 1.2rem; } .premium-sponsors { text-align: center; } #silver-sponsors img { height: 140px; } #bronze-sponsors img { height: 140px; } #bronze-sponsors p { display: flex; flex-wrap: wrap; justify-content: center; } #bronze-sponsors a { display: block; flex-shrink: 0; } .sponsors-total { font-weight: bold; }mkdocstrings-python-handlers-1.10.5/docs/css/material.css000066400000000000000000000026751463457115100234730ustar00rootroot00000000000000/* More space at the bottom of the page. */ .md-main__inner { margin-bottom: 1.5rem; } /* Custom admonition: preview */ :root { --md-admonition-icon--preview: url('data:image/svg+xml;charset=utf-8,'); } .md-typeset .admonition.preview, .md-typeset details.preview { border-color: rgb(220, 139, 240); } .md-typeset .preview>.admonition-title, .md-typeset .preview>summary { background-color: rgba(142, 43, 155, 0.1); } .md-typeset .preview>.admonition-title::before, .md-typeset .preview>summary::before { background-color: rgb(220, 139, 240); -webkit-mask-image: var(--md-admonition-icon--preview); mask-image: var(--md-admonition-icon--preview); }mkdocstrings-python-handlers-1.10.5/docs/css/mkdocstrings.css000066400000000000000000000021031463457115100243660ustar00rootroot00000000000000/* Indentation. */ div.doc-contents:not(.first) { padding-left: 25px; border-left: .05rem solid var(--md-typeset-table-color); } /* Mark external links as such. */ a.external::after, a.autorefs-external::after { /* https://primer.style/octicons/arrow-up-right-24 */ mask-image: url('data:image/svg+xml,'); -webkit-mask-image: url('data:image/svg+xml,'); content: ' '; display: inline-block; vertical-align: middle; position: relative; height: 1em; width: 1em; background-color: currentColor; } a.external:hover::after, a.autorefs-external:hover::after { background-color: var(--md-accent-fg-color); } mkdocstrings-python-handlers-1.10.5/docs/index.md000066400000000000000000000000231463457115100220050ustar00rootroot00000000000000--8<-- "README.md" mkdocstrings-python-handlers-1.10.5/docs/insiders/000077500000000000000000000000001463457115100222015ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/docs/insiders/changelog.md000066400000000000000000000032061463457115100244530ustar00rootroot00000000000000# Changelog ## mkdocstrings-python Insiders ### 1.5.1 September 12, 2023 { id="1.5.1" } - Prevent empty auto-summarized Methods section. ### 1.5.0 September 05, 2023 { id="1.5.0" } - Render function signature overloads. ### 1.4.0 August 27, 2023 { id="1.4.0" } - Render cross-references in attribute signatures. ### 1.3.0 August 24, 2023 { id="1.3.0" } - Add "method" symbol type. ### 1.2.0 August 20, 2023 { id="1.2.0" } - Add [member auto-summaries](../usage/configuration/members.md#summary). ### 1.1.4 July 17, 2023 { id="1.1.4" } - Fix heading level increment for class members. ### 1.1.3 July 17, 2023 { id="1.1.3" } - Fix heading level (avoid with clause preventing to decrease it). ### 1.1.2 July 15, 2023 { id="1.1.2" } - Use non-breaking spaces after symbol types. ### 1.1.1 June 27, 2023 { id="1.1.1" } - Correctly escape expressions in signatures and other rendered types. ### 1.1.0 June 4, 2023 { id="1.1.0" } - Add [Symbol types in headings and table of contents](../usage/configuration/headings.md#show_symbol_type_toc). ### 1.0.0 May 10, 2023 { id="1.0.0" } - Add [cross-references for type annotations in signatures](../usage/configuration/signatures.md#signature_crossrefs). Make sure to update your local templates as the signature of the [`format_signature` filter][mkdocstrings_handlers.python.rendering.do_format_signature] has changed. The templates that must be updated: `class.html`, `expression.html`, `function.html` and `signature.html`. mkdocstrings-python-handlers-1.10.5/docs/insiders/goals.yml000066400000000000000000000013561463457115100240360ustar00rootroot00000000000000goals: 500: name: PlasmaVac User Guide features: - name: Cross-references for type annotations in signatures ref: /usage/configuration/signatures/#signature_crossrefs since: 2023/05/10 - name: Symbol types in headings and table of contents ref: /usage/configuration/headings/#show_symbol_type_toc since: 2023/06/04 1000: name: GraviFridge Fluid Renewal features: - name: Auto-summary of object members ref: /usage/configuration/members/#summary since: 2023/08/20 - name: Automatic rendering of function signature overloads since: 2023/09/05 1500: name: HyperLamp Navigation Tips features: [] 2000: name: FusionDrive Ejection Configuration features: [] mkdocstrings-python-handlers-1.10.5/docs/insiders/index.md000066400000000000000000000245121463457115100236360ustar00rootroot00000000000000# Insiders *mkdocstrings-python* follows the **sponsorware** release strategy, which means that new features are first exclusively released to sponsors as part of [Insiders][insiders]. Read on to learn [what sponsorships achieve][sponsorship], [how to become a sponsor][sponsors] to get access to Insiders, and [what's in it for you][features]! ## What is Insiders? *mkdocstrings-python Insiders* is a private fork of *mkdocstrings-python*, hosted as a private GitHub repository. Almost[^1] [all new features][features] are developed as part of this fork, which means that they are immediately available to all eligible sponsors, as they are made collaborators of this repository. [^1]: In general, every new feature is first exclusively released to sponsors, but sometimes upstream dependencies enhance existing features that must be supported by *mkdocstrings-python*. Every feature is tied to a [funding goal][funding] in monthly subscriptions. When a funding goal is hit, the features that are tied to it are merged back into *mkdocstrings-python* and released for general availability, making them available to all users. Bugfixes are always released in tandem. Sponsorships start as low as [**$10 a month**][sponsors].[^2] [^2]: Note that $10 a month is the minimum amount to become eligible for Insiders. While GitHub Sponsors also allows to sponsor lower amounts or one-time amounts, those can't be granted access to Insiders due to technical reasons. Such contributions are still very much welcome as they help ensuring the project's sustainability. ## What sponsorships achieve Sponsorships make this project sustainable, as they buy the maintainers of this project time – a very scarce resource – which is spent on the development of new features, bug fixing, stability improvement, issue triage and general support. The biggest bottleneck in Open Source is time.[^3] [^3]: Making an Open Source project sustainable is exceptionally hard: maintainers burn out, projects are abandoned. That's not great and very unpredictable. The sponsorware model ensures that if you decide to use *mkdocstrings-python*, you can be sure that bugs are fixed quickly and new features are added regularly. If you're unsure if you should sponsor this project, check out the list of [completed funding goals][goals completed] to learn whether you're already using features that were developed with the help of sponsorships. You're most likely using at least a handful of them, [thanks to our awesome sponsors][sponsors]! ## What's in it for me? ```python exec="1" session="insiders" data_source = [ "docs/insiders/goals.yml", ("griffe-inherited-docstrings", "https://mkdocstrings.github.io/griffe-inherited-docstrings/", "insiders/goals.yml"), ("griffe-pydantic", "https://mkdocstrings.github.io/griffe-pydantic/", "insiders/goals.yml"), ("griffe-warnings-deprecated", "https://mkdocstrings.github.io/griffe-warnings-deprecated/", "insiders/goals.yml"), ] ``` ```python exec="1" session="insiders" idprefix="" --8<-- "scripts/insiders.py" if unreleased_features: print( "The moment you [become a sponsor](#how-to-become-a-sponsor), you'll get **immediate " f"access to {len(unreleased_features)} additional features** that you can start using right away, and " "which are currently exclusively available to sponsors:\n" ) for feature in unreleased_features: feature.render(badge=True) print( "\n\nThese are just the features related to this project. " "[See the complete feature list on the author's main Insiders page](https://pawamoy.github.io/insiders/#whats-in-it-for-me)." ) else: print( "The moment you [become a sponsor](#how-to-become-a-sponsor), you'll get immediate " "access to all released features that you can start using right away, and " "which are exclusively available to sponsors. At this moment, there are no " "Insiders features for this project, but checkout the [next funding goals](#goals) " "to see what's coming, as well as **[the feature list for all Insiders projects](https://pawamoy.github.io/insiders/#whats-in-it-for-me).**" ) ``` ## How to become a sponsor Thanks for your interest in sponsoring! In order to become an eligible sponsor with your GitHub account, visit [pawamoy's sponsor profile][github sponsor profile], and complete a sponsorship of **$10 a month or more**. You can use your individual or organization GitHub account for sponsoring. **Important**: If you're sponsoring **[@pawamoy][github sponsor profile]** through a GitHub organization, please send a short email to insiders@pawamoy.fr with the name of your organization and the GitHub account of the individual that should be added as a collaborator.[^4] You can cancel your sponsorship anytime.[^5] [^4]: It's currently not possible to grant access to each member of an organization, as GitHub only allows for adding users. Thus, after sponsoring, please send an email to insiders@pawamoy.fr, stating which account should become a collaborator of the Insiders repository. We're working on a solution which will make access to organizations much simpler. To ensure that access is not tied to a particular individual GitHub account, create a bot account (i.e. a GitHub account that is not tied to a specific individual), and use this account for the sponsoring. After being added to the list of collaborators, the bot account can create a private fork of the private Insiders GitHub repository, and grant access to all members of the organizations. [^5]: If you cancel your sponsorship, GitHub schedules a cancellation request which will become effective at the end of the billing cycle. This means that even though you cancel your sponsorship, you will keep your access to Insiders as long as your cancellation isn't effective. All charges are processed by GitHub through Stripe. As we don't receive any information regarding your payment, and GitHub doesn't offer refunds, sponsorships are non-refundable. [:octicons-heart-fill-24:{ .pulse }   Join our awesome sponsors](https://github.com/sponsors/pawamoy){ .md-button .md-button--primary }
If you sponsor publicly, you're automatically added here with a link to your profile and avatar to show your support for *mkdocstrings-python*. Alternatively, if you wish to keep your sponsorship private, you'll be a silent +1. You can select visibility during checkout and change it afterwards. ## Funding ### Goals The following section lists all funding goals. Each goal contains a list of features prefixed with a checkmark symbol, denoting whether a feature is :octicons-check-circle-fill-24:{ style="color: #00e676" } already available or :octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned, but not yet implemented. When the funding goal is hit, the features are released for general availability. ```python exec="1" session="insiders" idprefix="" for goal in goals.values(): if not goal.complete: goal.render() ``` ### Goals completed This section lists all funding goals that were previously completed, which means that those features were part of Insiders, but are now generally available and can be used by all users. ```python exec="1" session="insiders" idprefix="" for goal in goals.values(): if goal.complete: goal.render() ``` ## Frequently asked questions ### Compatibility > We're building an open source project and want to allow outside collaborators to use *mkdocstrings-python* locally without having access to Insiders. Is this still possible? Yes. Insiders is compatible with *mkdocstrings-python*. Almost all new features and configuration options are either backward-compatible or implemented behind feature flags. Most Insiders features enhance the overall experience, though while these features add value for the users of your project, they shouldn't be necessary for previewing when making changes to content. ### Payment > We don't want to pay for sponsorship every month. Are there any other options? Yes. You can sponsor on a yearly basis by [switching your GitHub account to a yearly billing cycle][billing cycle]. If for some reason you cannot do that, you could also create a dedicated GitHub account with a yearly billing cycle, which you only use for sponsoring (some sponsors already do that). If you have any problems or further questions, please reach out to insiders@pawamoy.fr. ### Terms > Are we allowed to use Insiders under the same terms and conditions as *mkdocstrings-python*? Yes. Whether you're an individual or a company, you may use *mkdocstrings-python Insiders* precisely under the same terms as *mkdocstrings-python*, which are given by the [ISC License][license]. However, we kindly ask you to respect our **fair use policy**: - Please **don't distribute the source code** of Insiders. You may freely use it for public, private or commercial projects, privately fork or mirror it, but please don't make the source code public, as it would counteract the sponsorware strategy. - If you cancel your subscription, you're automatically removed as a collaborator and will miss out on all future updates of Insiders. However, you may **use the latest version** that's available to you **as long as you like**. Just remember that [GitHub deletes private forks][private forks]. [insiders]: #what-is-insiders [sponsorship]: #what-sponsorships-achieve [sponsors]: #how-to-become-a-sponsor [features]: #whats-in-it-for-me [funding]: #funding [goals completed]: #goals-completed [github sponsor profile]: https://github.com/sponsors/pawamoy [billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle [license]: ../license.md [private forks]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository mkdocstrings-python-handlers-1.10.5/docs/insiders/installation.md000066400000000000000000000057411463457115100252330ustar00rootroot00000000000000--- title: Getting started with Insiders --- # Getting started with Insiders *mkdocstrings-python Insiders* is a compatible drop-in replacement for *mkdocstrings-python*, and can be installed similarly using `pip` or `git`. Note that in order to access the Insiders repository, you need to [become an eligible sponsor] of @pawamoy on GitHub. [become an eligible sponsor]: index.md#how-to-become-a-sponsor ## Installation ### with PyPI Insiders [PyPI Insiders](https://pawamoy.github.io/pypi-insiders/) is a tool that helps you keep up-to-date versions of Insiders projects in the PyPI index of your choice (self-hosted, Google registry, Artifactory, etc.). See [how to install it](https://pawamoy.github.io/pypi-insiders/#installation) and [how to use it](https://pawamoy.github.io/pypi-insiders/#usage). **We kindly ask that you do not upload the distributions to public registries, as it is against our [Terms of use](index.md#terms).** ### with pip (ssh/https) *mkdocstrings-python Insiders* can be installed with `pip` [using SSH][using ssh]: ```bash pip install git+ssh://git@github.com/pawamoy-insiders/mkdocstrings-python.git ``` [using ssh]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh Or using HTTPS: ```bash pip install git+https://${GH_TOKEN}@github.com/pawamoy-insiders/mkdocstrings-python.git ``` >? NOTE: **How to get a GitHub personal access token** > The `GH_TOKEN` environment variable is a GitHub token. > It can be obtained by creating a [personal access token] for > your GitHub account. It will give you access to the Insiders repository, > programmatically, from the command line or GitHub Actions workflows: > > 1. Go to https://github.com/settings/tokens > 2. Click on [Generate a new token] > 3. Enter a name and select the [`repo`][scopes] scope > 4. Generate the token and store it in a safe place > > [personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token > [Generate a new token]: https://github.com/settings/tokens/new > [scopes]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes > > Note that the personal access > token must be kept secret at all times, as it allows the owner to access your > private repositories. ### with Git Of course, you can use *mkdocstrings-python Insiders* directly using Git: ``` git clone git@github.com:pawamoy-insiders/mkdocstrings-python ``` When cloning with Git, the package must be installed: ``` pip install -e mkdocstrings-python ``` ## Upgrading When upgrading Insiders, you should always check the version of *mkdocstrings-python* which makes up the first part of the version qualifier. For example, a version like `8.x.x.4.x.x` means that Insiders `4.x.x` is currently based on `8.x.x`. If the major version increased, it's a good idea to consult the [changelog] and go through the steps to ensure your configuration is up to date and all necessary changes have been made. [changelog]: ./changelog.md mkdocstrings-python-handlers-1.10.5/docs/js/000077500000000000000000000000001463457115100207755ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/docs/js/insiders.js000066400000000000000000000054731463457115100231640ustar00rootroot00000000000000function humanReadableAmount(amount) { const strAmount = String(amount); if (strAmount.length >= 4) { return `${strAmount.slice(0, strAmount.length - 3)},${strAmount.slice(-3)}`; } return strAmount; } function getJSON(url, callback) { var xhr = new XMLHttpRequest(); xhr.open('GET', url, true); xhr.responseType = 'json'; xhr.onload = function () { var status = xhr.status; if (status === 200) { callback(null, xhr.response); } else { callback(status, xhr.response); } }; xhr.send(); } function updatePremiumSponsors(dataURL, rank) { let capRank = rank.charAt(0).toUpperCase() + rank.slice(1); getJSON(dataURL + `/sponsors${capRank}.json`, function (err, sponsors) { const sponsorsDiv = document.getElementById(`${rank}-sponsors`); if (sponsors.length > 0) { let html = ''; html += `${capRank} sponsors

` sponsors.forEach(function (sponsor) { html += ` ${sponsor.name} ` }); html += '

' sponsorsDiv.innerHTML = html; } }); } function updateInsidersPage(author_username) { const sponsorURL = `https://github.com/sponsors/${author_username}` const dataURL = `https://raw.githubusercontent.com/${author_username}/sponsors/main`; getJSON(dataURL + '/numbers.json', function (err, numbers) { document.getElementById('sponsors-count').innerHTML = numbers.count; Array.from(document.getElementsByClassName('sponsors-total')).forEach(function (element) { element.innerHTML = '$ ' + humanReadableAmount(numbers.total); }); getJSON(dataURL + '/sponsors.json', function (err, sponsors) { const sponsorsElem = document.getElementById('sponsors'); const privateSponsors = numbers.count - sponsors.length; sponsors.forEach(function (sponsor) { sponsorsElem.innerHTML += ` `; }); if (privateSponsors > 0) { sponsorsElem.innerHTML += ` +${privateSponsors} `; } }); }); updatePremiumSponsors(dataURL, "gold"); updatePremiumSponsors(dataURL, "silver"); updatePremiumSponsors(dataURL, "bronze"); } mkdocstrings-python-handlers-1.10.5/docs/license.md000066400000000000000000000000441463457115100223230ustar00rootroot00000000000000# License ``` --8<-- "LICENSE" ``` mkdocstrings-python-handlers-1.10.5/docs/logo.png000066400000000000000000001627141463457115100220420ustar00rootroot00000000000000PNG  IHDRZrMzTXtRaw profile type exifxڭgvcvcrZo^+DN;JzzG|Ssg_^(c1}k%,~=o/|?[~.=oV߳k _|(uJa,pz a%WzN\XxGhq2.L&$2kH%Tz,q {L9)$cNuoB'3yH&%HHӑ`SCK)(k*l-JF=Ksđ2h1䦓'\0EKXf݆EʪnXsǝ6ȵn R:SO;3/vͷzwG־?k;keJlkCIQX́7e@BQStEL(9;(cd0 ?#s?ys9?9=oڞ zاztB)0qd1^W/)ɫӈ=o[imjhDv6mr\KbhZXٷgwNnE|:=w+z~9 b%t_Zo[@F-,uPn)Cx`brIq),&AN(gܬ_r6^~)$}wV&~'/Oi Xk [Vuk4"F-U K E9BWH{4&Tp䁼b6`;w:/iwg(LnΘ03u10g!GtI<2b"# Z_FJu8.%{(4Ivt?P.aiTŸ DAG9ܦ6nVxJ:"R}/p3WLݔ>x)UBJ+bTׁMCZH&< ow N.D҂p^LnDW)qq~'7kӨ ˤ T~`X7`R.Y=A 2ƚ$H8~}]7Zu6gJEiiDS|f XHiDf4#'a>(3#e)Rޕ"a_h_s -¯e3sZeR}HvA-Dʍ`zLH藬)zH !."B4/x2XD]۔LgF 6dS-Q62A;K/ o ~/WA&jI iԫʵRQS3.K z(Lb/͆r6Y#C)UYn~T]2NBn;(.8C"D.NŞfFS'<%  %*9? MWWe f2@|.ky|DP`{M4}3!֓i)ՠ 6 B(~V:РC+ `9n1U+7qæ8.v?w]Yb:)k/x.5wlA. gM _{ OP|=M{GAL=@ׇwHT"P}{'$v3꫟ԄDzmɬ?@er^Um?t,ory JFMT)jqlHVhuɘd#H%U#% =XKWXhoИQ44\)V.AM!:n#"Vxr)!T?, Y)0E[HapR|}L<<+Kp4n]#[UwY1߼8J=.BsGʢ mI/Fđd%6ϓ'h xww5.ɐrgPbDm,8K$G#项͋`3y1Uy%Ĭ lYhm/CiZ$ikBX6 z @7% ny2uljxQOLB֑CMpB-H"01Ѻ46U'p:4r"X[$Hѓ$(Ƙ-hπR ;tL`1)IX[2GLsBH?!|.}@*|D SRߏPp0ִR,1;|½ED hCB7(j_g) &aV14TV;3I::ޚ EqU36-)r_n1PxRm0cYa=d'B=PnaTp\~^{P7΅rm4aG {paϻ2G;b 9ںh{hZŰ4(pIBke|"0. c]~;6MR碟@x@5CD$c_JBH+ps0~GQ聅:D;3#~CNhcw@nxщvJ&G rZ"1"̟:AGPcӋAdyo7?ʚL#6R)V=EKZnXhj sb IRʅ %q:)_.bVZy6]vtT@x@TAQk |boS{-`p^—+cMκy(!w3"jWQ \L~cC2c=! t@ЫWo_f[+:hC;6~6Bn4 >5 H2ϑ + y_ .[`I^LLBJ n y84ryC 2mx#o#Oac4(EgI e>+'j"6JHtj*y$nK[PnAk1d4W3䑘$Cѥ8P-U<nt!F"U1(OJw) =umIM_[B::ԫG$ yo9G/O[a-Z?-I:(6#twthE-֗M'fB`FI$C_g0%(S . `@WgڏCǡi`xhjvaȊxEG 2®159-d(-QQΘ&@aX;LѩΗ1Tm=E1pnUhtdZ#ޚRی?3JrdYAgW(6b#, ! pi.ܠ|2p yB^rSDbSA܉|B3E$ q@+q7TǡKe[~@Q') xk(b. jrh&p8H$p)%>2o3 xh$.G!fxǑ-EK4jY :oK,2Cp޽] Z⻮N!p⨉-C[9ν#8C8SK3AbG$~u@b [ĆIEoD6 o9a+;YG8 Ov X ~ ? za`mgjI?;F/,Bچ~9.q|b#]{&#-0&M&N Qk0 bZoڬ"ĈpY$yԣM-$zzVabCUt.TRc2_.t@G%UXcBSjv97 /hJ?rOP `"hUJR|POe:O>F* |(_YN-n_ps-I<RUڇzΎ-7 3&K:m_уEr?.I_0/K ,Pbfze @'FQG>z/ & 54C$;x?4{uba@r +T}xD:LB^/#lt$xOv4^售>t^י6r zձ܆ @zZ|i7@Aw2 rIQ].d:t r* &mlOH2^[o$_i/ސH r݈ى6{Al@NwDn}(n Bl(lwHaUqP^;&D0\3$gfԮp#yK];Ot4>Y!jPAԴ2/,.P>4!~T;:mӺaRLvdVpsԉUߏ'Ϗ:0J Q*0nEEm?(+.OBKVztLw,c"-\3:XHy1K҆翨}W&|, xxz9GYIRω #e8̨IGbJJ 9bKGD pHYs  tIME  4S IDATxy|Օ=zSK[1"86l^`2$eB20I3I>y~' U,$!c H0cm1xhݒ%[K/խt>[UV=s  A(hnƆzM =Kn1ͺLL9Y13.Hpʔi%N/4^cIMCSrPe(.Wb411i?2ɣc h%BbF Nͪmvht@qZ6$GL-6v:@Fvy>~@2!"ՌH*AAaX o'ԳXZ;v5?',O0TlzǬ&Ü@c {"Dh0& W0k9Yzӏ^rJ{t b|@D R鷨k@ 8h 8!vH:6ɖ|V_?jQI^GlD3"H   zT-oЬoёmӅsMS1|Wt~˘1M5)8ciX$; рvaSgbySӥ2D|7l;wCԿSÒ AA)H)2``za'pq'pTA oE>2 dƑ]?38m++uDAAfΪD/'Lڛ|ݎ^TkW h935|*. HsZZo4^AϾEめkmǹ.T5D Z'qX )<+9KK>gR#݃&@C)e ev@;-amϯOюHd]$]A{olT#EٟьS&] s2)qh05k(*!gn!=8?%)2DJJ)ӂ:?ƬL:_f[WBfS8,0"  ҩӳ3>䘠a_b*,& 0v@K(t (g!bbS7h5D,GOmj=Gzdf]$]AR@m-# r]6Aà=L& +n<#%w}12,*F2-K6f0R =~hv'h'rx[b F-q"  ZFvoZdXКV̌Eh!.AW]Ao ):ߛ?O|{GjhDzDAA("+BW:D~d Xwx|e vlG;6+";<ARxb|K dZiOi"ôرöA7~`-[bˬH  E6 ,Zp{|[Mw)tv<d1Bt3ѩD2-S>8xnz<^wXJ)#ouSn3RAD.5k;7hiql FOs!!tAA uf:X۽ wuvt<=VNK.0=ZݪNM;hcѵ'w 5zW'% H  nSh LϪ'Lmc}`K;IPȂ 4~PAϢ- `0A٤ KY^8bOV?H  ΅]w|ezevY&Q,-JnYҕD]t5k(h|"[hj{*T  ?BHy%mkLraz(C!dXHa'6=[^ϋܲHFC>Y̤ °i:M^n2<;ayi/l I z6ŽdZ&D"|7o7O4tAAF5f*z3@C/JvfѝS%Dx.,;7u# DH  HӒ[֘o5Y_}$0vw DZ#,33S6r_.YYwhh8.mw,Ӛ㫨z3ߥr<)EbAXi<~!_gJQ_8K!}@AGqʱUl[bswd}*d&]AJF^e kDe-gYX7Sp9Cp;-<1Pڦ9r/ιڦ0+BdF}tAA(e>R&N/X~mORΈv;"Dݤ\nˁ^/~rAN"i˦PqŞ &Q/22.  aճ~~̉vlNѶc3;I~m[3L,p6c46pbѸlLįlj\ǡPHL  ,ЬϹi>M${QWv 2L_@)_aX~ a*bVZ; &:H>7"\"J)emvѦl -bcĉ ,\@AJf&"`}[19mIޗo "`Ўxp4 :;ҿ}+ VRTRc6,J;V֙MBEd6d\;:qngqqKr_vlXkVՒr(X&`jq6jN{O 8H~ؗ~N~TtxZ{-Nwn *L\2]܆qlxI\n [̦5_=TJ"uEKłW Q &Hk=+B;FYT$&9!~Gh=LO?# Xq4-H{HQ : Ƅ}wb1s]v04fw:}XL<]v?N BY!c`Aj`$,Lbcюg`+JMsk"55+YI42sq$auּy3j"k,ak[oHTP`1G*E@f0 `[o" dƔtKZ ?N}6Y^Nf HB <"(:NlNdg;Uc&êaCSFP1|\8!3;PY9lGEs A9+ϱ\x>T[iy= %"><5Շe Y|T6?m๫G} ;r#;ͧQQpD|f{v[FjN9pjLq55dw= Awcl ffy(vl2$. "yI|X` J+=xk^36 3?p>RwpIZ҅1~NtmWjaP[)Cg"'xfE8>-NϡXwN)tGY}\fz6Ȩnf*ӳ`Hd}K42-l"5֤ =o2_* :WFhonqU[>| @*-=C@2[%mh/ߡj|P1`f"]]6/D ;.HKf40;8Tx6sPBB*~RyWЧl{,2/x^- d}:=嚥؝f(E}i6keU LBpIHiotCN͜aJIH0I !"5s}]Z'xUO"uc ӗNQI礊F3Cu"`994(X5e++m¡m,k5U;IM`{8t!⊠Y9  8_E u)Db57!s"Bp'6Rʬt]TA Юgi0$P>I@{ +5DY<>AX3ւR5dUXJ$$HHjR7 BX~ H=0}wR7 B1KI?Td4ͅNOF>as'%xَ33ѕ,ݶa.n[OW]n8FjO%@ǐFi !-ϋRmB p9Rb6DĠwp0dMwԪ@ĵ`@)ǸzIۦ^ޑ$+irZ"qnԣH!5k("uS 3| Е5|T, J7'U2!t"֧?LD)ef9Dm}B"MӸ5IJdh{f[MY.} QL.r J_ 0Y\&RY6> axPԽ!#v4 c ٰQ敗W?e-峸հmDl˿hsD&RFy/sNz[J 6Ϡ(_Lر"͕8JK9$s8 WEAJWT04 ; m&|J F8LLn(F0i_XO2Id.p;wpo,}R}t9q!͙ZhJU5ox@L!b|9RJh|/ғkڊ!¡in&62uuihp"ďk|&|]!Req)4\e:fE* KRn-QII"e l?=ƎǞT[+'F6|D=h*edlR"eR9FBz.-iGO4JFAaɃ6.U1="zEd9vұ1V )Tv8e; "L:pAwC` <˼,)_B* 0< R]R}D1܈ 2-5ر>O D e9S -9mFJE] `R} Þ:K5H.vY$ @bo!|z6ȲnMw hG>&יCR-DEE*++v=***PVV`0!@hсVɓ8yd'NmX©ѼR~QhooGgggV8\8rK50bWV ΄JzGsL4 Ǐرc1n8;'Nĉ1fTTTt?Ʋ??5ں%?~ǎñcpߏ9Cرc`pRYYI&uٞwرw{+}a5)'NÇq^ѣ8x N<9X IDATqbW%n|+rCCP%t$^’>oWLEEjjjPSS3gb̙={6f͚ɓ's9k-x{͛chnn믿Vǃ磶gg;gFU  Q]]{;::ocΝx7o^Css3><һ"OP a xo7g]O.m$=x`]cFgJ0T41m4̜9sܹs1{lL6 ӦMÄ  v2Rz3g̙s&Ɖ'w^ݻwƮ]k׮n1:~\&2>gƜ9s0k,L:SNŴiP]]]𰓑HYYPWWwkmmmxww^ر:~mڵ ;wDggH9 JMmFFTq.>KW-`.to[fHzX|9.,_K,x<,_˗/ǃ>;ws=oQ_]]ݫ4MiQ¢Eh"{x׿>,֭[K 3!]۸ַ]&*BEȹHz."}ݸ80k,̚5 7p`֭OGydnDUJ >K.isŹ瞋[oZk `|Ǟ={#`ʕCv, .<#G'EЅ~r+Vڵkqa<#rF#R'؀BEyz0g=p0\٧[~ZyY^̫jIkcqgKk  q7bݺux?ؼy3\p*xx'cy7zGo9Zq3z(,渿|gA~ >%~;̛7OZHțy׿5>epe\veRBTWW?!֬Y#1 !6|gɢY, )ΰH(>%=.'ү$] p+!:bg[(:>HZ AA(I "=:Iv=SAtY /eϞ9 RgDisAgЖф(H  ֎;.um[te >{2?.9H$DdulX qs". Bd;^[Q |)>c0x}3%'Hlo.tWC{J]$]A۶1aS{E_9ՙk;8s߿kvG2kbpִ^f =`~,vtAA_^sZUEh)'ɉ(km;$[Qcg,,'h(Rlܽȳnh %@ w zV\J̠ft.tAAM0#v@MX +H+^p96swb .  G"p0V1~4IMLf<@(AAF:IRoAwsW 1C̤ 0(`XrK,JHkbG<G<ض 5ְ9s$ ÀR J)^/^/|>_eYR ( rA.fAA%p^;]wH{޽{҂#Gȑ#8zh]6D5i" bر?~|ɓ1i$L2ӧOQVV& * |A/\y :AϪ2+&ܞj%AFd"SCIϒd2#G`ؿ?ZZZ҂wqQ;v 'O,m'N'sA7nƏSLQAi>3]ɡ 8-رcz-8qBÇ~n̘1={6fϞsb޼yży$F‰83zu+իpXaFCצᴜ #_DyRoKi /猌7 5Y 7"J,Λ2r7Z)'qx|WM WI/"o6?駟3e S *nj |LڧAZnWqe|tq;lB^cc`MĄ2Af "&\KЋv,`#pl/IQ{Щ 3nʾ ?`Rjjjrc$L~դo>3W!i 0DxI?r^~eKذa6mڄmoD  l2\uU81~x(A@`"h,?,lâSNs'✨^f8u*Y3/G1pd}DJԩS5BZw{ ]Uv!>ZsɗX Vzt2 'E2ɤDng?`%ȌwVzϠ;06_un7r9:e p8j 5ַОڥi?l$ cu+. ]70"̸G}މYeOz9,";#I)JGRFẠ#n :XЋ&E!u zOXllBшC#hc|0? g030 VR$]A,ekK3G?l*"Hh;n" #U>,]~ץMAwS8s;,-spC Xe2rulJ]e\B@tZ^9CC " $R+R5&q//xiYʀH:1)R$3}#͆n2*ŞwQͿyvQ>΁]jׂzd@3dVGU 4yw^嗗XX.DH P̦ի&"_ULjô Nq;aZD`GCŐsI`E9sh-sAϣ_U{jcX L$mTxTMn^Z⯙C&Ϋ  *=EoUk09hBkm*2" uHĐQT)]t1tovDI 6dg9/,Q:Jjt IAJ Nl"Ϲ+_NvC"O*?2-Y OM`wSl+.}z{اULun~UD NcL7  B_d&]A(B!Z7~zLV ʎGLj"2I 'h>,y 'Cu3=_&Ef1Τܮ>ڒslǬfya&2~ܐbJ6HA]!DCQƕ}|WRNe|IAFaM+W>=?1=D]3Jaq#2HHE_!,^It1J٭̟Vdֺ!#F 9mu wA[АVӱcϙ?ىwj۱5)c 4^]A!~o!ƓO8uUU//l# *G]$|>TTTt?*++QQQr~B)0R j:q8dZk858(b8bXhmmEkk+N<Ӷmi,ACc'W <(+{#1I45 i *<$"p%diEQZ{+28]ܖZa ;`ŋ} j8"%@YYjjj0c L6 'O1}tuY6mZ\2Zk>|w޽{o>ڵ ݻoĉ M}}ihpjn _2њd$\$Z0PZB\AhsR-ٖż2!fnvE՘4i1ydTWW0aJ)L4 &M\6mmmؿ?8{[كfq8 O(jkoo/ ]n xf𔺠 :\lLPoS\.z. 1G#`N`tSwܹsq/ҥKQWW#üy|qxaū*'B"s9e?'mqRv1"j -ŞuͲ.ؒ-n͠gfѭL4ʃQ>ùe]Nۦ RrvG?3gb-)zQ[[wXl,X磬Ly`jjjPSSn с^{ ۶m֭[el޼ Fh5Ez⻾>mfFJzAA=e /ner΅_s<=Ӆif#sx /?u+LDcܸq}˗/ f(++ҥKtSݙ:z)7?T `Sq }eeٱM`dfnfq-}!.f`͔g]!A!io}%̒hy nLQJaΜ9 qE/Fmm\%K"q{qa hjj477q(A!s/F_ub]ܡNXeݎAw\ qqc@ t.!ąNU\+KւMQ}Y@9EU?ͺn<RDf#G_|hhhu]ӧ˕q0a\{kx'OT g7o_[ }[FNtjf i ΍,B|*#%"㳔qŹ+Mb6նᳮK'?`O>ÔAjDJ1f &Mn v}a.Ǧ- $m"ew%+fmIr&Lr3=zpy&b*29uA3z=cBz? ڲ d?]a">2va ni ;s>_Na}.!AGJǠ]g.s,&YCЎPlY0uk"fP "DR0 (;L&]+YgJY_ױuVW2M?QUU% _LBYf11&"#_bs:C$%>y3u-]Ϊ-iBĠg\:K&%@ڎ'hW91zK0.D$]F9w֮]Zy]wk]SVVEtVu?1`}7͎v$rD4Awc^t.htu@y~Fr=hYǸ%.\3`!Jsu!}VdD ~Vބ Cz- 7Zy?ϱi&i"Q_H9c14=8K߄8!q 7gteqE32MF0X,gC38Wm.eu$}[r4u7rǞM[a~kVg9X 3>g@0]@c}!.BX|aWzA04+ B,r<í2A7l(TK&U72 gķ0sI)!mmmhmmE,C,CGGGX xxdJ)"eYPJ4SMzz|`aHoߎ_W^{mAp5+WWƯ7O:D!V+_lRFH7=c1p❵]Y"/#K!b)"S[r{ehO@?@IE]q}1c&d=wy6UM컉\ t以DKK y;ؿ?ߏ#Gz#^18~8vP)TUUa2eJO4[Lٳg|H$_ҵ>K/-ʱ_tE];_׾#EB&όfz+'رW.C4\B IDATsVv |((^l u s;_jbAP@mg(NT)dx饗 /`hnnFGGǨ5=GbnWVVZ,Z .矏ŋ,| vZ޽ە*++)塇o~ R+QP$n!3Ơg[f[6X̻-]bL٠*XL]Lر>,.2  pYcI&zO=ձ1n{5˺p-͢[a9|*͠QMyD4d#f\諅A%o(=BL\/YV5č91*$/"6n܈xpA [n֭[}˖-_e˖~7***\ѵ>L:uHΣwk鍍"n\G, J. 'R\ ([s6^ΠJF;LPZL@rl;+͹P PH2gL0.jh?#2O/~ \qW\O=0!Hg׾5\y3f .)<2ˊ@vTF"zWʺ<$ot646Mά[`q1C`qEW.nƠsa75z*P2D~ fEaeD:6]}uRWu#ĥ5}$'"C4%]3y]+TtM~W:Io51)ӚvAw}{IXt-̃ :|n z?J:H:dv.gs.mAd fk೭1KzDa~z,֯_/%B!fgEhHYbu|\Ac썯Śs<^ǐMFלq1q5=z`oA?#gόtz+i<&݅\=sv(lZd{<9+@Da?ɕr,—:/ˮ\Iȃ|;5MiCe.p"&6!RuV&pA-ˮ~$k"&.TV0Ȃ)bENy 2:ݍц-5 r2dtoV&a`u/ևM46~BXӞMy[.#$Svf=hm,S;|7H Ѩ+-5\SxWxGd+٦770:#Ai9~v9 g݊A'sV0 D* W/AD̜8y-v^̞=*8gmַ̠jJv*)n2\,㐺P~ո{^xe bLD[tm8;mC `as `Hu3B|>g``}}}Coo8z(?>Ӂp'%KLqxG#??0hu-,y7̿w* MеE$e-W2e˨ׄx ".50K؂ Aq p5?Lя7ÇkG_p!M6ڿtR-v6md8SJ8\gr(s*,X:cЫ4hF2Y"#P$:*z.%D#Vzhl^KiR(XX x)R-&㨁A _kHY|뭷NK/d8p=9o,p:"ۖjM`Z|xy{]"3ΨBjq .)i_av jvbg…gE]T5~U4ԉܢ\WѩU>adU֌1#󞥷b`82`;ڞ_Z6ȶEDRx A/;$$L@ I70AٳGTMy9r̀dEVf<" qQdti!>!.~3hÕXy,[*7ղ#2ӶRaMHH@)8_|X~PcL$LP&\oo?5(gub$T3\B},3}s|7|7)K(mx5n`Pc8x #۹'n+ ]]]fPkސPL)â::`a[tMDq{ed[8vP6Wjf"?Z2Dz1D3F0.eDXDoo/ׇ^\|~  ,I')O'ضV?5Ιo:P+G3gά*X4('Fc =~/A-XF@=FT"GH\yVGD]ߘpW o/i8!CmJDN׿7`9IBY -YL{lk?f18g}8bh3}v5TFU"k؍ kQC-q?9b1j_`LPV"ee1{:{{oL2d[%Q[Xd"pBMU̢oB\83g] j'O4$ hs 3F"L-(s$`hY,=Ybx,$BH[;\sz0SkՑY N U7LUKIY zF#3$+,VHzss3l>~%4@aTX zyR2D2fI du.#U`E $ ˆ[zܾ\tj[l6:K)iQFJg7mw)AXz2Z\46$&+mSSSIСC%|FbpUfN'\:e_F[ :@Ă@B-BapUE/"(LFDTַ-h?^ؠ@osyn``H9HR5㓦$B3f@-XC̢DKw])~Xf1U\j&AD HQz=  <?tT~|Jg"khg!;a3LP, E1Asg2d!ZҨV@_k $=u>,V"xYb2E>kqg,'#sSW}M)A^9ӿfw?t@?S(Ooo/q~;f.&|<ى˯55%h8ܥ!.oT[J`o71?_{mowg+WJhQ0,pa-AٶvF[КÞzXF;Z8G͜WO|B>CŠ!b1 -.5~SC#NW_ oŋ1oDGzk!)'N޽{sNر;wΝ;m6?~ ! ZJZS NL|n HAeOHbÊ"i'Ҧ|n 9v~C=EK1kQ)McTƌr!S9_)d[?"l&qhL`@B5.x+(8-sڊ[o˖-^ҋSL)ShѢs>sxzj^iD'f'}4a2Dy/ S_(z_+cvdȐʚQ{siZݾZdJ0^:(ζ;e$= xƜ(H;Agkx:oIz*u]n7x#nf\f2mcٲeXl>C)]vaÆ شi:;;vZ9r8+"t֒.ࠖ1lp6 9dY/YɔTbcO۫CE4Bu h%%d3"ܩ2DUiuu1qdS :D !ɠB麌Ll"T o{w wq^!`,X|;KRظq#x <2 ]o~jp___cBDuO~vЫ9]YI`*Ds̶ $בdbg+ûv.C,<#`G?R߮YGgq{JED ~g«`a-!~lJ [)1 $o<~|lAq@Iq-`ٲex_%K*&7pn|ӟ+gyկ/bI>: IcWZf 0ᠨR+-Ao ~dvWY]Gydž+d[+u&l۶,dZ1‡d%/ q òoFXd'($ypI%)0 Pa=Ag/Z$|;G6i;wʕ+c&_!"Ղk-9 $AQNAQV+)?m| dy DZ m>zӇNAx[9L&sU> ˧=+QP$v,۲mD@&fhqbdo.\q1_blNz v11!lY#PNΈmIN Zc+`ԩZ;v&188'OV_k %X`,B(U玙fEXyL$-b7~ϾٚN[Xeܞޯ36e= uy[h_/KyaO"pӌDr!gjĂNm=LH؇Mp6pO,),!9aK- (X<)ݚXbͥSvUTrGz-qA[ b`PC2e;:vڡ˯5"7Xp0g)(X<ѧ[lZf0V g1U"{nn+so}= u.Ih:P[`@1$;47tzr6.lo0#3@1Caqn @9c@<5E7 4H8X2%xC6%M+ -Jvo͝R =%Fȁ\V0!CPPu Pv2YZАпA H!u:ԧ!)Q. }eHA Ap]0$}4N}w*'N<dutlKxr~Ԛ^eu,Ű^b>p|b;W3ef`4B%<5D\b *QƸ4IQGqᡈ-_ tcPjuR0aF,vi:7G]\yLAfσ~YLFP0$0mڴR爙َ=jH !58d%*bD9GLtVQXr& rYfOY,O߱[ (è|Zhp@$o } # A [?c⥫.(gc*Я$f͚Ç3g4kWZ6ՕkHD>RQApDΝGC=?V txD/ΜF폒KECBA'Bi+wq9j#Az[i/AǚH9PZ>͛:t&|2zpHf#_㢀jLミ_ (-%QÛ&]sZQ= Tb)2:9@ X°BƠk܋Py@YgJ!Tc`P[?~d _j!5{>Ġ%Xy`>֖PCCLyV}KGu\Ő$!|򁸉ddn3Tgķ+§RT:tԏ4I701\qm*WQ8+DB8)qegHc%d}SZAvmn`PcꫵٺuŁ"ۘ7oɤX#@i=8􄓴_Ua>$!Y;i}O=њ^eut|9, -tNu/578Y,1,몈' 1 B|_9긝l$őJ&+b;$>}3$62$Q/Oz_7lk1j4/#)MZa'd :dR eq@\a È\fDsߣ{ya[:ѕ L "wco¶q% ȞSVZ.0d2@dzXVjU7f'؈YfE9kqךA5 > "_̆UfQ-+s}_u^ 8Ey`%& sT_ \c+p mL&0yipu5$q饗FqFI_|Qo Qzw]V^ Ř7w<= +?"w~~zr,Iz";zв󸞠!m۶M5kD3w\ضm( |LH V'h LD4Ē"=è y{zo!#sZ%QF+"5eW)Vӧ$H/y=Vu20C.4o& I70A,ZHɪe c-b.Ib8 :$A}O1D$)WN/xշ˺uD.[!%H!QkhkŭZɷ`2Qr$A I70A,YD_򗓲/BU&qtKxČ\ 1:i{>:By?Wx; QL%K._Qš˰DyCʑ(bX8HRUBc*fgHA .C]]]d;6mRjҵƍZҜIt>Z@ZgmCRF4-h<^> 4誯"=NMڎTbr.د_yc g=:a.|>f)QWx"-f*2A_Ivn`PH$Xtid;Ǐ͛']ׯ_oHz`"q-ABXE߾8 WOxi+eSNY(d|oKM+.>y]`8h>B]hGO*cu9"c!ao%bI un`P;Ilذ!\yf qA&^ę_ ]ӳ01{v^Qp]ǘC]$eܚ7_f77LDft <$ZQ'r #ĥ A zdYƠ5HVjHA-oyyIҟ}Yv7"L4rWBE*Fa x?nb L_ Q+ca"'ZR:{)=rQ3 C})|eܚݑbYi e_h @y͐tō7ވv֯_CMv?Uȩe }\HϘ!4LQS2Q'ÿ/^*׷. ,L/AD!⟵t1Azv>nZDz3ᛠ3 \hH4$Fa6/^}ÀYZJp?[wuD`jr_:NVD\d( iw_&uaa,mҭoC$U/ INWGÎxe&;zą]9 l*.A;+Hy"׋ㆤ0nf-vtd,֮]v.B\s5fM ~X& :d#'&P&OPLRẈXt^Ze}i"zz֫L]>DЪmvq,Af1Aג%W\R^AQC j7t;}o5 f9 xqЯ2)=Ph@)H uT~ |hg6էނ:R<$V ^,>{_=5}btY6 z8< V [zo!5 ];ǎ~VU~i2 y%ΜqbA UBNŠ.k qv@!AD|p͉HJ[>D_:0KBŠ+*#IZ za7^_A{b0| "G읔2$`̝;7^xAKIжl23x&@["@7#h$ R LbD9B6Ji2MfO72(2H"ZH&Sڈ,[HY/8B\ˇ<"ce;y(pd>g`HA~wdb77P,#۩7;> HէN N\, o $Pmt3qJHzl\OAajAT\4>LIA zs% HK cuD(fFJK wn``Ho| _v~_bo}+9E #6L[FY@0D1 :vNqq:-(QW)q+ cz ҉Ad9vLKHjLaC!ũ̢e=HK[Z I708CmۆΪlcgg'mVUG&L;*7 Hsq "ԉ!eh*5M^*Z~ABFr\>'DE3ru,m*T7x+ c[$Una~siaHy)ShSOUetkʔ)̀9,o_-%6y|[bHDd|'ǀ\^u6<υm=_I2\AiI: @]A/a( 'E]dHy7MZJo u`P]Ҳ9^b 2:^My>ƟDu~,eU`I7-E;[.+t zPA0nr5SW}Dd+n`px;7oc=VUm{ǰi&-~~ >V5r>VSS3X8"$ 总q֡q#/'0 :~,ob˚bqaED "?qW^L._#t(:`ay8ivn`p>`ʔ)zW&6«}݇f3X Q |A^"B]"@$¯;Bټ8D'rsX1h+ TV'x+J#t(ț:} U IDATb60z 2$G>m֏>hU_;RJ_$Y$f&:yaDE-b.P<[}g믅iJ?"CK؀sB| - CY8afpC\t$ṫ:]$<&"0Vw(Ĥ7+tR-~`֭m֭[3hd,X hP."1y2=@9@Y%7*fBL >H"&h6@33O} n`pARfƇ?axWvx`5X bV;'ZH[!!< bP chNI+a-z3ӘI[(i\PE #!,qDiIdHy6m{9Z"Xz5{9mVXaGp$X(%HH 4.!{YPqITe76=LP3̸ C&97a >M4sXuI&@p{K% 4$ʆ"Ac.z89`_A=wD+d=߱5^jYC W|3f駟/~^Ъ.O -!$/ A^uf-wzÌD_ibe%D1U2y9b.[ J=Zʳ^gIKc!IqugGp!!-Z-)|DYߏ|Moŋ͠0.FPW s 4C^ 6^dJ *lйָ#c;LPuV/=!!i+k_ZY;vf} Еₙcv}D'.ЕCgƺ$$|i~(3dJY A{h23AגH1T!IC,2ʐto1{lm>ϡ/zfk]3!ZW˞/t;!_QZL=nm=)! /VWn9K$=* qa՞g-6cC34+hM?g^٩l"73]9fb108܌fo޽ԧ>kߏ={h|dՌVh;̪>(yaDEsP39_;AceE"p/W@l9~MqKx+8Ը{Z 觫NP em!)kf+_ ֬YK]jw5`F_})^vY)5eSk$]iJy1.cP 2$Rwt gy􅺁y ˲X=9>xٻaYAĭeggη!13*PxЊOyu >=Hc¦O 9aB11l( >R 2~C\bQ:f *|m;Qw I708sf逸OSut]/ޜ9sGGcP 3ŁvsԴQwu`r{j mPrZcg*AZjSW>:ڠX)|͌y,ܐtӧOǃ>͞yx{ރm6?cÆ }K_BKKɨ*kףDOBpL)cJTTi=U[aRÊ)fJ,>fɥ(yOm/1}ywj(O|'LGM" hR YyR% QPrhpՐ0L=P,>GB"鱓X1;z)iv})[B&H+_$,8]ׄ?A>9ASk&k zPI@Hpx*6- zLb+3#)/M`.!+_qb~^T:=z9vѦqm+VrBQǟ>vʱ=ڿNxoB(vQ'PwM̐tf7& ߐ\=iZI(cNu\!Ȯnġ0A2V{r/>K! y?zǾ8 t@4hN1_&=o!%Qpx vH%ȩU=x؀N #Hx$CVʔIt>co([E_U;>dy:{9V F;}C{hGE I70000b\);%!,Ja/7N IIx1LU4vr+$!Лm[nHAّ,d7.NXJjD?gidҡyx>dK](9#h- &#n~A5h]>=+(F!U_t4sa !eE6;iJK#"v%ulTőr36u*K ]Ŷ< h,(m;1OuWM[gnt50000"d2L;/LLl̬xxdwNMA9K t.V"IMRt94 F&V9.,9R‹s 5"C@R=sI-CݐtI %?dw~_M7V"D} s灈,@ht61ܾL=n哉CLЇxJك BBB"W\G}'q~e tuyAaHA5;·3>G:T]㖝xHs R !eժXIxAC˪= >'$~)0 apW-A3j\L‡@ C [DJJTw6Z=l)S]7n;1"nXݡx[ I70000f8a{1-T$ۅ+\!sy!nD!.Q u"lhGzFS_!b, RgTMÐyaWP7Ā8? n7 ^?o!*}V||`ꐄ"3hةt{[>C & "'߽_?;ws}CldS J2M X)E`-uPTw5젏gE>RE_[|Y;tO?( XD1KrcI' u+x i40x~llYr|n````0zIf V7f_zEk7z{m"/\JLbu'*Þ&,NxR[P!Q-Y,T_y 8jaQ xR4$༚g3D%;ฮs.$0)=hCezДDIq: 8IL2yMSA[ ]ٶʂ>8BU lhQC?[oD>$0 ø[;Ύ_=s2lޯ.UUxU},0.qcPVѵ7r*^m $ HXJе^VH:AjQgt\3*:囤a |@{{Ҽr7wG;:,ȥinrg=Fe $Wq讳ana@gg|$-nsYi{Leu]Ir [+ب&NIt0I7 0wN7QEYk-ɼqk 0 c zɂ t$0 0Jf]$ZuA/7nna1m=2?IU\"Z݈ 9Ir 0 czM"YZ3/{!!`upS mGEIaat*,QtIJ=:(V6 t0 0&Q 0Ar~8Iݽ1gG<< ;C.(^{menaFfc@г^d&^e_$@e$EF -k^Sp*}*ȣAҙx ΢La w,=MG+IqDB#eqQr_=rO|I\}ooOe<( r:&aar36@zVYu*]2D˽~*q?V['ID"xonnaluvZ9z719D**ڎrjt9 7$mAqV$0 0foע$LkUk_Z$FLxq9<:Sߨ"aa*nAMgYPZ&aadu LeAp6}ZZr&.&&a1C)v42],UJ}ZNP&mSʕtI7 0Th"Whon%JmkR~/uh).7Ǣ&P*P(P*(xu4\.GCCMMMr9@cʈ!(.k74RBب6A߼i͗.2ԁ7LҧBS8y$gϞΝ;顧/rҥBaʯ9ٳ={6mmm̝;?>c,\n f7```ӧOsΜ9Coo/ϟ9zzz8{,ϟjFQ4pdܶ1{l̙C[[ͻnq,]fg#X$Zy%S6T{`t"c=Jww7o&o&>@uzfey7Z[[{?̊+?իYr%ЇlCCC8p`d:tÇ3mWE#,̛7e˖|r^/_Κ5kXbfͲcBFONY.畔Z*FͽxO.]=zǏs 9‘#G8~8|u)&3>Ǿ}{nѢE,];３%Kd-[wͲe˘={u`ѣ#c;v{cǎqرi;bk׮ϟ]t)w}]`u1l~5ī~inA_MW𶙑Izb޽޽={/gUԩS:uW_}u-ZڵkY~==ׯg…qeNv52vw"d*ΝܹscYx17nfݺu_V}]z-9bQ)m6m6ؒ%KXb+V`\+Wr]wQeA/ǿeo`~W jOl ɿegե޽{ٹs' ۷o>%yb>6}}}Ͻc=Ϛ5kXz5vuQ%T&%A7թCN&A!Y8,'$=T*/ݻw[ epp]v]o<3 k׮\ո{\|L'Amu=AP"J*"H ~8+ADp5W[4TQOuaV:prʼn ~0߸d' lJ~|AЫHtZYOգ#@p\ &m# BxCyJ0/`þXW+;`aӖ[H+ zֶK>vMq]v1o`|=D ̈́6/n%-uMATPu8sI1rnnaUay=!ArtL*ws/FvhB5D VxKBg7/ϚK|h "Oؙ/UcI&aaT*sZomr2,fi;eO9B ?sXm}%`[?n{?'zЖK^_"^sldaӊ,).ՙ MZ,4@/Dž¿W~ѽ߾m>UnItUG򸣳]~Kf'8ZL}>)X$0 0R͊*i[($YO >: [7TqʦP:vF"tOnr?sφuZGA<ꇋk5eI7 0[3l _T&:4Η|suC*;3o#xyjgڃ{{~Y=!+ͺ@'0 t0 ø5<] Xu,|o0KTZ|jkЌZ֩'0n'-a(;c:7;M;~W A`ۣ z,&a1S^ɖ3]9A-^tMSƷ2ֈ }|_vBymYǏbPtF\T"&&a1cqJrus4e!z(z}Z'7xRǴ;8%Rd"]Cľth|@AA״OGOXut0 Ø/S:'rJwazK%).UܤTA%&/AE~> [u;.?עݰ{I]lS#t0 0,^o7 ט g_<5D7/NUG M 0 cF7e=%j7R͊ }&i@fy狨"A>6łq2;k*.Ju]jna3$7ƹ4ZV'T+ dʼnP QO9PEP=PoKd0+hna,HKԕ/^",yY}Be˔Y_ot~I)"$([e%ǥӫ"N^ߣA/oc5vPHRkJc:ȑd@hHkHQGKz F[Lc4yǮKwxܶ_[0n=Φc"B(Xf[!)"^U}.}fk]JEz Q[Mp8'ӯgס)F ۀ{%gsQp8M5]GveQ.3|6NۏGН?u".UEc, 8ab]+}aEƹ^d$䓓:Mb$A^?J:#3bM`Dg{q3Zǀ|7jc:~ߟ}QʧY7c.xX|?ް@:s?v__9y5 'C5fi[k-N@˹:b^DC_\eAuzֶzO&B1֞uOtklr=x7p%C1`7F? %=B"0[I~7$q[Z?D=I|Tu$QIRffJ5';oI.uEx5=>8tJӣ^zc@Fk 2MKkOA;HgM[ m+JsUuy@6 +#X~nnc7YꦂtiɅʓLBX8<zIa`I7cq$Qio!im'ظE/] )SE٭O4 «fZhh6*&6$ǁMN TEر||XCT="_L&gE.XTnLg9>hCu~ݗƨi<ĕDgOu#ƨ'L;k4o#.(ˤ&z7+,:Q2/|^]Iů0ι_RB+TQ4At[k]u]Q7gLd3I"BEO\+.JeFIȿ1s)q%M/F=~?C$Qϑl3D7H>"*k$~pGRanL!)Y+?e^nq"4,G0n%HsD(4OO!vM]#"tH;kʵ5$Q#,_&(ݵL^O_㰑*C}]]ds H?)/}iZj8_x(?tPiױks:$QWI]F-`dqv,Ә*I돎:nAMH"_Eҷ3.ᳮ\,8ܨ='QQ iNp',k1-A@Пs婣>sXIN*աw)apQjxf9_?)׿_ Ԃ%$mv,F=̜gdd?ZuTG}#=,5%}xխq "{/*7כW%pyc𕋧wE1i *I*G7Kk|B8e@K#{]Ra1aQe+$ I4֒^o^'1tĪ84n{lT3A7 E>LaǺe~to_pſM.skc(²*g9!.Fg=t-aL$uf_lH=xSE"ء՗-&F^*|P ߽Ot7tNx%.ni44(QWO*.Qnþ_jna3Wy~ףk7S-/%,+:^Dg ő)2J)%i$7Jqtw.Q>n6*PLaQh5TU _|ٟ҆!`)I}FNF-T~ Z}ZI{zIaٷyX$0 0";#ݵ.^:{b34b{cIꆖ*+ݰDfڨH˔mZ:̶7m]oԯUӉk}#)|oׂIaa7]vC ^4WDjG l{LրHJ,).*kѵPz҅_iنa1MYs7r ~_9}\d֚kvZ k6T#AkDKb]rOdܺ0 0|>ΝDŽ\*ߦz]O8U+ײ?Ũ2'%|tfBϵ~om\4X$0 0)J7^ODcT}դf3 zi/A*#f(( lN}SOϷaa@3صΆ]sg(P.m5=kzmV4y^ SX=@sz)us?~L 0 Øo#ĺu[7Wqn>QW@L K'Cm7I+X#A/xUDcЇ>r9}oNaQmQ-͏^{[!|!/:W:ezQi.Oez<Z{/ҁ/I^ժ na">q|ï~~Ο=M[#'JɗPCu3HгWv<^>UTcD hr_ meU}6=7I7 0 cٶ=ho?#)0k݇h'p-_Ȭ\1 E dVAJ7Tŷc¬С/>/aWŁ?n R< wznnaF[plE%MhS~Ӯ5B!NRMvNBDQ=O {j=t@cbR7~ǜ|l&N_}7L 0 èGYO뻌« Y kJ'և 7r "Y7}ME&:uGUr$ /F~];BCxUYj t0 0okhoGds _g|t柌%|\)=^xG njOFEYVA+ G"!H@  JI?P~}/ |ǎ 瘫`)-&aa:xX6A|i}ƅaGL EQPN:J{m'Uh+^# 'eE7OB'#{F[ۅ* $0 0[O5p&ǓOM6?ZK?q N_LkZr}C{T#$k\I5rŻ*_뛓M'#rM4\dg h9AwrtR˥m7eCR>ݙ\A;97I7 0 c ``w8)8#!BKp^-%M"ɑo^QT\8Lkgy%:.c4\a{dD y#RQtZcCb6OŇf-'e#rl\&茇&aada;5%Gmk358PA˽b@B=1U$ URgN ]zE诉GZI1H$EGMߒF=$ UPG@!G('b8 \pKT|[S\?|NVB/sO;  䒪^%DzK/Л5ZGsŸL [Y?(+g$qݺnz&aaw-ucB}BǸ`j5-m&iqa⥁YM.n yF6щx|a#8U "s} 21"H!"R4Az Q<w~su 5Wܫ3[ sc ?yEgIENDB`mkdocstrings-python-handlers-1.10.5/docs/schema.json000066400000000000000000000363251463457115100225250ustar00rootroot00000000000000{ "$schema": "https://json-schema.org/draft-07/schema", "title": "Python handler for mkdocstrings.", "type": "object", "properties": { "python": { "markdownDescription": "https://mkdocstrings.github.io/python/", "type": "object", "properties": { "import": { "title": "Inventories to import.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/#global-only-options", "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "url": { "title": "URL of the inventory file.", "type": "string" }, "base_url": { "title": "Base URL used to build references URLs.", "type": "string" }, "domains": { "title": "Domains to import from the inventory.", "description": "If not defined it will only import 'py' domain.", "type": "array", "items": { "type": "string" } } } } ] } }, "paths": { "title": "Local absolute/relative paths (relative to mkdocs.yml) to search packages into.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/#paths", "type": "array", "items": { "type": "string", "format": "path" } }, "load_external_modules": { "title": "Load external modules to resolve aliases.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/#load_external_modules", "type": "boolean", "default": false }, "options": { "title": "Options for collecting and rendering objects.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", "type": "object", "properties": { "docstring_style": { "title": "The docstring style to use when parsing docstrings.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#docstring_style", "enum": [ "google", "numpy", "sphinx" ], "default": "google" }, "docstring_options": { "title": "The options for the docstring parser.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#docstring_options", "default": null, "items": { "$ref": "https://raw.githubusercontent.com/mkdocstrings/griffe/master/docs/schema-docstrings-options.json" } }, "show_root_heading": { "title": "Show the heading of the object at the root of the documentation tree.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_root_heading", "type": "boolean", "default": false }, "show_root_toc_entry": { "title": "If the root heading is not shown, at least add a ToC entry for it.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_root_toc_entry", "type": "boolean", "default": true }, "show_root_full_path": { "title": "Show the full Python path for the root object heading.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_root_full_path", "type": "boolean", "default": true }, "show_root_members_full_path": { "title": "Show the full Python path of the root members.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_root_members_full_path", "type": "boolean", "default": false }, "show_object_full_path": { "title": "Show the full Python path of every object.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_object_full_path", "type": "boolean", "default": false }, "show_symbol_type_heading": { "title": "Show the symbol type in headings (e.g. mod, class, func and attr).", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_symbol_type_heading", "type": "boolean", "default": false }, "show_symbol_type_toc": { "title": "Show the symbol type in the Table of Contents (e.g. mod, class, func and attr).", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_symbol_type_toc", "type": "boolean", "default": false }, "show_category_heading": { "title": "When grouped by categories, show a heading for each category.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_category_heading", "type": "boolean", "default": false }, "show_if_no_docstring": { "title": "Show the object heading even if it has no docstring or children with docstrings.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_if_no_docstring", "type": "boolean", "default": false }, "show_signature": { "title": "Show methods and functions signatures.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#show_signature", "type": "boolean", "default": true }, "show_signature_annotations": { "title": "Show the type annotations in methods and functions signatures.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#show_signature_annotations", "type": "boolean", "default": false }, "separate_signature": { "title": "Whether to put the whole signature in a code block below the heading. If Black is installed, the signature is also formatted using it.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#separate_signature", "type": "boolean", "default": false }, "line_length": { "title": "Maximum line length when formatting code/signatures.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#line_length", "type": "integer", "default": 60 }, "merge_init_into_class": { "title": "Whether to merge the `__init__` method into the class' signature and docstring.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#merge_init_into_class", "type": "boolean", "default": false }, "show_docstring_attributes": { "title": "Whether to display the \"Attributes\" section in the object's docstring.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_attributes", "type": "boolean", "default": true }, "show_docstring_description": { "title": "Whether to display the textual block (including admonitions) in the object's docstring.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_description", "type": "boolean", "default": true }, "show_docstring_examples": { "title": "Whether to display the \"Examples\" section in the object's docstring.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_examples", "type": "boolean", "default": true }, "show_docstring_other_parameters": { "title": "Whether to display the \"Other Parameters\" section in the object's docstring.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_other_parameters", "type": "boolean", "default": true }, "show_docstring_parameters": { "title": "Whether to display the \"Parameters\" section in the object's docstring.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_parameters", "type": "boolean", "default": true }, "show_docstring_raises": { "title": "Whether to display the \"Raises\" section in the object's docstring.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_raises", "type": "boolean", "default": true }, "show_docstring_receives": { "title": "Whether to display the \"Receives\" section in the object's docstring.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_receives", "type": "boolean", "default": true }, "show_docstring_returns": { "title": "Whether to display the \"Returns\" section in the object's docstring.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_returns", "type": "boolean", "default": true }, "show_docstring_warns": { "title": "Whether to display the \"Warns\" section in the object's docstring.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_warns", "type": "boolean", "default": true }, "show_docstring_yields": { "title": "Whether to display the \"Yields\" section in the object's docstring.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_yields", "type": "boolean", "default": true }, "show_source": { "title": "Show the source code of this object.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/general/#show_source", "type": "boolean", "default": true }, "show_bases": { "title": "Show the base classes of a class.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/general/#show_bases", "type": "boolean", "default": true }, "show_submodules": { "title": "When rendering a module, show its submodules recursively.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#show_submodules", "type": "boolean", "default": false }, "group_by_category": { "title": "Group the object's children by categories: attributes, classes, functions, and modules.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#group_by_category", "type": "boolean", "default": true }, "heading_level": { "title": "The initial heading level to use.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#heading_level", "type": "integer", "default": 2 }, "members_order": { "title": "The members ordering to use.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#members_order", "enum": [ "alphabetical", "source" ], "default": "alphabetical" }, "docstring_section_style": { "title": "The style used to render docstring sections.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#docstring_section_style", "enum": [ "list", "spacy", "table" ], "default": "table" }, "members": { "title": "An explicit list of members to render.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#members", "type": [ "boolean", "array" ], "default": null }, "filters": { "title": "A list of filters applied to filter objects based on their name. A filter starting with `!` will exclude matching objects instead of including them. The `members` option takes precedence over `filters` (filters will still be applied recursively to lower members in the hierarchy).", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#filters", "type": "array", "default": [ "!^_[^_]" ] }, "annotations_path": { "title": "The verbosity for annotations path.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#annotations_path", "enum": [ "brief", "source" ], "default": "brief" }, "preload_modules": { "title": "Pre-load modules. It permits to resolve aliases pointing to these modules (packages), and therefore render members of an object that are external to the given object (originating from another package).", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/general/#preload_modules", "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }mkdocstrings-python-handlers-1.10.5/docs/usage/000077500000000000000000000000001463457115100214655ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/docs/usage/configuration/000077500000000000000000000000001463457115100243345ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/docs/usage/configuration/docstrings.md000066400000000000000000000677631463457115100270600ustar00rootroot00000000000000# Docstrings options ## `docstring_style` - **:octicons-package-24: Type [`str`][] :material-equal: `"google"`{ title="default value" }** The docstring style to expect when parsing docstrings. Possible values: - `"google"`: see [Google style](../docstrings/google.md). - `"numpy"`: see [Numpy style](../docstrings/numpy.md). - `"sphinx"`: see [Sphinx style](../docstrings/sphinx.md). - `None` (`null` or `~` in YAML): no style at all, parse as regular text. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: docstring_style: google ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: docstring_style: numpy ``` /// admonition | Preview type: preview Every style gets rendered the same way. Here are some docstring examples. //// tab | Google ```python def greet(name: str) -> str: """Greet someone. Parameters: name: The name of the person to greet. Returns: A greeting message. """ return f"Hello {name}!" ``` //// //// tab | Numpy ```python def greet(name: str) -> str: """Greet someone. Parameters ---------- name The name of the person to greet. Returns ------- A greeting message. """ return f"Hello {name}!" ``` //// //// tab | Sphinx ```python def greet(name: str) -> str: """Greet someone. :param name: The name of the person to greet. :return: A greeting message. """ return f"Hello {name}!" ``` //// /// ## `docstring_options` - **:octicons-package-24: Type [`dict`][] :material-equal: `{}`{ title="default value" }** The options for the docstring parser. - [Google-style options](https://mkdocstrings.github.io/griffe/docstrings/#parser-options){ .external } - [Numpydoc-style options](https://mkdocstrings.github.io/griffe/docstrings/#parser-options_1){ .external } The Sphinx style does not offer any option. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: docstring_options: ignore_init_summary: false trim_doctest_flags: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: docstring_options: ignore_init_summary: true trim_doctest_flags: false ``` ```python class PrintOK: """Class docstring.""" def __init__(self): """Initialize the instance. Examples: >>> PrintOK() # doctest: +NORMALIZE_WHITESPACE ok """ print("ok") ``` /// admonition | Preview type: preview //// tab | Ignore init summary, trim doctest flags

PrintOK

Class docstring.

__init__

Examples:

```pycon >>> PrintOK() ok ``` //// //// tab | Keep init summary and doctest flags

PrintOK

Class docstring.

__init__

Initialize the instance.

Examples:

```pycon >>> PrintOK() # doctest: +NORMALIZE_WHITESPACE ok ``` //// /// ## `docstring_section_style` - **:octicons-package-24: Type [`str`][] :material-equal: `"table"`{ title="default value" }** The style used to render docstring sections. A section is a block of text that has a special meaning in a docstring. There are sections for documenting attributes of an object, parameters of a function, exceptions raised by a function, the return value of a function, etc. Sections are parsed as structured data and can therefore be rendered in different ways. Possible values: - `"table"`: a simple table, usually with type, name and description columns - `"list"`: a simple list, akin to what you get with the [ReadTheDocs Sphinx theme]{ .external } - `"spacy"`: a poor implementation of the amazing tables in [Spacy's documentation]{ .external } ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: docstring_section_style: table ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: docstring_section_style: list ``` /// admonition | Preview type: preview //// tab | Table Tables work well when you have lots of items with short names, type annotations, descriptions, etc.. With longer strings, the columns risk getting squished horizontally. In that case, the Spacy tables can help. **Parameters:** **Type** | **Name** | **Description** | **Default** ---------- | ----------- | ------------------------ | ----------- [`int`][] | `threshold` | Threshold for something. | *required* [`bool`][] | `flag` | Enable something. | `False` **Other Parameters:** **Type** | **Name** | **Description** | **Default** ---------- | ----------- | ------------------------ | ----------- list[int \| float] | `gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | *required* VacuumType \| Literal["regular"] | `vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | `VacuumType.PLASMA` //// //// tab | List Lists work well whatever the length of names, type annotations, descriptions, etc. **Parameters:** - `threshold` ([`int`][]) — Threshold for something. - `flag` ([`bool`][]) — Enable something. **Other Parameters:** - `gravity_forces` (list[int \| float]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. - `vacuum_type` (VacuumType \| Literal["regular"]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. //// //// tab | Spacy Spacy tables work better than regular tables with longer names, type annotations, descriptions, etc., by reserving more horizontal space on the second column. **Parameters:** **Name** | **Description** ----------- | --------------- `threshold` | Threshold for something.
**TYPE:** [`int`][] DEFAULT: required `flag` | Enable something.
**TYPE:** [`bool`][] DEFAULT: False **Other Parameters:** **Name** | **Description** ----------- | --------------- `gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
**TYPE:** list[int \| float] DEFAULT: required `vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
**TYPE:**VacuumType \| Literal["regular"] DEFAULT: VacuumType.PLASMA //// /// ## `merge_init_into_class` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Whether to merge the `__init__` method into the class' signature and docstring. By default, only the class name is rendered in headings. When merging, the `__init__` method parameters are added after the class name, like a signature, and the `__init__` method docstring is appended to the class' docstring. This option is well used in combination with the `ignore_init_summary` [docstring option][docstring_options], to discard the first line of the `__init__` docstring which is not often useful. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: docstring_options: ignore_init_summary: false merge_init_into_class: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: docstring_options: ignore_init_summary: true merge_init_into_class: true ``` ```python class Thing: """A class for things.""" def __init__(self, value: int = 0): """Initialize a thing. Parameters: value: The thing's value. """ self.value = value ``` /// admonition | Preview type: preview //// tab | Merged, summary discarded

Thing(value=0)

Class docstring.

Parameters:

**Type** | **Name** | **Description** | **Default** --------- | -------- | ------------------ | ----------- [`int`][] | `value` | The thing's value. | `0` //// //// tab | Unmerged, summary kept

Thing

Class docstring.

__init__(value=0)

Initialize a thing.

Parameters:

**Type** | **Name** | **Description** | **Default** --------- | -------- | ------------------ | ----------- [`int`][] | `value` | The thing's value. | `0` //// /// ## `show_if_no_docstring` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Show the object heading even if it has no docstring or children with docstrings. Without an explicit list of [`members`][], members are selected based on [`filters`][], and then filtered again to keep only those with docstrings. Checking if a member has a docstring is done recursively: if at least one of its direct or indirect members (lower in the tree) has a docstring, the member is rendered. If the member does not have a docstring, and none of its members have a docstring, it is excluded. With this option you can tell the Python handler to skip the docstring check. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_if_no_docstring: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_if_no_docstring: true ``` ```python def function_without_docstring(): ... def function_with_docstring(): """Hello.""" class ClassWithoutDocstring: def method_without_docstring(self): ... def method_with_docstring(self): """Hello.""" ``` /// admonition | Preview type: preview //// tab | Show

function_without_docstring

function_with_docstring

Hello.

ClassWithoutDocstring

method_without_docstring

method_with_docstring

Hello.

//// //// tab | Don't show

function_with_docstring

Hello.

ClassWithoutDocstring

method_with_docstring

Hello.

//// /// ## `show_docstring_attributes` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Attributes" sections of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_attributes: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_attributes: false ``` ```python class Class: """Summary. Attributes: attr: Some attribute. """ attr: int = 1 ``` /// admonition | Preview type: preview //// tab | With attributes

Class

Summary.

Attributes:

**Type** | **Name** | **Description** --------- | -------- | --------------- [`int`][] | `attr` | Some attribute. //// //// tab | Without attributes

Class

Summary.

//// /// ## `show_docstring_functions` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Functions" or "Methods" sections of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_functions: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_functions: false ``` ```python """Summary. Functions: foo: Some function. """ def foo(): ... class Class: """Summary. Methods: bar: Some method. """ def bar(self): ... ``` /// admonition | Preview type: preview //// tab | With functions

module

Summary.

Functions:

**Name** | **Description** -------- | --------------- `foo` | Some function.

Class

Summary.

Methods:

**Name** | **Description** -------- | --------------- `bar` | Some method. //// //// tab | Without functions

module

Summary.

Class

Summary.

//// /// ## `show_docstring_classes` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Classes" sections of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_classes: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_classes: false ``` ```python """Summary. Classes: Class: Some class. """ class Class: """Summary.""" ``` /// admonition | Preview type: preview //// tab | With classes

module

Summary.

Classes:

**Name** | **Description** -------- | --------------- `Class` | Some class.

Class

Summary.

//// //// tab | Without classes

module

Summary.

Class

Summary.

//// /// ## `show_docstring_modules` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Modules" sections of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_modules: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_modules: false ``` ```tree module/ __init__.py submodule.py ``` ```python title="module/__init__.py" """Summary. Modules: submodule: Some module. """ ``` /// admonition | Preview type: preview //// tab | With modules

module

Summary.

Modules:

**Name** | **Description** ----------- | --------------- `submodule` | Some module. //// //// tab | Without modules

module

Summary.

//// /// ## `show_docstring_description` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the textual blocks (including admonitions) of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_description: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_description: false ``` ```python class Class: """Summary. Long description. Warning: Deprecated Stop using this class. Attributes: attr: Some attribute. """ attr: int = 1 ``` /// admonition | Preview type: preview //// tab | With description blocks

Class

Summary.

Long description.

Deprecated

Stop using this class.

Attributes:

**Type** | **Name** | **Description** --------- | -------- | --------------- [`int`][] | `attr` | Some attribute. //// //// tab | Without description blocks

Class

Attributes:

**Type** | **Name** | **Description** --------- | -------- | --------------- [`int`][] | `attr` | Some attribute. //// /// ## `show_docstring_examples` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Examples" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_examples: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_examples: false ``` ```python def print_hello(): """Print hello. Examples: >>> print("hello") hello """ print("hello") ``` /// admonition | Preview type: preview //// tab | With examples

print_hello

Print hello.

Examples:

```pycon >>> print("hello") hello ``` //// //// tab | Without examples

print_hello

Print hello.

//// /// ## `show_docstring_other_parameters` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Other Parameters" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_other_parameters: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_other_parameters: false ``` ```python def do_something(**kwargs): """Do something. Other parameters: whatever (int): Some integer. """ ``` /// admonition | Preview type: preview //// tab | With other parameters

do_something

Do something.

Other parameters:

**Type** | **Name** | **Description** --------- | ---------- | --------------- [`int`][] | `whatever` | Some integer. //// //// tab | Without other parameters

do_something

Do something.

//// /// ## `show_docstring_parameters` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Parameters" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_parameters: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_parameters: false ``` ```python def do_something(whatever: int = 0): """Do something. Parameters: whatever: Some integer. """ ``` /// admonition | Preview type: preview //// tab | With parameters

do_something

Do something.

Parameters:

**Type** | **Name** | **Description** | **Default** --------- | ---------- | --------------- | ----------- [`int`][] | `whatever` | Some integer. | `0` //// //// tab | Without parameters

do_something

Do something.

//// /// ## `show_docstring_raises` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Raises" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_raises: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_raises: false ``` ```python def raise_runtime_error(): """Raise a runtime error. Raises: RuntimeError: Not good. """ raise RuntimeError ``` /// admonition | Preview type: preview //// tab | With exceptions

raise_runtime_error

Raise a runtime error.

Raises:

**Type** | **Description** ------------------ | --------------- [`RuntimeError`][] | Not good. //// //// tab | Without exceptions

raise_runtime_error

Raise a runtime error.

//// /// ## `show_docstring_receives` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Receives" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_receives: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_receives: false ``` ```python def iter_skip( iterable: Iterable[T], initial_skip: int = 0, ) -> Generator[T, int, None]: """Iterate and skip elements. Receives: skip: Number of elements to skip. """ skip = initial_skip for element in iterable: if skip or 0 > 0: skip -= 1 else: skip = yield element ``` /// admonition | Preview type: preview //// tab | With received values

iter_skip

Iterate and skip elements.

Receives:

**Type** | **Description** --------- | --------------- [`int`][] | Number of elements to skip. //// //// tab | Without received values

iter_skip

Iterate and skip elements.

//// /// ## `show_docstring_returns` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Returns" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_returns: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_returns: false ``` ```python def rand() -> int: """Return a random number. Returns: A random number. """ return random.randint(0, 1000) ``` /// admonition | Preview type: preview //// tab | With return value

rand

Return a random number.

Returns:

**Type** | **Description** --------- | --------------- [`int`][] | A random number. //// //// tab | Without return value

rand

Return a random number.

//// /// ## `show_docstring_warns` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Warns" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_warns: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_warns: false ``` ```python def warn(): """Warn user. Warns: UserWarning: When this is inappropriate. """ warnings.warn(UserWarning("This is inappropriate")) ``` /// admonition | Preview type: preview //// tab | With warnings

warn

Warn user.

Warns:

**Type** | **Description** ----------------- | --------------- [`UserWarning`][] | When this is inappropriate. //// //// tab | Without warnings

warn

Warn user.

//// /// ## `show_docstring_yields` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Yields" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_yields: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_yields: false ``` ```python def iter_skip( iterable: Iterable[T], initial_skip: int = 0, ) -> Generator[T, int, None]: """Iterate and skip elements. Yields: Elements of the iterable. """ skip = initial_skip for element in iterable: if skip or 0 > 0: skip -= 1 else: skip = yield element ``` /// admonition | Preview type: preview //// tab | With yielded values

iter_skip

Iterate and skip elements.

Yields:

**Type** | **Description** --------- | --------------- `T` | Elements of the iterable. //// //// tab | Without yielded values

iter_skip

Iterate and skip elements.

//// /// mkdocstrings-python-handlers-1.10.5/docs/usage/configuration/general.md000066400000000000000000000144671463457115100263070ustar00rootroot00000000000000# General options ## `allow_inspection` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to allow inspecting modules (importing them) when it is not possible to visit them (parse their source code). When loading data for a given package, [Griffe] discovers every Python module, compiled or not, and inspects or visits them accordingly. If you have compiled modules but also provide stubs for them, you might want to disable the inspection of these modules, because inspection picks up many more members, and sometimes the collected data is inaccurate (depending on the tool that was used to compile the module) or too low-level/technical for API documentation. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: allow_inspection: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.object options: allow_inspection: false ``` /// admonition | Preview type: preview //// tab | With inspection

SomeClass

Docstring of the class.

__eq__

Method docstring.

__weakref__

Method docstring.

documented_method

Method docstring.

//// //// tab | Without inspection

SomeClass

Docstring of the class.

documented_method

Method docstring.

//// /// ## `show_bases` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Show the base classes of a class. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_bases: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.object options: show_bases: false ``` /// admonition | Preview type: preview //// tab | With bases

SomeClass()

Bases: SomeBaseClass

Docstring of the class.

//// //// tab | Without bases

SomeClass()

Docstring of the class.

//// /// ## `show_source` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Show the source code of this object. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_source: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.object options: show_source: false ``` /// admonition | Preview type: preview //// tab | With source

some_function()

Docstring of the function.

///// details | Source code in `package/module.py` type: quote ```python linenums="1" def some_function(): ... ``` ///// //// //// tab | Without source

some_function()

Docstring of the function.

//// /// ## `preload_modules` - **:octicons-package-24: Type list[str] | None :material-equal: `None`{ title="default value" }** Pre-load modules that are not specified directly in [autodoc instructions][autodoc syntax] (`::: identifier`). It is useful when you want to render documentation for a particular member of an object, and this member is imported from another package than its parent. For an imported member to be rendered, you need to add it to the [`__all__`][__all__] attribute of the importing module. The package from which the imported object originates must be accessible to the handler (see [Finding modules](../index.md#finding-modules)). ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: preload_modules: - their_package ``` ```md title="or in docs/some_page.md (local configuration)" ::: your_package.your_module options: preload_modules: - their_package ``` ```python title="your_package/your_module.py" from their_package.their_module import their_object __all__ = ["their_object"] # rest of your code ``` /// admonition | Preview type: preview //// tab | With preloaded modules

your_module

Docstring of your module.

their_object

Docstring of their object.

//// //// tab | Without preloaded modules

your_module

Docstring of your module.

//// /// ## `find_stubs_package` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** When looking for documentation specified in [autodoc instructions][autodoc syntax] (`::: identifier`), also look for the stubs package as defined in [PEP 561](https://peps.python.org/pep-0561/) if it exists. This is useful when most of your documentation is separately provided by such a package and not inline in your main package. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: find_stubs_package: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: your_package.your_module.your_func options: find_stubs_package: true ``` ```python title="your_package/your_module.py" def your_func(a, b): # Function code ... # rest of your code ``` ```python title="your_package-stubs/your_module.pyi" def your_func(a: int, b: str): """ """ ... # rest of your code ``` /// admonition | Preview type: preview //// tab | With find_stubs_package

your_func

Function docstring

//// //// tab | Without find_stubs_package

your_func

//// /// mkdocstrings-python-handlers-1.10.5/docs/usage/configuration/headings.md000066400000000000000000000355341463457115100264520ustar00rootroot00000000000000# Headings options ## `heading_level` - **:octicons-package-24: Type [`int`][] :material-equal: `2`{ title="default value" }** The initial heading level to use. When injecting documentation for an object, the object itself and its members are rendered. For each layer of objects, we increase the heading level by 1. The initial heading level will be used for the first layer. If you set it to 3, then headings will start with `

`. If the [heading for the root object][show_root_heading] is not shown, then the initial heading level is used for its members. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: heading_level: 2 ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: heading_level: 3 ``` /// admonition | Preview type: preview //// tab | With level 3 and root heading

module (3)

Docstring of the module.

ClassA (4)

Docstring of class A.

ClassB (4)

Docstring of class B.

method_1 (5)

Docstring of the method.

//// //// tab | With level 3, without root heading

Docstring of the module.

ClassA (3)

Docstring of class A.

ClassB (3)

Docstring of class B.

method_1 (4)

Docstring of the method.

//// /// ## `show_root_heading` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Show the heading of the object at the root of the documentation tree (i.e. the object referenced by the identifier after `:::`). It is pretty common to inject documentation for one module per page, especially when following our [automatic reference pages recipe][autopages recipe]. Since each page already has a title, usually being the module's name, we can spare one heading level by not showing the heading for the module itself (heading levels are limited to 6 by the HTML specification). Sparing that extra level can be helpful when your objects tree is deeply nested (e.g. method in a class in a class in a module). If your objects tree is not deeply nested, and you are injecting documentation for many different objects on a single page, it might be preferable to render the heading of each object. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_root_heading: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.ClassA options: show_root_heading: true ::: path.to.ClassB options: show_root_heading: true ``` /// admonition | Preview type: preview //// tab | With root heading

ClassA (2)

Docstring of class A.

method_a1 (3)

Docstring of the method.

ClassB (2)

Docstring of class B.

method_b1 (3)

Docstring of the method.

//// //// tab | Without root heading

Docstring of class A.

method_a1 (2)

Docstring of the method.

Docstring of class B.

method_b1 (2)

Docstring of the method.

//// /// ## `show_root_toc_entry` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** If the root heading is not shown, at least add a ToC entry for it. If you inject documentation for an object in the middle of a page, after long paragraphs, and without showing the [root heading][show_root_heading], then you will not be able to link to this particular object as it won't have a permalink and will be "lost" in the middle of text. In that case, it is useful to add a hidden anchor to the document, which will also appear in the table of contents. In other cases, you might want to disable the entry to avoid polluting the ToC. It is not possible to show the root heading *and* hide the ToC entry. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_root_toc_entry: true ``` ```md title="or in docs/some_page.md (local configuration)" ## Some heading Lots of text. ::: path.to.object options: show_root_toc_entry: false ## Other heading. More text. ``` /// admonition | Preview type: preview //// tab | With ToC entry **Table of contents** [Some heading](#permalink-to-some-heading){ title="#permalink-to-some-heading" } [`object`](#permalink-to-object){ title="#permalink-to-object" } [Other heading](#permalink-to-other-heading){ title="#permalink-to-other-heading" } //// //// tab | Without ToC entry **Table of contents** [Some heading](#permalink-to-some-heading){ title="#permalink-to-some-heading" } [Other heading](#permalink-to-other-heading){ title="#permalink-to-other-heading" } //// /// ## `show_root_full_path` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Show the full Python path for the root object heading. The path of a Python object is the dot-separated list of names under which it is accessible, for example `package.module.Class.method`. With this option you can choose to show the full path of the object you inject documentation for, or just its name. This option impacts only the object you specify, not its members. For members, see the two other options [`show_root_members_full_path`][] and [`show_object_full_path`][]. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_root_full_path: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module.Class.method options: show_root_full_path: false ``` /// admonition | Preview type: preview //// tab | With root full path

package.module.Class.method

Docstring of the method.

//// //// tab | Without root full path

method

Docstring of the method.

//// /// ## `show_root_members_full_path` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Show the full Python path of the root members. This option does the same thing as [`show_root_full_path`][], but for direct members of the root object instead of the root object itself. To show the full path for every member recursively, see [`show_object_full_path`][]. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_root_members_full_path: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: show_root_members_full_path: false ``` /// admonition | Preview type: preview //// tab | With members full path

Docstring of the module.

package.module.Class

Docstring of the class.

method

Docstring of the method.

//// //// tab | Without members full path

Docstring of the module.

Class

Docstring of the class.

method

Docstring of the method.

//// /// ## `show_object_full_path` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Show the full Python path of every object. Same as for [`show_root_members_full_path`][], but for every member, recursively. This option takes precedence over [`show_root_members_full_path`][]: `show_root_members_full_path` | `show_object_full_path` | Direct root members path ----------------------------- | ----------------------- | ------------------------ False | False | Name only False | True | Full True | False | Full True | True | Full ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_object_full_path: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: show_object_full_path: false ``` /// admonition | Preview type: preview //// tab | With objects full path

Docstring of the module.

package.module.Class

Docstring of the class.

package.module.Class.method

Docstring of the method.

//// //// tab | Without objects full path

Docstring of the module.

Class

Docstring of the class.

method

Docstring of the method.

//// /// ## `show_category_heading` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** When [grouped by categories][group_by_category], show a heading for each category. These category headings will appear in the table of contents, allowing you to link to them using their permalinks. WARNING: **Not recommended with deeply nested object** When injecting documentation for deeply nested objects, you'll quickly run out of heading levels, and the objects at the bottom of the tree risk all getting documented using H6 headings, which might decrease the readability of your API docs. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: group_by_category: true show_category_heading: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: group_by_category: true show_category_heading: false ``` /// admonition | Preview type: preview //// tab | With category headings

Docstring of the module.

Attributes (2)

module_attribute (3)

Docstring of the module attribute.

Classes (2)

Class (3)

Docstring of the class.

Attributes (4)

class_attribute (5)

Docstring of the class attribute.

Methods (4)

method (5)

Docstring of the method.

//// //// tab | Without category headings

Docstring of the module.

module_attribute (2)

Docstring of the module attribute.

Class (2)

Docstring of the class.

class_attribute (3)

Docstring of the class attribute.

method (3)

Docstring of the method.

//// /// ## `show_symbol_type_heading` [:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0) - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Show the symbol type in headings. This option will prefix headings with , , , or types. See also [`show_symbol_type_toc`][show_symbol_type_toc]. To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types). ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_symbol_type_heading: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: show_symbol_type_heading: false ``` /// admonition | Preview type: preview //// tab | With symbol type in headings

module

Docstring of the module.

attribute

Docstring of the module attribute.

function

Docstring of the function.

Class

Docstring of the class.

method

Docstring of the method.

//// //// tab | Without symbol type in headings

module

Docstring of the module.

attribute

Docstring of the module attribute.

function

Docstring of the function.

Class

Docstring of the class.

method

Docstring of the method.

//// /// ## `show_symbol_type_toc` [:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0) - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Show the symbol type in the Table of Contents. This option will prefix items in the ToC with , , , or types. See also [`show_symbol_type_heading`][show_symbol_type_heading]. To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types). ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_symbol_type_toc: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: show_symbol_type_toc: false ``` /// admonition | Preview type: preview //// tab | With symbol type in ToC
  • module
  • attribute
  • function
  • Class
    • method
//// //// tab | Without symbol type in ToC
  • module
  • attribute
  • function
  • Class
    • method
//// /// mkdocstrings-python-handlers-1.10.5/docs/usage/configuration/members.md000066400000000000000000000431661463457115100263220ustar00rootroot00000000000000# Members options ## `members` - **:octicons-package-24: Type list[str] | bool | None :material-equal: `None`{ title="default value" }** An explicit list of members to render. Only members declared in this list will be rendered. A member without a docstring will still be rendered, even if [`show_if_no_docstring`][] is set to false. The members will be rendered in the specified order, regardless of the value of [`members_order`][]. **Note that members will still be grouped by category, according to the [`group_by_category`][] option.** Passing a falsy value (`no`, `false` in YAML) or an empty list (`[]`) will tell the Python handler not to render any member. Passing a truthy value (`yes`, `true` in YAML) will tell the Python handler to render every member. Any given value, except for an explicit `None` (`null` in YAML) will tell the handler to ignore [`filters`][] for the object's members. Filters will still be applied to the next layers of members (grand-children). ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: members: - hello # (1) ``` 1. :warning: Most of the time it won't make sense to use this option at the global level. ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: members: - ThisClass - this_function ``` ```python title="package/module.py" """Module docstring.""" def this_function(): """Function docstring.""" class ThisClass: """Class docstring.""" def method(self): """Method docstring.""" this_attribute = 0 """Attribute docstring.""" ``` /// admonition | Preview type: preview //// tab | With `members: true`

Module docstring.

this_function

Function docstring.

ThisClass

Class docstring.

method

Method docstring.

this_attribute

Attribute docstring.

//// //// tab | With `members: false` or `members: []`

Module docstring.

//// //// tab | With `members: [ThisClass]`

Module docstring.

ThisClass

Class docstring.

method

Method docstring.

//// /// INFO: **The default behavior (with unspecified `members` or `members: null`) is to use [`filters`][].** ## `inherited_members` - **:octicons-package-24: Type list[str] | bool :material-equal: `False`{ title="default value" }** An explicit list of inherited members (for classes) to render. Inherited members are always fetched from classes that are in the same package as the currently rendered class. To fetch members inherited from base classes, themselves coming from external packages, use the [`preload_modules`][preload_modules] option. For example, if your class inherits from Pydantic's `BaseModel`, and you want to render `BaseModel`'s methods in your class, use `preload_modules: [pydantic]`. The `pydantic` package must be available in the current environment. Passing a falsy value (`no`, `false` in YAML) or an empty list (`[]`) will tell the Python handler not to render any inherited member. Passing a truthy value (`yes`, `true` in YAML) will tell the Python handler to render every inherited member. When all inherited members are selected with `inherited_members: true`, it is possible to specify both members and inherited members in the `members` list: ```yaml inherited_members: true members: - inherited_member_a - inherited_member_b - member_x - member_y ``` The alternative is not supported: ```yaml inherited_members: - inherited_member_a - inherited_member_b members: - member_x - member_y ``` ...because it would make members ordering ambiguous/unspecified. You can render inherited members *only* by setting `inherited_members: true` (or a list of inherited members) and setting `members: false`: ```yaml inherited_members: true members: false ``` ```yaml inherited_members: - inherited_member_a - inherited_member_b members: false ``` You can render *all declared members* and all or specific inherited members by leaving `members` as null (default): ```yaml inherited_members: - inherited_member_a - inherited_member_b # members: null # (1) ``` 1. In this case, only declared members will be subject to further filtering with [`filters`][filters] and [`docstrings`][show_if_no_docstring]. ```yaml inherited_members: true # (1) # members: null ``` 1. In this case, both declared and inherited members will be subject to further filtering with [`filters`][filters] and [`docstrings`][show_if_no_docstring]. You can render *all declared members* and all or specific inherited members, avoiding further filtering with [`filters`][filters] and [`docstrings`][show_if_no_docstring] by setting `members: true`: ```yaml inherited_members: true members: true ``` ```yaml inherited_members: - inherited_member_a - inherited_member_b members: true ``` The general rule is that declared or inherited members specified in lists are never filtered out. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: inherited_members: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: inherited_members: true ``` ```python title="package/module.py" """Module docstring.""" class Base: """Base class.""" def base(self): """Base method.""" class Main(Base): """Main class.""" def main(self): """Main method.""" ``` /// admonition | Preview type: preview //// tab | With inherited members

Module docstring.

Base

Base class.

base

Base method.

Main

Main class.

base

Base method.

main

Main method.

//// //// tab | Without inherited members

Module docstring.

Base

Base class.

base

Base method.

Main

Main class.

main

Main method.

//// /// ## `members_order` - **:octicons-package-24: Type [`str`][] :material-equal: `"alphabetical"`{ title="default value" }** The members ordering to use. Possible values: - `alphabetical`: order by the members names. - `source`: order members as they appear in the source file. The order applies for all members, recursively. The order will be ignored for members that are explicitely sorted using the [`members`][] option. **Note that members will still be grouped by category, according to the [`group_by_category`][] option.** ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: members_order: alphabetical ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: members_order: source ``` ```python title="package/module.py" """Module docstring.""" def function_b(): """Function a.""" def function_a(): """Function b.""" def function_c(): """Function c.""" ``` /// admonition | Preview type: preview //// tab | With alphabetical order

Module docstring.

function_a

Function a.

function_b

Function b.

function_c

Function c.

//// //// tab | With source order

Module docstring.

function_b

Function b.

function_a

Function a.

function_c

Function c.

//// /// ## `filters` - **:octicons-package-24: Type list[str] | None :material-equal: `["!^_[^_]"]`{ title="default value" }** A list of filters applied to filter objects based on their name. Filters are regular expressions. These regular expressions are evaluated by Python and so must match the syntax supported by the [`re`][] module. A filter starting with `!` (negative filter) will exclude matching objects instead of including them. The default value (`["!^_[^_]"]`) means: *render every object, except those starting with one underscore, unless they start with two underscores*. It means that an object whose name is `hello`, `__hello`, or `__hello__` will be rendered, but not one whose name is `_hello`. Each filter takes precedence over the previous one. This allows for fine-grain selection of objects by adding more specific filters. For example, you can start by unselecting objects that start with `_`, and add a second filter that re-select objects that start with `__`. The default filters can therefore be rewritten like this: ```yaml filters: - "!^_" - "^__" ``` If there are no negative filters, the handler considers that everything is **unselected** first, and then selects things based on your positive filters. If there is at least one negative filter, the handler considers that everything is **selected** first, and then re-selects/unselects things based on your other filters. In short, `filters: ["a"]` means *"keep ***nothing*** except names containing `a`"*, while `filters: ["!a"]` means *"keep ***everything*** except names containing `a`"*. An empty list of filters tells the Python handler to render every object. The [`members`][] option takes precedence over filters (filters will still be applied recursively to lower members in the hierarchy). ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: filters: - "!^_" ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: filters: [] ``` ```python title="package/module.py" def hello(): ... def _world(): ... ``` /// admonition | Preview type: preview //// tab | With `filters: []`

Module docstring.

hello

Function docstring.

_world

Function docstring.

//// //// tab | With `filters: ["hello"]`

Module docstring.

hello

Function docstring.

//// //// tab | With `filters: ["!hello"]`

Module docstring.

_world

Function docstring.

//// /// /// admonition | Common filters type: tip Here are some common filters that you might to want to use. - `["!^_"]`: exclude all private/protected/special objects - `["!^_", "^__init__$"]`: same as above, but keep `__init__` methods - `["!^_[^_]"]`: exclude all private/protected objects, keep special ones (default filters) /// ## `group_by_category` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Group the object members by categories: attributes, classes, functions, and modules. Members within a same category will be ordered according to the [`members_order`][] option. You can use the [`show_category_heading`][] option to also render a heading for each category. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: group_by_category: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: group_by_category: false ``` ```python title="package/module.py" def function_a(): ... class ClassB: ... attribute_C = 0 def function_d(): ... ``` /// admonition | Preview type: preview //// tab | With category grouping

Module docstring.

attribute_c

Attribute docstring.

ClassB

Class docstring.

function_a

Function docstring.

function_d

Function docstring.

//// //// tab | Without category grouping

Module docstring.

function_a

Function docstring.

ClassB

Class docstring.

attribute_c

Attribute docstring.

function_d

Function docstring.

//// /// ## `show_submodules` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** When rendering a module, show its submodules recursively. This is false by default, because most of the time we render only one module per page, and when rendering a package (a tree of modules and their members) on a single page, we quickly run out of [heading levels][heading_level]. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_submodules: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.subpackage options: show_submodules: false ``` ```tree title="package" package __init__.py subpackage __init__.py submodule.py ``` /// admonition | Preview type: preview //// tab | With submodules

Subpackage docstring.

subpackage_member

Member docstring.

submodule

Submodule docstring.

submodule_member

Member docstring.

//// //// tab | Without submodules

Subpackage docstring.

subpackage_member

Member docstring.

//// /// ## `summary` [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.2.0](../../insiders/changelog.md#1.2.0) - **:octicons-package-24: Type bool | dict[str, bool] :material-equal: `False`{ title="default value" }** Whether to render summaries of modules, classes, functions (methods) and attributes. This option accepts a boolean (`yes`, `true`, `no`, `false` in YAML) or a dictionary with one or more of the following keys: `attributes`, `functions`, `classes`, `modules`, with booleans as values. Class methods summary is (de)activated with the `functions` key. By default, `summary` is false, and by extension all values are false. Examples: ```yaml summary: true ``` ```yaml summary: false ``` ```yaml summary: attributes: false functions: true modules: false ``` Summaries will be rendered as the corresponding docstring sections. For example, the summary for attributes will be rendered as an Attributes docstring section. The section will be rendered in accordance with the [`docstring_section_style`][] option. If the objects appearing in the summary are also rendered on the page (or somewhere else on the site), their name will automatically link to their rendered documentation. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: summary: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: summary: false ``` /// admonition | Preview type: preview //// tab | With all summaries ``` ::: path.to.module.MyClass options: summary: true ```

MyClass

Class docstring.

Methods:

  • my_method1: Summary of the method (first docstring line).
  • my_method2: Summary of the method (first docstring line).

Attributes:

  • attr1: Summary of the attribute (first docstring line).
  • attr2: Summary of the attribute (first docstring line).
//// //// tab | With methods summary only ``` ::: path.to.module.MyClass options: summary: functions: true ```

MyClass

Class docstring.

Methods:

  • my_method1: Summary of the method (first docstring line).
  • my_method2: Summary of the method (first docstring line).
//// /// ## `show_labels` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to show labels of the members. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_labels: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: show_labels: false ``` ```python title="package/module.py" class SomeClass: some_attr: int ``` /// admonition | Preview type: preview //// tab | With labels some_attr: int instance-attribute //// //// tab | Without labels some_attr: int //// /// mkdocstrings-python-handlers-1.10.5/docs/usage/configuration/signatures.md000066400000000000000000000267671463457115100270640ustar00rootroot00000000000000# Signatures options ## `annotations_path` - **:octicons-package-24: Type [`str`][] :material-equal: `"brief"`{ title="default value" }** The verbosity for annotations path. Possible values: - `brief` (recommended): render only the last component of each type path, not their full paths. For example, it will render `Sequence[Path]` and not `typing.Sequence[pathlib.Path]`. Brief annotations will cross-reference the right object anyway, and show the full path in a tooltip when hovering them. - `source`: render annotations as written in the source. For example if you imported `typing` as `t`, it will render `typing.Sequence` as `t.Sequence`. Each part will cross-reference the relevant object: `t` will link to the `typing` module and `Sequence` will link to the `Sequence` type. - `full`: render annotations with their full path (the opposite of brief). For example if you import `Sequence` and `Pattern` from `typing` and annoate something using `Sequence[Pattern]`, it will render as `typing.Sequence[typing.Pattern]`, with each part cross-referencing the corresponding object. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: annotations_path: brief ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: annotations_path: source ``` /// admonition | Preview type: preview //// tab | Brief annotations ```python import markdown import markupsafe def convert(text: str, md: markdown.Markdown) -> markupsafe.Markup: """Convert text to Markdown. Parameters: text: The text to convert. md: A Markdown instance. Returns: Converted markup. """ return markupsafe.Markup(md.convert(text)) ```

convert(text, md)

Convert text to Markdown.

Parameters:

**Type** | **Description** | **Default** ---------- | ------------------------ | ----------- [`str`][] | The text to convert. | *required* [`Markdown`](#ref-to-markdown){ .external title="markdown.Markdown" } | A Markdown instance. | *required*

Returns:

**Type** | **Name** | **Description** ---------- | ----------- | --------------- [`Markup`](#ref-to-markup){ .external title="markupsafe.Markup" } | `text` | Converted markup. //// //// tab | Source annotations ```python import markdown from markupsafe import Markup def convert(text: str, md: markdown.Markdown) -> Markup: """Convert text to Markdown. Parameters: text: The text to convert. md: A Markdown instance. Returns: Converted markup. """ return Markup(md.convert(text)) ```

convert(text, md)

Convert text to Markdown.

Parameters:

**Type** | **Description** | **Default** ---------- | ------------------------ | ----------- [`str`][] | The text to convert. | *required* markdown.Markdown | A Markdown instance. | *required*

Returns:

**Type** | **Name** | **Description** ---------- | ----------- | --------------- [`Markup`](#ref-to-markup){ .external title="markupsafe.Markup" } | `text` | Converted markup. //// //// tab | Full annotations ```python from markdown import Markdown from markupsafe import Markup def convert(text: str, md: Markdown) -> Markup: """Convert text to Markdown. Parameters: text: The text to convert. md: A Markdown instance. Returns: Converted markup. """ return Markup(md.convert(text)) ```

convert(text, md)

Convert text to Markdown.

Parameters:

**Type** | **Description** | **Default** ---------- | ------------------------ | ----------- [`str`][] | The text to convert. | *required* markdown.Markdown | A Markdown instance. | *required*

Returns:

**Type** | **Name** | **Description** ---------- | ----------- | --------------- markupsafe.Markup | `text` | Converted markup. //// /// ## `line_length` - **:octicons-package-24: Type [`int`][] :material-equal: `60`{ title="default value" }** Maximum line length when formatting code/signatures. When separating signatures from headings with the [`separate_signature`][] option, the Python handler will try to format the signatures using [Black] and the specified line length. If Black is not installed, the handler issues an INFO log once. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: separate_signature: true line_length: 60 ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: separate_signature: true line_length: 80 ``` /// admonition | Preview type: preview //// tab | Line length 60

long_function_name

long_function_name(
    long_parameter_1="hello",
    long_parameter_2="world",
)
//// //// tab | Line length 80

long_function_name

long_function_name(long_parameter_1="hello", long_parameter_2="world")
//// /// ## `show_signature` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Show methods and functions signatures. Without it, just the function/method name is rendered. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_signature: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_signature: false ``` /// admonition | Preview type: preview //// tab | With signature

function(param1, param2=None)

Function docstring.

//// //// tab | Without signature

function

Function docstring.

//// /// ## `show_signature_annotations` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Show the type annotations in methods and functions signatures. Since the heading can become quite long when annotations are rendered, it is usually best to [separate the signature][separate_signature] from the heading. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: separate_signature: true show_signature_annotations: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: separate_signature: true show_signature_annotations: false ``` /// admonition | Preview type: preview //// tab | With signature annotations

function

```python function( param1: list[int | float], param2: bool | None = None, ) -> float ```

Function docstring.

//// //// tab | Without signature annotations

function

```python function(param1, param2=None) ```

Function docstring.

//// /// ## `separate_signature` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Whether to put the whole signature in a code block below the heading. When separating signatures from headings, the Python handler will try to format the signatures using [Black] and the specified [line length][line_length]. If Black is not installed, the handler issues an INFO log once. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: separate_signature: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: separate_signature: true ``` /// admonition | Preview type: preview //// tab | With separate signature

function

```python function(param1, param2=None) ```

Function docstring.

//// //// tab | Without separate signature

function(param1, param2=None)

Function docstring.

//// /// ## `signature_crossrefs` [:octicons-tag-24: Insiders 1.0.0](../../insiders/changelog.md#1.0.0) Whether to render cross-references for type annotations in signatures. When signatures are separated from headings with the [`separate_signature`][] option and type annotations are shown with the [`show_signature_annotations`][] option, this option will render a cross-reference (link) for each type annotation in the signature. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: separate_signature: true show_signature_annotations: true signature_crossrefs: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: separate_signature: true show_signature_annotations: true signature_crossrefs: true ``` /// admonition | Preview type: preview //// tab | With signature cross-references

do_format_code

do_format_code(code: str, line_length: int) -> str

Function docstring.

//// //// tab | Without signature cross-references

do_format_code

do_format_code(code: str, line_length: int) -> str

Function docstring.

//// /// ## `unwrap_annotated` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Whether to unwrap [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated){ .external } types to show only the type without the annotations. For example, unwrapping `Annotated[int, Gt(10)]` will render `int`. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: unwrap_annotated: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: unwrap_annotated: true ``` mkdocstrings-python-handlers-1.10.5/docs/usage/customization.md000066400000000000000000000316041463457115100247230ustar00rootroot00000000000000# Customization It is possible to customize the output of the generated documentation with CSS and/or by overriding templates. ## CSS classes Our templates add [CSS](https://www.w3schools.com/Css/) classes to many HTML elements to make it possible for users to customize the resulting look and feel. To add CSS rules and style mkdocstrings' output, put them in a CSS file in your docs folder, for example in `docs/css/mkdocstrings.css`, and reference this file in [MkDocs' `extra_css` configuration option](https://www.mkdocs.org/user-guide/configuration/#extra_css): ```yaml title="mkdocs.yml" extra_css: - css/mkdocstrings.css ``` Example: ```css title="docs/css/mkdocstrings.css" .doc-section-title { font-weight: bold; } ``` The following CSS classes are used in the generated HTML: - `doc`: on all the following elements - `doc-children`: on `div`s containing the children of an object - `doc-object`: on `div`s containing an object - `doc-attribute`: on `div`s containing an attribute - `doc-class`: on `div`s containing a class - `doc-function`: on `div`s containing a function - `doc-module`: on `div`s containing a module - `doc-heading`: on objects headings - `doc-object-name`: on `span`s wrapping objects names/paths in the heading - `doc-KIND-name`: as above, specific to the kind of object (module, class, function, attribute) - `doc-contents`: on `div`s wrapping the docstring then the children (if any) - `first`: same, but only on the root object's contents `div` - `doc-labels`: on `span`s wrapping the object's labels - `doc-label`: on `small` elements containing a label - `doc-label-LABEL`: same, where `LABEL` is replaced by the actual label - `doc-section-title`: on section titles (depend on the [selected style for section rendering][docstring_style]) - `doc-section-item`: on section items (depend on the [selected style for section rendering][docstring_style]) - `doc-md-description`: on `div`s containing HTML descriptions converted from Markdown docstrings - `doc-symbol`: on `code` tags of symbol types - `doc-symbol-heading`: on symbol types in headings - `doc-symbol-toc`: on symbol types in the ToC - `doc-symbol-KIND`: specific to the kind of object (`module`, `class`, `function`, `method`, `attribute`) /// admonition | Example with colorful labels type: example //// tab | CSS ```css .doc-label { border-radius: 15px; padding: 2px 8px; font-weight: bold; } .doc-label-special { background-color: #3330E4; color: white; } .doc-label-private { background-color: #F637EC; color: white; } .doc-label-property { background-color: #FBB454; color: black; } .doc-label-read-only { background-color: #FAEA48; color: black; } ``` //// //// tab | Result

special private property read-only

//// /// ## Symbol types ### Colors You can customize the colors of the symbol types (see [`show_symbol_type_heading`][show_symbol_type_heading] and [`show_symbol_type_toc`][show_symbol_type_toc]) by overriding the values of our CSS variables, for example: ```css title="docs/css/mkdocstrings.css" [data-md-color-scheme="default"] { --doc-symbol-attribute-fg-color: #0079ff; --doc-symbol-function-fg-color: #00dfa2; --doc-symbol-method-fg-color: #00dfa2; --doc-symbol-class-fg-color: #d1b619; --doc-symbol-module-fg-color: #ff0060; --doc-symbol-attribute-bg-color: #0079ff1a; --doc-symbol-function-bg-color: #00dfa21a; --doc-symbol-method-bg-color: #00dfa21a; --doc-symbol-class-bg-color: #d1b6191a; --doc-symbol-module-bg-color: #ff00601a; } [data-md-color-scheme="slate"] { --doc-symbol-attribute-fg-color: #963fb8; --doc-symbol-function-fg-color: #6d67e4; --doc-symbol-method-fg-color: #6d67e4; --doc-symbol-class-fg-color: #46c2cb; --doc-symbol-module-fg-color: #f2f7a1; --doc-symbol-attribute-bg-color: #963fb81a; --doc-symbol-function-bg-color: #6d67e41a; --doc-symbol-method-bg-color: #6d67e41a; --doc-symbol-class-bg-color: #46c2cb1a; --doc-symbol-module-bg-color: #f2f7a11a; } ``` The `[data-md-color-scheme="*"]` selectors work with the [Material for MkDocs] theme. If you are using another theme, adapt the selectors to this theme if it supports light and dark themes, otherwise just override the variables at root level: ```css title="docs/css/mkdocstrings.css" :root { --doc-symbol-attribute-fg-color: #0079ff; --doc-symbol-function-fg-color: #00dfa2; --doc-symbol-method-fg-color: #00dfa2; --doc-symbol-class-fg-color: #d1b619; --doc-symbol-module-fg-color: #ff0060; --doc-symbol-attribute-bg-color: #0079ff1a; --doc-symbol-function-bg-color: #00dfa21a; --doc-symbol-method-bg-color: #00dfa21a; --doc-symbol-class-bg-color: #d1b6191a; --doc-symbol-module-bg-color: #ff00601a; } ``` /// admonition | Preview type: preview

Try cycling through the themes to see the colors for each theme:

/// ### Names You can also change the actual symbol names. For example, to use single letters instead of truncated types: ```css title="docs/css/mkdocstrings.css" .doc-symbol-attribute::after { content: "A"; } .doc-symbol-function::after { content: "F"; } .doc-symbol-method::after { content: "M"; } .doc-symbol-class::after { content: "C"; } .doc-symbol-module::after { content: "M"; } ``` /// admonition | Preview type: preview
  • Attribute:
  • Function:
  • Method:
  • Class:
  • Module:
/// ## Templates Templates are organized into the following tree: ```python exec="1" result="tree" from pathlib import Path basedir = "src/mkdocstrings_handlers/python/templates/material" print("theme/") for filepath in sorted(path for path in Path(basedir).rglob("*") if "_base" not in str(path) and path.suffix != ".css"): print( " " * (len(filepath.relative_to(basedir).parent.parts) + 1) + filepath.name + ("/" if filepath.is_dir() else "") ) ``` See them [in the repository](https://github.com/mkdocstrings/python/tree/master/src/mkdocstrings_handlers/python/templates/). See the general *mkdocstrings* documentation to learn how to override them: https://mkdocstrings.github.io/theming/#templates. Each one of these templates extends a base version in `theme/_base`. Example: ```html+jinja title="theme/class.html" {% extends "_base/class.html" %} ``` Some of these templates define [Jinja blocks](https://jinja.palletsprojects.com/en/3.0.x/templates/#template-inheritance). allowing to customize only *parts* of a template without having to fully copy-paste it into your project: ```jinja title="templates/theme/class.html" {% extends "_base/class.html" %} {% block contents %} {{ block.super }} Additional contents {% endblock contents %} ``` ### Available blocks Only the templates for the **Material for MkDocs** provide Jinja blocks. The following tables show the block names, description, and the Jinja context available in their scope. #### `module.html` - `heading`: The module heading. - `labels`: The module labels. - `contents`: The module contents: docstring and children blocks. - `docstring`: The module docstring. - `summary`: The automatic summaries of members. - `children`: The module children. Available context: - `config`: The handler configuration (dictionary). - `module`: The [Module][griffe.dataclasses.Module] instance. #### `class.html` - `heading`: The class heading. - `labels`: The class labels. - `signature`: The class signature. - `contents`: The class contents: bases, docstring, source and children blocks. - `bases`: The class bases. - `docstring`: The class docstring. - `summary`: The automatic summaries of members. - `source`: The class source code. - `children`: The class children. Available context: - `config`: The handler configuration (dictionary). - `class`: The [Class][griffe.dataclasses.Class] instance. #### `function.html` - `heading`: The function heading. - `labels`: The function labels. - `signature`: The function signature. - `contents`: The function contents: docstring and source blocks. - `docstring`: The function docstring. - `source`: The function source code. Available context: - `config`: The handler configuration (dictionary). - `function`: The [Function][griffe.dataclasses.Function] instance. #### `attribute.html` - `heading`: The attribute heading. - `labels`: The attribute labels. - `signature`: The attribute signature. - `contents`: The attribute contents: docstring block. - `docstring`: The attribute docstring. Available context: - `config`: The handler configuration (dictionary). - `attribute`: The [Attribute][griffe.dataclasses.Attribute] instance. #### Docstring sections In `docstring/attributes.html`, `docstring/functions.html`, `docstring/classes.html`, `docstring/modules.html`, `docstring/other_parameters.html`, `docstring/parameters.html`, `docstring/raises.html`, `docstring/receives.html`, `docstring/returns.html`, `docstring/warns.html`, and `docstring/yields.html`: - `table_style`: The section as a table. - `list_style`: The section as a list. - `spacy_style`: The section as a Spacy table. Available context: - `section`: The [DocstringSection][griffe.docstrings.dataclasses.DocstringSection] instance (see `DocstringSection*` subclasses). ### Syntax highlight in signatures You can customize the colors in syntax highlighted signatures. If you are using the [Material for MkDocs] theme, here are some customization examples: ```css /* Fancier color for operators such as * and |. */ .doc-signature .o { color: var(--md-code-hl-special-color); } /* Fancier color for constants such as None, True, and False. */ .doc-signature .kc { color: var(--md-code-hl-constant-color); } /* Fancier color for built-in types (only useful when cross-references are used). */ .doc-signature .n > a[href^="https://docs.python.org/"][href*="/functions.html#"], .doc-signature .n > a[href^="https://docs.python.org/"][href*="/stdtypes.html#"] { color: var(--md-code-hl-constant-color); } ``` For other themes, use their own CSS variables, or use plain colors such as `violet` or `#2987f2`. ## Style recommendations [](){#recommended-style-material} ### Material Here are some CSS rules for the [Material for MkDocs] theme: ```css --8<-- "docs/css/mkdocstrings.css" ``` [](){#recommended-style-readthedocs} ### ReadTheDocs Here are some CSS rules for the built-in ReadTheDocs theme: ```css /* Indentation. */ div.doc-contents:not(.first) { padding-left: 25px; border-left: .05rem solid rgba(200, 200, 200, 0.2); } ```mkdocstrings-python-handlers-1.10.5/docs/usage/docstrings/000077500000000000000000000000001463457115100236445ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/docs/usage/docstrings/google.md000066400000000000000000000015061463457115100254440ustar00rootroot00000000000000# Google style ## :warning: Work in Progress! ### Google-style admonitions With Google-style docstrings, any section that is not recognized will be transformed into its admonition equivalent. For example: === "Docstring" ```python """ Note: It looks like a section, but it will be rendered as an admonition. Tip: You can even choose a title. This admonition has a custom title! """ ``` === "Result" NOTE: It looks like a section, but it will be rendered as an admonition. TIP: **You can even choose a title.** This admonition has a custom title! See [Napoleon's documentation](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). See the supported docstring sections on [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/). mkdocstrings-python-handlers-1.10.5/docs/usage/docstrings/numpy.md000066400000000000000000000010011463457115100253260ustar00rootroot00000000000000# Numpydoc style ## :warning: Work in Progress! NOTE: As Numpy-style is partially supported by the underlying parser, you may experience problems in the building process if your docstring has a `Methods` section in the class docstring (see [#366](https://github.com/mkdocstrings/mkdocstrings/issues/366)). See [Numpydoc's documentation](https://numpydoc.readthedocs.io/en/latest/format.html). See the supported docstring sections on [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/). mkdocstrings-python-handlers-1.10.5/docs/usage/docstrings/sphinx.md000066400000000000000000000004111463457115100254730ustar00rootroot00000000000000# Sphinx style ## :warning: Work in Progress! See [Sphinx's documentation](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html). See the supported docstring sections on [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/). mkdocstrings-python-handlers-1.10.5/docs/usage/extensions.md000066400000000000000000000012101463457115100242000ustar00rootroot00000000000000# Extensions ## :warning: Work in Progress! The Python handler supports extensions through [*mkdocstrings*' handler extensions](https://mkdocstrings.github.io/usage/handlers/#handler-extensions). Specifically, additional templates can be added to the handler, and Griffe extensions can instruct the handler to use a particular template for a particular object by setting a value in the Griffe object's `extra` dictionary: ```python title="griffe_extension.py" obj = ... # get a reference to a Griffe object if "mkdocstrings" not in obj.extra: obj.extra["mkdocstrings"] = {} obj.extra["mkdocstrings"]["template"] = "template_name.html" ``` mkdocstrings-python-handlers-1.10.5/docs/usage/index.md000066400000000000000000000236421463457115100231250ustar00rootroot00000000000000# Usage TIP: **This is the documentation for the NEW Python handler.** To read the documentation for the LEGACY handler, go to the [legacy handler documentation](https://mkdocstrings.github.io/python-legacy). ## Installation You can install this handler as a *mkdocstrings* extra: ```toml title="pyproject.toml" # PEP 621 dependencies declaration # adapt to your dependencies manager [project] dependencies = [ "mkdocstrings[python]>=0.18", ] ``` You can also explicitly depend on the handler: ```toml title="pyproject.toml" # PEP 621 dependencies declaration # adapt to your dependencies manager [project] dependencies = [ "mkdocstrings-python", ] ``` The Python handler is the default *mkdocstrings* handler. You can change the default handler, or explicitely set the Python handler as default by defining the `default_handler` configuration option of `mkdocstrings` in `mkdocs.yml`: ```yaml title="mkdocs.yml" plugins: - mkdocstrings: default_handler: python ``` ## Injecting documentation With the Python handler installed and configured as default handler, you can inject documentation for a module, class, function, or any other Python object with *mkdocstrings*' [autodoc syntax], in your Markdown pages: ```md ::: path.to.object ``` If another handler was defined as default handler, you can explicitely ask for the Python handler to be used when injecting documentation with the `handler` option: ```md ::: path.to.object handler: python ``` ## Configuration When installed, the Python handler becomes the default *mkdocstrings* handler. You can configure it in `mkdocs.yml`: ```yaml title="mkdocs.yml" plugins: - mkdocstrings: handlers: python: ... # the Python handler configuration ``` ### Global-only options Some options are **global only**, and go directly under the handler's name. #### `import` This option is used to import Sphinx-compatible objects inventories from other documentation sites. For example, you can import the standard library objects inventory like this: ```yaml title="mkdocs.yml" plugins: - mkdocstrings: handlers: python: import: - https://docs.python-requests.org/en/master/objects.inv ``` When importing an inventory, you enable automatic cross-references to other documentation sites like the standard library docs or any third-party package docs. Typically, you want to import the inventories of your project's dependencies, at least those that are used in the public API. See [*mkdocstrings*' documentation on inventories][inventories] for more details. [inventories]: https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories Additionally, the Python handler accepts a `domains` option in the import items, which allows to select the inventory domains to select. By default the Python handler only selects the `py` domain (for Python objects). You might find useful to also enable the [`std` domain][std domain]: [std domain]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-standard-domain ```yaml title="mkdocs.yml" plugins: - mkdocstrings: handlers: python: import: - url: https://docs.python-requests.org/en/master/objects.inv domains: [std, py] ``` NOTE: The `import` option is common to *all* handlers, however they might implement it differently, or not even implement it. #### `paths` This option is used to provide filesystem paths in which to search for Python modules. Non-absolute paths are computed as relative to MkDocs configuration file. Example: ```yaml title="mkdocs.yml" plugins: - mkdocstrings: handlers: python: paths: [src] # search packages in the src folder ``` More details at [Finding modules](#finding-modules). #### `load_external_modules` This option allows resolving aliases (imports) to any external module. Modules are considered external when they are not part of the package your are injecting documentation for. Setting this option to `True` will tell the handler to resolve aliases recursively when they are made public through the [`__all__`][__all__] variable. By default, the handler will only resolve aliases when they point at a private sibling of the source package, for example aliases going from `ast` to `_ast`. Set `load_external_modules` to `False` to prevent even that. WARNING: **Use with caution** This can load a *lot* of modules through [Griffe], slowing down your build or triggering errors that Griffe does not yet handle. **We recommend using the [`preload_modules`][] option instead**, which acts as an include-list rather than as include-all. Example: ```yaml title="mkdocs.yml" plugins: - mkdocstrings: handlers: python: load_external_modules: true ``` [__all__]: https://docs.python.org/3/tutorial/modules.html#importing-from-a-package ### Global/local options The other options can be used both globally *and* locally, under the `options` key. For example, globally: ```yaml title="mkdocs.yml" plugins: - mkdocstrings: handlers: python: options: do_something: true ``` ...and locally, overriding the global configuration: ```md title="docs/some_page.md" ::: package.module.class options: do_something: false ``` These options affect how the documentation is collected from sources and rendered. See the following tables summarizing the options, and get more details for each option in the following pages: - [General options](configuration/general.md): various options that do not fit in the other categories - [Headings options](configuration/headings.md): options related to headings and the table of contents (or sidebar, depending on the theme used) - [Members options](configuration/members.md): options related to filtering or ordering members in the generated documentation - [Docstrings options](configuration/docstrings.md): options related to docstrings (parsing and rendering) - [Signature options](configuration/signatures.md): options related to signatures and type annotations #### Options summary ::: mkdocstrings_handlers.python.handler.PythonHandler.default_config options: show_root_heading: false show_root_toc_entry: false ## Finding modules There are multiple ways to tell the handler where to find your packages/modules. **The recommended method is to use the `paths` option, as it's the only one that works with the `-f` option of MkDocs, allowing to build the documentation from any location on the file system.** Indeed, the paths provided with the `paths` option are computed as relative to the configuration file (mkdocs.yml), so that the current working directory has no impact on the build process: *you can build the docs from any location on your filesystem*. ### Using the `paths` option TIP: **This is the recommended method.** 1. mkdocs.yml in root, package in root ```tree root/ mkdocs.yml package/ ``` ```yaml title="mkdocs.yml" plugins: - mkdocstrings: handlers: python: paths: [.] # actually not needed, default ``` 1. mkdocs.yml in root, package in subfolder ```tree root/ mkdocs.yml src/ package/ ``` ```yaml title="mkdocs.yml" plugins: - mkdocstrings: handlers: python: paths: [src] ``` 1. mkdocs.yml in subfolder, package in root ```tree root/ docs/ mkdocs.yml package/ ``` ```yaml title="mkdocs.yml" plugins: - mkdocstrings: handlers: python: paths: [..] ``` 1. mkdocs.yml in subfolder, package in subfolder ```tree root/ docs/ mkdocs.yml src/ package/ ``` ```yaml title="mkdocs.yml" plugins: - mkdocstrings: handlers: python: paths: [../src] ``` Except for case 1, which is supported by default, **we strongly recommend setting the path to your packages using this option, even if it works without it** (for example because your project manager automatically adds `src` to PYTHONPATH), to make sure anyone can build your docs from any location on their filesystem. ### Using the PYTHONPATH environment variable WARNING: **This method has limitations.** This method might work for you, with your current setup, but not for others trying your build your docs with their own setup/environment. We recommend using the [`paths` method](#using-the-paths-option) instead. You can take advantage of the usual Python loading mechanisms. In Bash and other shells, you can run your command like this (note the prepended `PYTHONPATH=...`): 1. mkdocs.yml in root, package in root ```tree root/ mkdocs.yml package/ ``` ```bash PYTHONPATH=. mkdocs build # actually not needed, default ``` 1. mkdocs.yml in root, package in subfolder ```tree root/ mkdocs.yml src/ package/ ``` ```bash PYTHONPATH=src mkdocs build ``` 1. mkdocs.yml in subfolder, package in root ```tree root/ docs/ mkdocs.yml package/ ``` ```bash PYTHONPATH=. mkdocs build -f docs/mkdocs.yml ``` 1. mkdocs.yml in subfolder, package in subfolder ```tree root/ docs/ mkdocs.yml src/ package/ ``` ```bash PYTHONPATH=src mkdocs build -f docs/mkdocs.yml ``` ### Installing your package in the current Python environment WARNING: **This method has limitations.** This method might work for you, with your current setup, but not for others trying your build your docs with their own setup/environment. We recommend using the [`paths` method](#using-the-paths-option) instead. Install your package in the current environment, and run MkDocs: /// tab | pip ```bash . venv/bin/activate pip install -e . mkdocs build ``` /// /// tab | PDM ```bash pdm install pdm run mkdocs build ``` /// /// tab | Poetry ```bash poetry install poetry run mkdocs build ``` /// mkdocstrings-python-handlers-1.10.5/duties.py000066400000000000000000000156051463457115100213070ustar00rootroot00000000000000"""Development tasks.""" from __future__ import annotations import os import sys from contextlib import contextmanager from importlib.metadata import version as pkgversion from pathlib import Path from typing import TYPE_CHECKING, Iterator from duty import duty, tools if TYPE_CHECKING: from duty.context import Context PY_SRC_PATHS = (Path(_) for _ in ("src", "tests", "duties.py", "scripts")) PY_SRC_LIST = tuple(str(_) for _ in PY_SRC_PATHS) PY_SRC = " ".join(PY_SRC_LIST) CI = os.environ.get("CI", "0") in {"1", "true", "yes", ""} WINDOWS = os.name == "nt" PTY = not WINDOWS and not CI MULTIRUN = os.environ.get("MULTIRUN", "0") == "1" def pyprefix(title: str) -> str: # noqa: D103 if MULTIRUN: prefix = f"(python{sys.version_info.major}.{sys.version_info.minor})" return f"{prefix:14}{title}" return title @contextmanager def material_insiders() -> Iterator[bool]: # noqa: D103 if "+insiders" in pkgversion("mkdocs-material"): os.environ["MATERIAL_INSIDERS"] = "true" try: yield True finally: os.environ.pop("MATERIAL_INSIDERS") else: yield False @duty def changelog(ctx: Context, bump: str = "") -> None: """Update the changelog in-place with latest commits. Parameters: bump: Bump option passed to git-changelog. """ ctx.run(tools.git_changelog(bump=bump or None), title="Updating changelog") @duty(pre=["check_quality", "check_types", "check_docs", "check_dependencies", "check-api"]) def check(ctx: Context) -> None: # noqa: ARG001 """Check it all!""" @duty def check_quality(ctx: Context) -> None: """Check the code quality.""" ctx.run( tools.ruff.check(*PY_SRC_LIST, config="config/ruff.toml"), title=pyprefix("Checking code quality"), ) @duty def check_docs(ctx: Context) -> None: """Check if the documentation builds correctly.""" Path("htmlcov").mkdir(parents=True, exist_ok=True) Path("htmlcov/index.html").touch(exist_ok=True) with material_insiders(): ctx.run( tools.mkdocs.build(strict=True, verbose=True), title=pyprefix("Building documentation"), ) @duty def check_types(ctx: Context) -> None: """Check that the code is correctly typed.""" os.environ["MYPYPATH"] = "src" ctx.run( tools.mypy(*PY_SRC_LIST, config_file="config/mypy.ini"), title=pyprefix("Type-checking"), ) @duty def check_api(ctx: Context, *cli_args: str) -> None: """Check for API breaking changes.""" ctx.run( tools.griffe.check("mkdocstrings_handlers.python", search=["src"], color=True).add_args(*cli_args), title="Checking for API breaking changes", nofail=True, ) @duty def docs(ctx: Context, *cli_args: str, host: str = "127.0.0.1", port: int = 8000) -> None: """Serve the documentation (localhost:8000). Parameters: host: The host to serve the docs from. port: The port to serve the docs on. """ with material_insiders(): ctx.run( tools.mkdocs.serve(dev_addr=f"{host}:{port}").add_args(*cli_args), title="Serving documentation", capture=False, ) @duty def docs_deploy(ctx: Context) -> None: """Deploy the documentation to GitHub pages.""" os.environ["DEPLOY"] = "true" with material_insiders() as insiders: if not insiders: ctx.run(lambda: False, title="Not deploying docs without Material for MkDocs Insiders!") origin = ctx.run("git config --get remote.origin.url", silent=True) if "pawamoy-insiders/mkdocstrings-python" in origin: ctx.run( "git remote add upstream git@github.com:mkdocstrings/python", silent=True, nofail=True, ) ctx.run( tools.mkdocs.gh_deploy(remote_name="upstream", force=True), title="Deploying documentation", ) else: ctx.run( lambda: False, title="Not deploying docs from public repository (do that from insiders instead!)", nofail=True, ) @duty def format(ctx: Context) -> None: """Run formatting tools on the code.""" ctx.run( tools.ruff.check(*PY_SRC_LIST, config="config/ruff.toml", fix_only=True, exit_zero=True), title="Auto-fixing code", ) ctx.run(tools.ruff.format(*PY_SRC_LIST, config="config/ruff.toml"), title="Formatting code") @duty def build(ctx: Context) -> None: """Build source and wheel distributions.""" ctx.run( tools.build(), title="Building source and wheel distributions", pty=PTY, ) @duty def publish(ctx: Context) -> None: """Publish source and wheel distributions to PyPI.""" if not Path("dist").exists(): ctx.run("false", title="No distribution files found") dists = [str(dist) for dist in Path("dist").iterdir()] ctx.run( tools.twine.upload(*dists, skip_existing=True), title="Publishing source and wheel distributions to PyPI", pty=PTY, ) @duty(post=["build", "publish", "docs-deploy"]) def release(ctx: Context, version: str = "") -> None: """Release a new Python package. Parameters: version: The new version number to use. """ origin = ctx.run("git config --get remote.origin.url", silent=True) if "pawamoy-insiders/mkdocstrings-python" in origin: ctx.run( lambda: False, title="Not releasing from insiders repository (do that from public repo instead!)", ) if not (version := (version or input("> Version to release: ")).strip()): ctx.run("false", title="A version must be provided") ctx.run("git add pyproject.toml CHANGELOG.md", title="Staging files", pty=PTY) ctx.run(["git", "commit", "-m", f"chore: Prepare release {version}"], title="Committing changes", pty=PTY) ctx.run(f"git tag {version}", title="Tagging commit", pty=PTY) ctx.run("git push", title="Pushing commits", pty=False) ctx.run("git push --tags", title="Pushing tags", pty=False) @duty(silent=True, aliases=["cov"]) def coverage(ctx: Context) -> None: """Report coverage as text and HTML.""" ctx.run(tools.coverage.combine(), nofail=True) ctx.run(tools.coverage.report(rcfile="config/coverage.ini"), capture=False) ctx.run(tools.coverage.html(rcfile="config/coverage.ini")) @duty def test(ctx: Context, *cli_args: str, match: str = "") -> None: """Run the test suite. Parameters: match: A pytest expression to filter selected tests. """ py_version = f"{sys.version_info.major}{sys.version_info.minor}" os.environ["COVERAGE_FILE"] = f".coverage.{py_version}" ctx.run( tools.pytest( "tests", config_file="config/pytest.ini", select=match, color="yes", ).add_args("-n", "auto", *cli_args), title=pyprefix("Running tests"), ) mkdocstrings-python-handlers-1.10.5/logo.png000077700000000000000000000000001463457115100234702docs/logo.pngustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/mkdocs.yml000066400000000000000000000121451463457115100214370ustar00rootroot00000000000000site_name: "mkdocstrings-python" site_description: "A Python handler for mkdocstrings." site_url: "https://mkdocstrings.github.io/python" repo_url: "https://github.com/mkdocstrings/python" repo_name: "mkdocstrings/python" site_dir: "site" watch: [mkdocs.yml, README.md, CONTRIBUTING.md, CHANGELOG.md, src/mkdocstrings_handlers] copyright: Copyright © 2021 Timothée Mazzucotelli edit_uri: edit/main/docs/ validation: omitted_files: warn absolute_links: warn unrecognized_links: warn nav: - Home: - Overview: index.md - Changelog: changelog.md - Credits: credits.md - License: license.md - Usage: - usage/index.md - Configuration options: - General: usage/configuration/general.md - Headings: usage/configuration/headings.md - Members: usage/configuration/members.md - Docstrings: usage/configuration/docstrings.md - Signatures: usage/configuration/signatures.md - Docstring styles: - Google: usage/docstrings/google.md - Numpy: usage/docstrings/numpy.md - Sphinx: usage/docstrings/sphinx.md - Advanced: - Customization: usage/customization.md - Extensions: usage/extensions.md # defer to gen-files + literate-nav - API reference: - mkdocstrings-python: reference/ - Development: - Contributing: contributing.md - Code of Conduct: code_of_conduct.md # - Coverage report: coverage.md - Insiders: - insiders/index.md - Getting started: - Installation: insiders/installation.md - Changelog: insiders/changelog.md - mkdocstrings: https://mkdocstrings.github.io/ theme: name: material custom_dir: docs/.overrides logo: logo.png features: - announce.dismiss - content.action.edit - content.action.view - content.code.annotate - content.code.copy - content.tooltips - navigation.footer - navigation.indexes - navigation.sections - navigation.tabs - navigation.tabs.sticky - navigation.top - search.highlight - search.suggest - toc.follow palette: - media: "(prefers-color-scheme)" toggle: icon: material/brightness-auto name: Switch to light mode - media: "(prefers-color-scheme: light)" scheme: default primary: teal accent: purple toggle: icon: material/weather-sunny name: Switch to dark mode - media: "(prefers-color-scheme: dark)" scheme: slate primary: black accent: lime toggle: icon: material/weather-night name: Switch to system preference extra_css: - css/material.css - css/mkdocstrings.css - css/insiders.css markdown_extensions: - abbr - attr_list - admonition - callouts: strip_period: no - footnotes - md_in_html - pymdownx.blocks.admonition - pymdownx.blocks.details - pymdownx.blocks.tab: alternate_style: true slugify: !!python/object/apply:pymdownx.slugs.slugify kwds: case: lower - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.highlight: pygments_lang_class: true - pymdownx.inlinehilite: style_plain_text: py3 - pymdownx.magiclink - pymdownx.snippets: auto_append: [docs/.glossary.md] base_path: [!relative $config_dir] check_paths: true - pymdownx.superfences - pymdownx.tabbed: alternate_style: true slugify: !!python/object/apply:pymdownx.slugs.slugify kwds: case: lower - pymdownx.tasklist: custom_checkbox: true - toc: permalink: "¤" plugins: - autorefs - search - markdown-exec - gen-files: scripts: - scripts/gen_ref_nav.py - literate-nav: nav_file: SUMMARY.md # - coverage - mkdocstrings: handlers: python: paths: [src] import: - https://docs.python.org/3/objects.inv - https://mkdocstrings.github.io/objects.inv - https://mkdocstrings.github.io/griffe/objects.inv - https://python-markdown.github.io/objects.inv options: docstring_options: ignore_init_summary: true docstring_section_style: list filters: ["!^_"] heading_level: 1 inherited_members: true merge_init_into_class: true parameter_headings: true preload_modules: [mkdocstrings] separate_signature: true show_root_heading: true show_root_full_path: false show_signature_annotations: true show_source: false show_symbol_type_heading: true show_symbol_type_toc: true signature_crossrefs: true summary: true unwrap_annotated: true - git-committers: enabled: !ENV [DEPLOY, false] repository: mkdocstrings/python - minify: minify_html: !ENV [DEPLOY, false] - group: enabled: !ENV [MATERIAL_INSIDERS, false] plugins: - typeset extra: social: - icon: fontawesome/brands/github link: https://github.com/pawamoy - icon: fontawesome/brands/mastodon link: https://fosstodon.org/@pawamoy - icon: fontawesome/brands/twitter link: https://twitter.com/pawamoy - icon: fontawesome/brands/gitter link: https://gitter.im/mkdocstrings/python - icon: fontawesome/brands/python link: https://pypi.org/project/mkdocstrings-python/ mkdocstrings-python-handlers-1.10.5/pyproject.toml000066400000000000000000000033241463457115100223470ustar00rootroot00000000000000[build-system] requires = ["pdm-backend"] build-backend = "pdm.backend" [project] name = "mkdocstrings-python" description = "A Python handler for mkdocstrings." authors = [{name = "Timothée Mazzucotelli", email = "dev@pawamoy.fr"}] license = {text = "ISC"} readme = "README.md" requires-python = ">=3.8" keywords = [] dynamic = ["version"] classifiers = [ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "Programming Language :: Python", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Topic :: Documentation", "Topic :: Software Development", "Topic :: Utilities", "Typing :: Typed", ] dependencies = [ "mkdocstrings>=0.25", "griffe>=0.47", ] [project.urls] Homepage = "https://mkdocstrings.github.io/python" Documentation = "https://mkdocstrings.github.io/python" Changelog = "https://mkdocstrings.github.io/python/changelog" Repository = "https://github.com/mkdocstrings/python" Issues = "https://github.com/mkdocstrings/python/issues" Discussions = "https://github.com/mkdocstrings/python/discussions" Gitter = "https://gitter.im/mkdocstrings/python" Funding = "https://github.com/sponsors/pawamoy" [tool.pdm] version = {source = "scm"} [tool.pdm.build] package-dir = "src" includes = ["src/mkdocstrings_handlers"] editable-backend = "editables" source-includes = ["share"] [tool.pdm.build.wheel-data] data = [ {path = "share/**/*", relative-to = "."}, ] mkdocstrings-python-handlers-1.10.5/scripts/000077500000000000000000000000001463457115100211205ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/scripts/gen_credits.py000066400000000000000000000150741463457115100237670ustar00rootroot00000000000000"""Script to generate the project's credits.""" from __future__ import annotations import os import sys from collections import defaultdict from importlib.metadata import distributions from itertools import chain from pathlib import Path from textwrap import dedent from typing import Dict, Iterable, Union from jinja2 import StrictUndefined from jinja2.sandbox import SandboxedEnvironment from packaging.requirements import Requirement # TODO: Remove once support for Python 3.10 is dropped. if sys.version_info >= (3, 11): import tomllib else: import tomli as tomllib project_dir = Path(os.getenv("MKDOCS_CONFIG_DIR", ".")) with project_dir.joinpath("pyproject.toml").open("rb") as pyproject_file: pyproject = tomllib.load(pyproject_file) project = pyproject["project"] project_name = project["name"] with project_dir.joinpath("devdeps.txt").open() as devdeps_file: devdeps = [line.strip() for line in devdeps_file if line.strip() and not line.strip().startswith(("-e", "#"))] PackageMetadata = Dict[str, Union[str, Iterable[str]]] Metadata = Dict[str, PackageMetadata] def _merge_fields(metadata: dict) -> PackageMetadata: fields = defaultdict(list) for header, value in metadata.items(): fields[header.lower()].append(value.strip()) return { field: value if len(value) > 1 or field in ("classifier", "requires-dist") else value[0] for field, value in fields.items() } def _norm_name(name: str) -> str: return name.replace("_", "-").replace(".", "-").lower() def _requirements(deps: list[str]) -> dict[str, Requirement]: return {_norm_name((req := Requirement(dep)).name): req for dep in deps} def _extra_marker(req: Requirement) -> str | None: if not req.marker: return None try: return next(marker[2].value for marker in req.marker._markers if getattr(marker[0], "value", None) == "extra") except StopIteration: return None def _get_metadata() -> Metadata: metadata = {} for pkg in distributions(): name = _norm_name(pkg.name) # type: ignore[attr-defined,unused-ignore] metadata[name] = _merge_fields(pkg.metadata) # type: ignore[arg-type] metadata[name]["spec"] = set() metadata[name]["extras"] = set() metadata[name].setdefault("summary", "") _set_license(metadata[name]) return metadata def _set_license(metadata: PackageMetadata) -> None: license_field = metadata.get("license-expression", metadata.get("license", "")) license_name = license_field if isinstance(license_field, str) else " + ".join(license_field) check_classifiers = license_name in ("UNKNOWN", "Dual License", "") or license_name.count("\n") if check_classifiers: license_names = [] for classifier in metadata["classifier"]: if classifier.startswith("License ::"): license_names.append(classifier.rsplit("::", 1)[1].strip()) license_name = " + ".join(license_names) metadata["license"] = license_name or "?" def _get_deps(base_deps: dict[str, Requirement], metadata: Metadata) -> Metadata: deps = {} for dep_name, dep_req in base_deps.items(): if dep_name not in metadata or dep_name == "mkdocstrings-python": continue metadata[dep_name]["spec"] |= {str(spec) for spec in dep_req.specifier} # type: ignore[operator] metadata[dep_name]["extras"] |= dep_req.extras # type: ignore[operator] deps[dep_name] = metadata[dep_name] again = True while again: again = False for pkg_name in metadata: if pkg_name in deps: for pkg_dependency in metadata[pkg_name].get("requires-dist", []): requirement = Requirement(pkg_dependency) dep_name = _norm_name(requirement.name) extra_marker = _extra_marker(requirement) if ( dep_name in metadata and dep_name not in deps and dep_name != project["name"] and (not extra_marker or extra_marker in deps[pkg_name]["extras"]) ): metadata[dep_name]["spec"] |= {str(spec) for spec in requirement.specifier} # type: ignore[operator] deps[dep_name] = metadata[dep_name] again = True return deps def _render_credits() -> str: metadata = _get_metadata() dev_dependencies = _get_deps(_requirements(devdeps), metadata) prod_dependencies = _get_deps( _requirements( chain( # type: ignore[arg-type] project.get("dependencies", []), chain(*project.get("optional-dependencies", {}).values()), ), ), metadata, ) template_data = { "project_name": project_name, "prod_dependencies": sorted(prod_dependencies.values(), key=lambda dep: str(dep["name"]).lower()), "dev_dependencies": sorted(dev_dependencies.values(), key=lambda dep: str(dep["name"]).lower()), "more_credits": "http://pawamoy.github.io/credits/", } template_text = dedent( """ # Credits These projects were used to build *{{ project_name }}*. **Thank you!** [Python](https://www.python.org/) | [uv](https://github.com/astral-sh/uv) | [copier-uv](https://github.com/pawamoy/copier-uv) {% macro dep_line(dep) -%} [{{ dep.name }}](https://pypi.org/project/{{ dep.name }}/) | {{ dep.summary }} | {{ ("`" ~ dep.spec|sort(reverse=True)|join(", ") ~ "`") if dep.spec else "" }} | `{{ dep.version }}` | {{ dep.license }} {%- endmacro %} {% if prod_dependencies -%} ### Runtime dependencies Project | Summary | Version (accepted) | Version (last resolved) | License ------- | ------- | ------------------ | ----------------------- | ------- {% for dep in prod_dependencies -%} {{ dep_line(dep) }} {% endfor %} {% endif -%} {% if dev_dependencies -%} ### Development dependencies Project | Summary | Version (accepted) | Version (last resolved) | License ------- | ------- | ------------------ | ----------------------- | ------- {% for dep in dev_dependencies -%} {{ dep_line(dep) }} {% endfor %} {% endif -%} {% if more_credits %}**[More credits from the author]({{ more_credits }})**{% endif %} """, ) jinja_env = SandboxedEnvironment(undefined=StrictUndefined) return jinja_env.from_string(template_text).render(**template_data) print(_render_credits()) mkdocstrings-python-handlers-1.10.5/scripts/gen_ref_nav.py000066400000000000000000000022551463457115100237470ustar00rootroot00000000000000"""Generate the code reference pages and navigation.""" from pathlib import Path import mkdocs_gen_files nav = mkdocs_gen_files.Nav() mod_symbol = '' root = Path(__file__).parent.parent src = root / "src" for path in sorted(src.rglob("*.py")): module_path = path.relative_to(src).with_suffix("") doc_path = path.relative_to(src).with_suffix(".md") full_doc_path = Path("reference", doc_path) parts = tuple(module_path.parts) if parts[-1] == "__init__": parts = parts[:-1] doc_path = doc_path.with_name("index.md") full_doc_path = full_doc_path.with_name("index.md") elif parts[-1].startswith("_"): continue nav_parts = [f"{mod_symbol} {part}" for part in parts] nav[tuple(nav_parts)] = doc_path.as_posix() with mkdocs_gen_files.open(full_doc_path, "w") as fd: ident = ".".join(parts) fd.write(f"---\ntitle: {ident}\n---\n\n::: {ident}") mkdocs_gen_files.set_edit_path(full_doc_path, ".." / path.relative_to(root)) with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file: nav_file.writelines(nav.build_literate_nav()) mkdocstrings-python-handlers-1.10.5/scripts/insiders.py000066400000000000000000000153201463457115100233130ustar00rootroot00000000000000"""Functions related to Insiders funding goals.""" from __future__ import annotations import json import logging import os import posixpath from dataclasses import dataclass from datetime import date, datetime, timedelta from itertools import chain from pathlib import Path from typing import Iterable, cast from urllib.error import HTTPError from urllib.parse import urljoin from urllib.request import urlopen import yaml logger = logging.getLogger(f"mkdocs.logs.{__name__}") def human_readable_amount(amount: int) -> str: # noqa: D103 str_amount = str(amount) if len(str_amount) >= 4: # noqa: PLR2004 return f"{str_amount[:len(str_amount)-3]},{str_amount[-3:]}" return str_amount @dataclass class Project: """Class representing an Insiders project.""" name: str url: str @dataclass class Feature: """Class representing an Insiders feature.""" name: str ref: str | None since: date | None project: Project | None def url(self, rel_base: str = "..") -> str | None: # noqa: D102 if not self.ref: return None if self.project: rel_base = self.project.url return posixpath.join(rel_base, self.ref.lstrip("/")) def render(self, rel_base: str = "..", *, badge: bool = False) -> None: # noqa: D102 new = "" if badge: recent = self.since and date.today() - self.since <= timedelta(days=60) # noqa: DTZ011 if recent: ft_date = self.since.strftime("%B %d, %Y") # type: ignore[union-attr] new = f' :material-alert-decagram:{{ .new-feature .vibrate title="Added on {ft_date}" }}' project = f"[{self.project.name}]({self.project.url}) — " if self.project else "" feature = f"[{self.name}]({self.url(rel_base)})" if self.ref else self.name print(f"- [{'x' if self.since else ' '}] {project}{feature}{new}") @dataclass class Goal: """Class representing an Insiders goal.""" name: str amount: int features: list[Feature] complete: bool = False @property def human_readable_amount(self) -> str: # noqa: D102 return human_readable_amount(self.amount) def render(self, rel_base: str = "..") -> None: # noqa: D102 print(f"#### $ {self.human_readable_amount} — {self.name}\n") if self.features: for feature in self.features: feature.render(rel_base) print("") else: print("There are no features in this goal for this project. ") print( "[See the features in this goal **for all Insiders projects.**]" f"(https://pawamoy.github.io/insiders/#{self.amount}-{self.name.lower().replace(' ', '-')})", ) def load_goals(data: str, funding: int = 0, project: Project | None = None) -> dict[int, Goal]: """Load goals from JSON data. Parameters: data: The JSON data. funding: The current total funding, per month. origin: The origin of the data (URL). Returns: A dictionaries of goals, keys being their target monthly amount. """ goals_data = yaml.safe_load(data)["goals"] return { amount: Goal( name=goal_data["name"], amount=amount, complete=funding >= amount, features=[ Feature( name=feature_data["name"], ref=feature_data.get("ref"), since=feature_data.get("since") and datetime.strptime(feature_data["since"], "%Y/%m/%d").date(), # noqa: DTZ007 project=project, ) for feature_data in goal_data["features"] ], ) for amount, goal_data in goals_data.items() } def _load_goals_from_disk(path: str, funding: int = 0) -> dict[int, Goal]: project_dir = os.getenv("MKDOCS_CONFIG_DIR", ".") try: data = Path(project_dir, path).read_text() except OSError as error: raise RuntimeError(f"Could not load data from disk: {path}") from error return load_goals(data, funding) def _load_goals_from_url(source_data: tuple[str, str, str], funding: int = 0) -> dict[int, Goal]: project_name, project_url, data_fragment = source_data data_url = urljoin(project_url, data_fragment) try: with urlopen(data_url) as response: # noqa: S310 data = response.read() except HTTPError as error: raise RuntimeError(f"Could not load data from network: {data_url}") from error return load_goals(data, funding, project=Project(name=project_name, url=project_url)) def _load_goals(source: str | tuple[str, str, str], funding: int = 0) -> dict[int, Goal]: if isinstance(source, str): return _load_goals_from_disk(source, funding) return _load_goals_from_url(source, funding) def funding_goals(source: str | list[str | tuple[str, str, str]], funding: int = 0) -> dict[int, Goal]: """Load funding goals from a given data source. Parameters: source: The data source (local file path or URL). funding: The current total funding, per month. Returns: A dictionaries of goals, keys being their target monthly amount. """ if isinstance(source, str): return _load_goals_from_disk(source, funding) goals = {} for src in source: source_goals = _load_goals(src, funding) for amount, goal in source_goals.items(): if amount not in goals: goals[amount] = goal else: goals[amount].features.extend(goal.features) return {amount: goals[amount] for amount in sorted(goals)} def feature_list(goals: Iterable[Goal]) -> list[Feature]: """Extract feature list from funding goals. Parameters: goals: A list of funding goals. Returns: A list of features. """ return list(chain.from_iterable(goal.features for goal in goals)) def load_json(url: str) -> str | list | dict: # noqa: D103 with urlopen(url) as response: # noqa: S310 return json.loads(response.read().decode()) data_source = globals()["data_source"] sponsor_url = "https://github.com/sponsors/pawamoy" data_url = "https://raw.githubusercontent.com/pawamoy/sponsors/main" numbers: dict[str, int] = load_json(f"{data_url}/numbers.json") # type: ignore[assignment] sponsors: list[dict] = load_json(f"{data_url}/sponsors.json") # type: ignore[assignment] current_funding = numbers["total"] sponsors_count = numbers["count"] goals = funding_goals(data_source, funding=current_funding) ongoing_goals = [goal for goal in goals.values() if not goal.complete] unreleased_features = sorted( (ft for ft in feature_list(ongoing_goals) if ft.since), key=lambda ft: cast(date, ft.since), reverse=True, ) mkdocstrings-python-handlers-1.10.5/scripts/make000077500000000000000000000152231463457115100217660ustar00rootroot00000000000000#!/usr/bin/env python3 """Management commands.""" import os import shutil import subprocess import sys from contextlib import contextmanager from pathlib import Path from typing import Any, Iterator PYTHON_VERSIONS = os.getenv("PYTHON_VERSIONS", "3.8 3.9 3.10 3.11 3.12 3.13").split() exe = "" prefix = "" def shell(cmd: str) -> None: """Run a shell command.""" subprocess.run(cmd, shell=True, check=True) # noqa: S602 @contextmanager def environ(**kwargs: str) -> Iterator[None]: """Temporarily set environment variables.""" original = dict(os.environ) os.environ.update(kwargs) try: yield finally: os.environ.clear() os.environ.update(original) def uv_install() -> None: """Install dependencies using uv.""" uv_opts = "" if "UV_RESOLUTION" in os.environ: uv_opts = f"--resolution={os.getenv('UV_RESOLUTION')}" cmd = f"uv pip compile {uv_opts} pyproject.toml devdeps.txt | uv pip install -r -" shell(cmd) if "CI" not in os.environ: shell("uv pip install --no-deps -e .") else: shell("uv pip install --no-deps .") def setup() -> None: """Setup the project.""" if not shutil.which("uv"): raise ValueError("make: setup: uv must be installed, see https://github.com/astral-sh/uv") print("Installing dependencies (default environment)") # noqa: T201 default_venv = Path(".venv") if not default_venv.exists(): shell("uv venv --python python") uv_install() if PYTHON_VERSIONS: for version in PYTHON_VERSIONS: print(f"\nInstalling dependencies (python{version})") # noqa: T201 venv_path = Path(f".venvs/{version}") if not venv_path.exists(): shell(f"uv venv --python {version} {venv_path}") with environ(VIRTUAL_ENV=str(venv_path.resolve())): uv_install() def activate(path: str) -> None: """Activate a virtual environment.""" global exe, prefix # noqa: PLW0603 if (bin := Path(path, "bin")).exists(): activate_script = bin / "activate_this.py" elif (scripts := Path(path, "Scripts")).exists(): activate_script = scripts / "activate_this.py" exe = ".exe" prefix = f"{path}/Scripts/" else: raise ValueError(f"make: activate: Cannot find activation script in {path}") if not activate_script.exists(): raise ValueError(f"make: activate: Cannot find activation script in {path}") exec(activate_script.read_text(), {"__file__": str(activate_script)}) # noqa: S102 def run(version: str, cmd: str, *args: str, **kwargs: Any) -> None: """Run a command in a virtual environment.""" kwargs = {"check": True, **kwargs} if version == "default": activate(".venv") subprocess.run([f"{prefix}{cmd}{exe}", *args], **kwargs) # noqa: S603, PLW1510 else: activate(f".venvs/{version}") os.environ["MULTIRUN"] = "1" subprocess.run([f"{prefix}{cmd}{exe}", *args], **kwargs) # noqa: S603, PLW1510 def multirun(cmd: str, *args: str, **kwargs: Any) -> None: """Run a command for all configured Python versions.""" if PYTHON_VERSIONS: for version in PYTHON_VERSIONS: run(version, cmd, *args, **kwargs) else: run("default", cmd, *args, **kwargs) def allrun(cmd: str, *args: str, **kwargs: Any) -> None: """Run a command in all virtual environments.""" run("default", cmd, *args, **kwargs) if PYTHON_VERSIONS: multirun(cmd, *args, **kwargs) def clean() -> None: """Delete build artifacts and cache files.""" paths_to_clean = ["build", "dist", "htmlcov", "site", ".coverage*", ".pdm-build"] for path in paths_to_clean: shell(f"rm -rf {path}") cache_dirs = [".cache", ".pytest_cache", ".mypy_cache", ".ruff_cache", "__pycache__"] for dirpath in Path(".").rglob("*"): if any(dirpath.match(pattern) for pattern in cache_dirs) and not (dirpath.match(".venv") or dirpath.match(".venvs")): shutil.rmtree(path, ignore_errors=True) def vscode() -> None: """Configure VSCode to work on this project.""" Path(".vscode").mkdir(parents=True, exist_ok=True) shell("cp -v config/vscode/* .vscode") def main() -> int: """Main entry point.""" args = list(sys.argv[1:]) if not args or args[0] == "help": if len(args) > 1: run("default", "duty", "--help", args[1]) else: print("Available commands") # noqa: T201 print(" help Print this help. Add task name to print help.") # noqa: T201 print(" setup Setup all virtual environments (install dependencies).") # noqa: T201 print(" run Run a command in the default virtual environment.") # noqa: T201 print(" multirun Run a command for all configured Python versions.") # noqa: T201 print(" allrun Run a command in all virtual environments.") # noqa: T201 print(" 3.x Run a command in the virtual environment for Python 3.x.") # noqa: T201 print(" clean Delete build artifacts and cache files.") # noqa: T201 print(" vscode Configure VSCode to work on this project.") # noqa: T201 try: run("default", "python", "-V", capture_output=True) except (subprocess.CalledProcessError, ValueError): pass else: print("\nAvailable tasks") # noqa: T201 run("default", "duty", "--list") return 0 while args: cmd = args.pop(0) if cmd == "run": run("default", *args) return 0 if cmd == "multirun": multirun(*args) return 0 if cmd == "allrun": allrun(*args) return 0 if cmd.startswith("3."): run(cmd, *args) return 0 opts = [] while args and (args[0].startswith("-") or "=" in args[0]): opts.append(args.pop(0)) if cmd == "clean": clean() elif cmd == "setup": setup() elif cmd == "vscode": vscode() elif cmd == "check": multirun("duty", "check-quality", "check-types", "check-docs") run("default", "duty", "check-api") elif cmd in {"check-quality", "check-docs", "check-types", "test"}: multirun("duty", cmd, *opts) else: run("default", "duty", cmd, *opts) return 0 if __name__ == "__main__": try: sys.exit(main()) except Exception: # noqa: BLE001 sys.exit(1) mkdocstrings-python-handlers-1.10.5/src/000077500000000000000000000000001463457115100202205ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/src/mkdocstrings_handlers/000077500000000000000000000000001463457115100246075ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/src/mkdocstrings_handlers/python/000077500000000000000000000000001463457115100261305ustar00rootroot00000000000000mkdocstrings-python-handlers-1.10.5/src/mkdocstrings_handlers/python/__init__.py000066400000000000000000000002001463457115100302310ustar00rootroot00000000000000"""Python handler for mkdocstrings.""" from mkdocstrings_handlers.python.handler import get_handler __all__ = ["get_handler"] mkdocstrings-python-handlers-1.10.5/src/mkdocstrings_handlers/python/debug.py000066400000000000000000000055161463457115100275770ustar00rootroot00000000000000"""Debugging utilities.""" from __future__ import annotations import os import platform import sys from dataclasses import dataclass from importlib import metadata @dataclass class Variable: """Dataclass describing an environment variable.""" name: str """Variable name.""" value: str """Variable value.""" @dataclass class Package: """Dataclass describing a Python package.""" name: str """Package name.""" version: str """Package version.""" @dataclass class Environment: """Dataclass to store environment information.""" interpreter_name: str """Python interpreter name.""" interpreter_version: str """Python interpreter version.""" interpreter_path: str """Path to Python executable.""" platform: str """Operating System.""" packages: list[Package] """Installed packages.""" variables: list[Variable] """Environment variables.""" def _interpreter_name_version() -> tuple[str, str]: if hasattr(sys, "implementation"): impl = sys.implementation.version version = f"{impl.major}.{impl.minor}.{impl.micro}" kind = impl.releaselevel if kind != "final": version += kind[0] + str(impl.serial) return sys.implementation.name, version return "", "0.0.0" def get_version(dist: str = "mkdocstrings-python") -> str: """Get version of the given distribution. Parameters: dist: A distribution name. Returns: A version number. """ try: return metadata.version(dist) except metadata.PackageNotFoundError: return "0.0.0" def get_debug_info() -> Environment: """Get debug/environment information. Returns: Environment information. """ py_name, py_version = _interpreter_name_version() packages = ["mkdocs", "mkdocstrings", "mkdocstrings-python", "griffe"] variables = ["PYTHONPATH", *[var for var in os.environ if var.startswith("MKDOCSTRINGS_PYTHON")]] return Environment( interpreter_name=py_name, interpreter_version=py_version, interpreter_path=sys.executable, platform=platform.platform(), variables=[Variable(var, val) for var in variables if (val := os.getenv(var))], packages=[Package(pkg, get_version(pkg)) for pkg in packages], ) def print_debug_info() -> None: """Print debug/environment information.""" info = get_debug_info() print(f"- __System__: {info.platform}") print(f"- __Python__: {info.interpreter_name} {info.interpreter_version} ({info.interpreter_path})") print("- __Environment variables__:") for var in info.variables: print(f" - `{var.name}`: `{var.value}`") print("- __Installed packages__:") for pkg in info.packages: print(f" - `{pkg.name}` v{pkg.version}") if __name__ == "__main__": print_debug_info() mkdocstrings-python-handlers-1.10.5/src/mkdocstrings_handlers/python/handler.py000066400000000000000000000574211463457115100301300ustar00rootroot00000000000000"""This module implements a handler for the Python language.""" from __future__ import annotations import glob import os import posixpath import re import sys from collections import ChainMap from contextlib import suppress from pathlib import Path from typing import TYPE_CHECKING, Any, BinaryIO, ClassVar, Iterator, Mapping, Sequence from griffe.collections import LinesCollection, ModulesCollection from griffe.docstrings.parsers import Parser from griffe.exceptions import AliasResolutionError from griffe.extensions import load_extensions from griffe.loader import GriffeLoader from griffe.logger import patch_loggers from mkdocstrings.extension import PluginError from mkdocstrings.handlers.base import BaseHandler, CollectionError, CollectorItem from mkdocstrings.inventory import Inventory from mkdocstrings.loggers import get_logger from mkdocstrings_handlers.python import rendering if TYPE_CHECKING: from markdown import Markdown if sys.version_info >= (3, 11): from contextlib import chdir else: # TODO: remove once support for Python 3.10 is dropped from contextlib import contextmanager @contextmanager def chdir(path: str) -> Iterator[None]: # noqa: D103 old_wd = os.getcwd() os.chdir(path) try: yield finally: os.chdir(old_wd) logger = get_logger(__name__) patch_loggers(get_logger) class PythonHandler(BaseHandler): """The Python handler class.""" name: str = "python" """The handler's name.""" domain: str = "py" # to match Sphinx's default domain """The cross-documentation domain/language for this handler.""" enable_inventory: bool = True """Whether this handler is interested in enabling the creation of the `objects.inv` Sphinx inventory file.""" fallback_theme = "material" """The fallback theme.""" fallback_config: ClassVar[dict] = {"fallback": True} """The configuration used to collect item during autorefs fallback.""" default_config: ClassVar[dict] = { "find_stubs_package": False, "docstring_style": "google", "docstring_options": {}, "show_symbol_type_heading": False, "show_symbol_type_toc": False, "show_root_heading": False, "show_root_toc_entry": True, "show_root_full_path": True, "show_root_members_full_path": False, "show_object_full_path": False, "show_category_heading": False, "show_if_no_docstring": False, "show_signature": True, "show_signature_annotations": False, "signature_crossrefs": False, "separate_signature": False, "line_length": 60, "merge_init_into_class": False, "show_docstring_attributes": True, "show_docstring_functions": True, "show_docstring_classes": True, "show_docstring_modules": True, "show_docstring_description": True, "show_docstring_examples": True, "show_docstring_other_parameters": True, "show_docstring_parameters": True, "show_docstring_raises": True, "show_docstring_receives": True, "show_docstring_returns": True, "show_docstring_warns": True, "show_docstring_yields": True, "show_source": True, "show_bases": True, "show_submodules": False, "group_by_category": True, "heading_level": 2, "members_order": rendering.Order.alphabetical.value, "docstring_section_style": "table", "members": None, "inherited_members": False, "filters": ["!^_[^_]"], "annotations_path": "brief", "preload_modules": None, "allow_inspection": True, "summary": False, "show_labels": True, "unwrap_annotated": False, } """Default handler configuration. Attributes: General options: find_stubs_package (bool): Whether to load stubs package (package-stubs) when extracting docstrings. Default `False`. allow_inspection (bool): Whether to allow inspecting modules when visiting them is not possible. Default: `True`. show_bases (bool): Show the base classes of a class. Default: `True`. show_source (bool): Show the source code of this object. Default: `True`. preload_modules (list[str] | None): Pre-load modules that are not specified directly in autodoc instructions (`::: identifier`). It is useful when you want to render documentation for a particular member of an object, and this member is imported from another package than its parent. For an imported member to be rendered, you need to add it to the `__all__` attribute of the importing module. The modules must be listed as an array of strings. Default: `None`. Attributes: Headings options: heading_level (int): The initial heading level to use. Default: `2`. show_root_heading (bool): Show the heading of the object at the root of the documentation tree (i.e. the object referenced by the identifier after `:::`). Default: `False`. show_root_toc_entry (bool): If the root heading is not shown, at least add a ToC entry for it. Default: `True`. show_root_full_path (bool): Show the full Python path for the root object heading. Default: `True`. show_root_members_full_path (bool): Show the full Python path of the root members. Default: `False`. show_object_full_path (bool): Show the full Python path of every object. Default: `False`. show_category_heading (bool): When grouped by categories, show a heading for each category. Default: `False`. show_symbol_type_heading (bool): Show the symbol type in headings (e.g. mod, class, meth, func and attr). Default: `False`. show_symbol_type_toc (bool): Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr). Default: `False`. Attributes: Members options: inherited_members (list[str] | bool | None): A boolean, or an explicit list of inherited members to render. If true, select all inherited members, which can then be filtered with `members`. If false or empty list, do not select any inherited member. Default: `False`. members (list[str] | bool | None): A boolean, or an explicit list of members to render. If true, select all members without further filtering. If false or empty list, do not render members. If none, select all members and apply further filtering with filters and docstrings. Default: `None`. members_order (str): The members ordering to use. Options: `alphabetical` - order by the members names, `source` - order members as they appear in the source file. Default: `"alphabetical"`. filters (list[str] | None): A list of filters applied to filter objects based on their name. A filter starting with `!` will exclude matching objects instead of including them. The `members` option takes precedence over `filters` (filters will still be applied recursively to lower members in the hierarchy). Default: `["!^_[^_]"]`. group_by_category (bool): Group the object's children by categories: attributes, classes, functions, and modules. Default: `True`. show_submodules (bool): When rendering a module, show its submodules recursively. Default: `False`. summary (bool | dict[str, bool]): Whether to render summaries of modules, classes, functions (methods) and attributes. show_labels (bool): Whether to show labels of the members. Default: `True`. Attributes: Docstrings options: docstring_style (str): The docstring style to use: `google`, `numpy`, `sphinx`, or `None`. Default: `"google"`. docstring_options (dict): The options for the docstring parser. See parsers under [`griffe.docstrings`][]. docstring_section_style (str): The style used to render docstring sections. Options: `table`, `list`, `spacy`. Default: `"table"`. merge_init_into_class (bool): Whether to merge the `__init__` method into the class' signature and docstring. Default: `False`. show_if_no_docstring (bool): Show the object heading even if it has no docstring or children with docstrings. Default: `False`. show_docstring_attributes (bool): Whether to display the "Attributes" section in the object's docstring. Default: `True`. show_docstring_functions (bool): Whether to display the "Functions" or "Methods" sections in the object's docstring. Default: `True`. show_docstring_classes (bool): Whether to display the "Classes" section in the object's docstring. Default: `True`. show_docstring_modules (bool): Whether to display the "Modules" section in the object's docstring. Default: `True`. show_docstring_description (bool): Whether to display the textual block (including admonitions) in the object's docstring. Default: `True`. show_docstring_examples (bool): Whether to display the "Examples" section in the object's docstring. Default: `True`. show_docstring_other_parameters (bool): Whether to display the "Other Parameters" section in the object's docstring. Default: `True`. show_docstring_parameters (bool): Whether to display the "Parameters" section in the object's docstring. Default: `True`. show_docstring_raises (bool): Whether to display the "Raises" section in the object's docstring. Default: `True`. show_docstring_receives (bool): Whether to display the "Receives" section in the object's docstring. Default: `True`. show_docstring_returns (bool): Whether to display the "Returns" section in the object's docstring. Default: `True`. show_docstring_warns (bool): Whether to display the "Warns" section in the object's docstring. Default: `True`. show_docstring_yields (bool): Whether to display the "Yields" section in the object's docstring. Default: `True`. Attributes: Signatures/annotations options: annotations_path (str): The verbosity for annotations path: `brief` (recommended), or `source` (as written in the source). Default: `"brief"`. line_length (int): Maximum line length when formatting code/signatures. Default: `60`. show_signature (bool): Show methods and functions signatures. Default: `True`. show_signature_annotations (bool): Show the type annotations in methods and functions signatures. Default: `False`. signature_crossrefs (bool): Whether to render cross-references for type annotations in signatures. Default: `False`. separate_signature (bool): Whether to put the whole signature in a code block below the heading. If Black is installed, the signature is also formatted using it. Default: `False`. unwrap_annotated (bool): Whether to unwrap `Annotated` types to show only the type without the annotations. Default: `False`. """ def __init__( self, *args: Any, config_file_path: str | None = None, paths: list[str] | None = None, locale: str = "en", load_external_modules: bool | None = None, **kwargs: Any, ) -> None: """Initialize the handler. Parameters: *args: Handler name, theme and custom templates. config_file_path: The MkDocs configuration file path. paths: A list of paths to use as Griffe search paths. locale: The locale to use when rendering content. load_external_modules: Load external modules when resolving aliases. **kwargs: Same thing, but with keyword arguments. """ super().__init__(*args, **kwargs) # Warn if user overrides base templates. if custom_templates := kwargs.get("custom_templates", ()): config_dir = Path(config_file_path or "./mkdocs.yml").parent for theme_dir in config_dir.joinpath(custom_templates, "python").iterdir(): if theme_dir.joinpath("_base").is_dir(): logger.warning( f"Overriding base template '{theme_dir.name}/_base/