pax_global_header00006660000000000000000000000064145470176020014520gustar00rootroot0000000000000052 comment=36499eb87db7314c267861ecc7aeaac2a21cf656 mkdocstrings-python-handlers-1.8.0/000077500000000000000000000000001454701760200173525ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/.copier-answers.yml000066400000000000000000000013241454701760200231140ustar00rootroot00000000000000# Changes here will be overwritten by Copier _commit: 1.1.3 _src_path: gh:pawamoy/copier-pdm author_email: pawamoy@pm.me author_fullname: Timothée Mazzucotelli author_username: pawamoy copyright_date: '2021' copyright_holder: Timothée Mazzucotelli copyright_holder_email: pawamoy@pm.me copyright_license: ISC License insiders: true insiders_repository_name: mkdocstrings-python project_description: A Python handler for mkdocstrings. project_name: mkdocstrings-python public_release: true python_package_command_line_name: '' python_package_distribution_name: mkdocstrings-python python_package_import_name: mkdocstrings_handlers repository_name: python repository_namespace: mkdocstrings repository_provider: github.com mkdocstrings-python-handlers-1.8.0/.github/000077500000000000000000000000001454701760200207125ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/.github/FUNDING.yml000066400000000000000000000001071454701760200225250ustar00rootroot00000000000000github: pawamoy ko_fi: pawamoy custom: - https://www.paypal.me/pawamoy mkdocstrings-python-handlers-1.8.0/.github/ISSUE_TEMPLATE/000077500000000000000000000000001454701760200230755ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/.github/ISSUE_TEMPLATE/bug_report.md000066400000000000000000000027171454701760200255760ustar00rootroot00000000000000--- 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.8.0/.github/ISSUE_TEMPLATE/config.yml000066400000000000000000000003301454701760200250610ustar00rootroot00000000000000blank_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.8.0/.github/ISSUE_TEMPLATE/feature_request.md000066400000000000000000000012131454701760200266170ustar00rootroot00000000000000--- 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.8.0/.github/workflows/000077500000000000000000000000001454701760200227475ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/.github/workflows/ci.yml000066400000000000000000000050031454701760200240630ustar00rootroot00000000000000name: 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 jobs: quality: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v3 - name: Fetch all tags run: git fetch --depth=1 --tags - name: Set up PDM uses: pdm-project/setup-pdm@v3 with: python-version: "3.8" - name: Resolving dependencies run: pdm lock -v --no-cross-platform -G ci-quality - name: Install dependencies run: pdm install -G ci-quality - name: Check if the documentation builds correctly run: pdm run duty check-docs - name: Check the code quality run: pdm run duty check-quality - name: Check if the code is correctly typed run: pdm run duty check-types - name: Check for vulnerabilities in dependencies run: pdm run duty check-dependencies - name: Check for breaking changes in the API run: pdm run duty 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"} ]' | tr -d '[:space:]' >> $GITHUB_OUTPUT else echo 'jobs=[]' >> $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" exclude: ${{ fromJSON(needs.exclude-test-jobs.outputs.jobs) }} runs-on: ${{ matrix.os }} continue-on-error: ${{ matrix.python-version == '3.12' }} steps: - name: Checkout uses: actions/checkout@v3 - name: Set up PDM uses: pdm-project/setup-pdm@v3 with: python-version: ${{ matrix.python-version }} allow-python-prereleases: true - name: Resolving dependencies run: pdm lock -v --no-cross-platform -G ci-tests - name: Install dependencies run: pdm install --no-editable -G ci-tests - name: Run the test suite run: pdm run duty test mkdocstrings-python-handlers-1.8.0/.github/workflows/release.yml000066400000000000000000000025461454701760200251210ustar00rootroot00000000000000name: release on: push permissions: contents: write jobs: release: runs-on: ubuntu-latest if: startsWith(github.ref, 'refs/tags/') steps: - name: Checkout uses: actions/checkout@v3 - 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@v3 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.8.0/.gitignore000066400000000000000000000003141454701760200213400ustar00rootroot00000000000000.idea/ __pycache__/ *.py[cod] dist/ *.egg-info/ build/ htmlcov/ .coverage* pip-wheel-metadata/ .pytest_cache/ .mypy_cache/ site/ pdm.lock pdm.toml .pdm-plugins/ .pdm-python __pypackages__/ .venv/ .cache/ mkdocstrings-python-handlers-1.8.0/.gitpod.dockerfile000066400000000000000000000001741454701760200227510ustar00rootroot00000000000000FROM gitpod/workspace-full USER gitpod ENV PIP_USER=no RUN pip3 install pipx; \ pipx install pdm; \ pipx ensurepath mkdocstrings-python-handlers-1.8.0/.gitpod.yml000066400000000000000000000002171454701760200214410ustar00rootroot00000000000000vscode: extensions: - ms-python.python image: file: .gitpod.dockerfile ports: - port: 8000 onOpen: notify tasks: - init: make setup mkdocstrings-python-handlers-1.8.0/CHANGELOG.md000066400000000000000000001040721454701760200211670ustar00rootroot00000000000000# 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.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.8.0/CODE_OF_CONDUCT.md000066400000000000000000000125471454701760200221620ustar00rootroot00000000000000# 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 pawamoy@pm.me. 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.8.0/CONTRIBUTING.md000066400000000000000000000102321454701760200216010ustar00rootroot00000000000000# 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 > [PDM](https://github.com/pdm-project/pdm) > manually. > > You can install it with: > > ```bash > python3 -m pip install --user pipx > pipx install pdm > ``` > > Now you can try running `make setup` again, > or simply `pdm 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 `pdm 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-pdm/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.8.0/LICENSE000066400000000000000000000013621454701760200203610ustar00rootroot00000000000000ISC 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.8.0/Makefile000066400000000000000000000016101454701760200210100ustar00rootroot00000000000000.DEFAULT_GOAL := help SHELL := bash DUTY := $(if $(VIRTUAL_ENV),,pdm run) duty export PDM_MULTIRUN_VERSIONS ?= 3.8 3.9 3.10 3.11 3.12 args = $(foreach a,$($(subst -,_,$1)_args),$(if $(value $a),$a="$($a)")) check_quality_args = files docs_args = host port release_args = version test_args = match BASIC_DUTIES = \ changelog \ check-api \ check-dependencies \ clean \ coverage \ docs \ docs-deploy \ format \ release \ vscode QUALITY_DUTIES = \ check-quality \ check-docs \ check-types \ test .PHONY: help help: @$(DUTY) --list .PHONY: lock lock: @pdm lock -G:all .PHONY: setup setup: @bash scripts/setup.sh .PHONY: check check: @pdm multirun duty check-quality check-types check-docs @$(DUTY) check-dependencies check-api .PHONY: $(BASIC_DUTIES) $(BASIC_DUTIES): @$(DUTY) $@ $(call args,$@) .PHONY: $(QUALITY_DUTIES) $(QUALITY_DUTIES): @pdm multirun duty $@ $(call args,$@) mkdocstrings-python-handlers-1.8.0/README.md000066400000000000000000000102511454701760200206300ustar00rootroot00000000000000

mkdocstrings-python

A Python handler for mkdocstrings.

ci documentation pypi version gitpod gitter

---

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.8.0/config/000077500000000000000000000000001454701760200206175ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/config/black.toml000066400000000000000000000000721454701760200225670ustar00rootroot00000000000000[tool.black] line-length = 120 exclude = "tests/fixtures" mkdocstrings-python-handlers-1.8.0/config/coverage.ini000066400000000000000000000005771454701760200231240ustar00rootroot00000000000000[coverage:run] branch = true parallel = true source = src/mkdocstrings_handlers tests/ [coverage:paths] equivalent = src/ __pypackages__/ [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.8.0/config/git-changelog.toml000066400000000000000000000003121454701760200242200ustar00rootroot00000000000000bump = "auto" convention = "angular" in-place = true output = "CHANGELOG.md" parse-refs = false parse-trailers = true sections = ["build", "deps", "feat", "fix", "refactor"] template = "keepachangelog" mkdocstrings-python-handlers-1.8.0/config/mypy.ini000066400000000000000000000002521454701760200223150ustar00rootroot00000000000000[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.8.0/config/pytest.ini000066400000000000000000000005471454701760200226560ustar00rootroot00000000000000[pytest] norecursedirs = .git .tox .env dist build python_files = test_*.py *_test.py tests.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.8.0/config/ruff.toml000066400000000000000000000040711454701760200224600ustar00rootroot00000000000000target-version = "py38" line-length = 132 exclude = [ "fixtures", "site", ] 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 ] [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 ] [flake8-quotes] docstring-quotes = "double" [flake8-tidy-imports] ban-relative-imports = "all" [isort] known-first-party = ["mkdocstrings_handlers"] [pydocstyle] convention = "google" mkdocstrings-python-handlers-1.8.0/config/vscode/000077500000000000000000000000001454701760200221025ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/config/vscode/launch.json000066400000000000000000000015711454701760200242530ustar00rootroot00000000000000{ "version": "0.2.0", "configurations": [ { "name": "python (current file)", "type": "python", "request": "launch", "program": "${file}", "console": "integratedTerminal", "justMyCode": false }, { "name": "test", "type": "python", "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.8.0/config/vscode/settings.json000066400000000000000000000030061454701760200246340ustar00rootroot00000000000000{ "files.watcherExclude": { "**/__pypackages__/**": true, "**/.venv*/**": true, "**/venv*/**": true }, "[python]": { "editor.defaultFormatter": "ms-python.black-formatter" }, "python.autoComplete.extraPaths": [ "__pypackages__/3.8/lib", "__pypackages__/3.9/lib", "__pypackages__/3.10/lib", "__pypackages__/3.11/lib", "__pypackages__/3.12/lib" ], "python.analysis.extraPaths": [ "__pypackages__/3.8/lib", "__pypackages__/3.9/lib", "__pypackages__/3.10/lib", "__pypackages__/3.11/lib", "__pypackages__/3.12/lib" ], "black-formatter.args": [ "--config=config/black.toml" ], "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.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.8.0/config/vscode/tasks.json000066400000000000000000000044261454701760200241300ustar00rootroot00000000000000{ "version": "2.0.0", "tasks": [ { "label": "changelog", "type": "shell", "command": "pdm run duty changelog" }, { "label": "check", "type": "shell", "command": "pdm run duty check" }, { "label": "check-quality", "type": "shell", "command": "pdm run duty check-quality" }, { "label": "check-types", "type": "shell", "command": "pdm run duty check-types" }, { "label": "check-docs", "type": "shell", "command": "pdm run duty check-docs" }, { "label": "check-dependencies", "type": "shell", "command": "pdm run duty check-dependencies" }, { "label": "check-api", "type": "shell", "command": "pdm run duty check-api" }, { "label": "clean", "type": "shell", "command": "pdm run duty clean" }, { "label": "docs", "type": "shell", "command": "pdm run duty docs" }, { "label": "docs-deploy", "type": "shell", "command": "pdm run duty docs-deploy" }, { "label": "format", "type": "shell", "command": "pdm run duty format" }, { "label": "lock", "type": "shell", "command": "pdm lock -G:all" }, { "label": "release", "type": "shell", "command": "pdm run duty release ${input:version}" }, { "label": "setup", "type": "shell", "command": "bash scripts/setup.sh" }, { "label": "test", "type": "shell", "command": "pdm run duty test coverage", "group": "test" }, { "label": "vscode", "type": "shell", "command": "pdm run duty vscode" } ], "inputs": [ { "id": "version", "type": "promptString", "description": "Version" } ] }mkdocstrings-python-handlers-1.8.0/docs/000077500000000000000000000000001454701760200203025ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/docs/.glossary.md000066400000000000000000000015251454701760200225500ustar00rootroot00000000000000[__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.8.0/docs/.overrides/000077500000000000000000000000001454701760200223625ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/docs/.overrides/main.html000066400000000000000000000010471454701760200241760ustar00rootroot00000000000000{% 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.8.0/docs/changelog.md000066400000000000000000000000261454701760200225510ustar00rootroot00000000000000--8<-- "CHANGELOG.md" mkdocstrings-python-handlers-1.8.0/docs/code_of_conduct.md000066400000000000000000000000341454701760200237360ustar00rootroot00000000000000--8<-- "CODE_OF_CONDUCT.md" mkdocstrings-python-handlers-1.8.0/docs/contributing.md000066400000000000000000000000311454701760200233250ustar00rootroot00000000000000--8<-- "CONTRIBUTING.md" mkdocstrings-python-handlers-1.8.0/docs/credits.md000066400000000000000000000002011454701760200222520ustar00rootroot00000000000000--- hide: - toc --- ```python exec="yes" --8<-- "scripts/gen_credits.py" ``` mkdocstrings-python-handlers-1.8.0/docs/css/000077500000000000000000000000001454701760200210725ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/docs/css/insiders.css000066400000000000000000000037311454701760200234300ustar00rootroot00000000000000@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.8.0/docs/css/material.css000066400000000000000000000026751454701760200234140ustar00rootroot00000000000000/* 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.8.0/docs/css/mkdocstrings.css000066400000000000000000000021171454701760200243140ustar00rootroot00000000000000/* 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: var(--md-typeset-a-color); } a.external:hover::after, a.autorefs-external:hover::after { background-color: var(--md-accent-fg-color); }mkdocstrings-python-handlers-1.8.0/docs/index.md000066400000000000000000000000231454701760200217260ustar00rootroot00000000000000--8<-- "README.md" mkdocstrings-python-handlers-1.8.0/docs/insiders/000077500000000000000000000000001454701760200221225ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/docs/insiders/changelog.md000066400000000000000000000032061454701760200243740ustar00rootroot00000000000000# 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.8.0/docs/insiders/goals.yml000066400000000000000000000011511454701760200237500ustar00rootroot00000000000000goals: 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 User Manual 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 mkdocstrings-python-handlers-1.8.0/docs/insiders/index.md000066400000000000000000000227131454701760200235600ustar00rootroot00000000000000# 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. ## 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-typing-deprecated", "https://mkdocstrings.github.io/griffe-typing-deprecated/", "insiders/goals.yml"), ] ``` ```python exec="1" session="insiders" --8<-- "scripts/insiders.py" print( f"""The moment you become a sponsor, you'll get **immediate 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) ``` ## 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 pawamoy@pm.me 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 pawamoy@pm.me, 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" 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 pawamoy@pm.me. ### 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.8.0/docs/insiders/installation.md000066400000000000000000000156211454701760200251520ustar00rootroot00000000000000--- 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). ### 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 pip (self-hosted) Self-hosting the Insiders package makes it possible to depend on *mkdocstrings-python* normally, while transparently downloading and installing the Insiders version locally. It means that you can specify your dependencies normally, and your contributors without access to Insiders will get the public version, while you get the Insiders version on your machine. WARNING: **Limitation** With this method, there is no way to force the installation of an Insiders version rather than a public version. If there is a public version that is more recent than your self-hosted Insiders version, the public version will take precedence. Remember to regularly update your self-hosted versions by uploading latest distributions. You can build the distributions for Insiders yourself, by cloning the repository and using [build] to build the distributions, or you can download them from our [GitHub Releases]. You can upload these distributions to a private PyPI-like registry ([Artifactory], [Google Cloud], [pypiserver], etc.) with [Twine]: [build]: https://pypi.org/project/build/ [Artifactory]: https://jfrog.com/help/r/jfrog-artifactory-documentation/pypi-repositories [Google Cloud]: https://cloud.google.com/artifact-registry/docs/python [pypiserver]: https://pypi.org/project/pypiserver/ [Github Releases]: https://github.com/pawamoy-insiders/mkdocstrings-python/releases [Twine]: https://pypi.org/project/twine/ ```bash # download distributions in ~/dists, then upload with: twine upload --repository-url https://your-private-index.com ~/dists/* ``` You might also need to provide a username and password/token to authenticate against the registry. Please check [Twine's documentation][twine docs]. [twine docs]: https://twine.readthedocs.io/en/stable/ You can then configure pip (or other tools) to look for packages into your package index. For example, with pip: ```bash pip config set global.extra-index-url https://your-private-index.com/simple ``` Note that the URL might differ depending on whether your are uploading a package (with Twine) or installing a package (with pip), and depending on the registry you are using (Artifactory, Google Cloud, etc.). Please check the documentation of your registry to learn how to configure your environment. **We kindly ask that you do not upload the distributions to public registries, as it is against our [Terms of use](index.md#terms).** >? TIP: **Full example with `pypiserver`** > In this example we use [pypiserver] to serve a local PyPI index. > > ```bash > pip install --user pypiserver > # or pipx install pypiserver > > # create a packages directory > mkdir -p ~/.local/pypiserver/packages > > # run the pypi server without authentication > pypi-server run -p 8080 -a . -P . ~/.local/pypiserver/packages & > ``` > > We can configure the credentials to access the server in [`~/.pypirc`][pypirc]: > > [pypirc]: https://packaging.python.org/en/latest/specifications/pypirc/ > > ```ini title=".pypirc" > [distutils] > index-servers = > local > > [local] > repository: http://localhost:8080 > username: > password: > ``` > > We then clone the Insiders repository, build distributions and upload them to our local server: > > ```bash > # clone the repository > git clone git@github.com:pawamoy-insiders/mkdocstrings-python > cd python > > # install build > pip install --user build > # or pipx install build > > # checkout latest tag > git checkout $(git describe --tags --abbrev=0) > > # build the distributions > pyproject-build > > # upload them to our local server > twine upload -r local dist/* --skip-existing > ``` > > Finally, we configure pip, and for example [PDM][pdm], to use our local index to find packages: > > ```bash > pip config set global.extra-index-url http://localhost:8080/simple > pdm config pypi.extra.url http://localhost:8080/simple > ``` > > [pdm]: https://pdm.fming.dev/latest/ > > Now when running `pip install mkdocstrings-python`, > or resolving dependencies with PDM, > both tools will look into our local index and find the Insiders version. > **Remember to update your local index regularly!** ### with git Of course, you can use *mkdocstrings-python Insiders* directly from `git`: ``` git clone git@github.com:pawamoy-insiders/mkdocstrings-python ``` When cloning from `git`, the package must be installed: ``` pip install -e 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.8.0/docs/js/000077500000000000000000000000001454701760200207165ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/docs/js/insiders.js000066400000000000000000000050621454701760200230770ustar00rootroot00000000000000function 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 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} `; } }); }); getJSON(dataURL + '/sponsorsBronze.json', function (err, sponsors) { const bronzeSponsors = document.getElementById("bronze-sponsors"); if (sponsors) { let html = ''; html += 'Bronze sponsors

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

' bronzeSponsors.innerHTML = html; } }); } mkdocstrings-python-handlers-1.8.0/docs/license.md000066400000000000000000000000441454701760200222440ustar00rootroot00000000000000# License ``` --8<-- "LICENSE" ``` mkdocstrings-python-handlers-1.8.0/docs/logo.png000066400000000000000000001627141454701760200217630ustar00rootroot00000000000000PNG  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.8.0/docs/schema.json000066400000000000000000000363251454701760200224460ustar00rootroot00000000000000{ "$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.8.0/docs/usage/000077500000000000000000000000001454701760200214065ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/docs/usage/configuration/000077500000000000000000000000001454701760200242555ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/docs/usage/configuration/docstrings.md000066400000000000000000000677551454701760200270020ustar00rootroot00000000000000# 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: >>> Class() # doctest: +NORMALIZE_WHITESPACE ok """ print("ok") ``` /// admonition | Preview type: preview //// tab | Ignore init summary, trim doctest flags

PrintOK

Class docstring.

__init__

Examples:

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

PrintOK

Class docstring.

__init__

Initialize the instance.

Examples:

```pycon >>> Class() # 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.8.0/docs/usage/configuration/general.md000066400000000000000000000117141454701760200262200ustar00rootroot00000000000000# 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.

//// /// mkdocstrings-python-handlers-1.8.0/docs/usage/configuration/headings.md000066400000000000000000000355341454701760200263730ustar00rootroot00000000000000# 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.8.0/docs/usage/configuration/members.md000066400000000000000000000406521454701760200262400ustar00rootroot00000000000000# 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`][]. 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. ```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).
//// /// mkdocstrings-python-handlers-1.8.0/docs/usage/configuration/signatures.md000066400000000000000000000267671454701760200270050ustar00rootroot00000000000000# 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.8.0/docs/usage/customization.md000066400000000000000000000264241454701760200246500ustar00rootroot00000000000000# Customization It is possible to customize the output of the generated documentation with CSS and/or by overriding templates. ## CSS classes 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-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). - `function`: 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). ## Style recommendations ### Material Here are some CSS rules for the [Material for MkDocs] theme: ```css --8<-- "docs/css/mkdocstrings.css" ``` ### 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.8.0/docs/usage/docstrings/000077500000000000000000000000001454701760200235655ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/docs/usage/docstrings/google.md000066400000000000000000000015061454701760200253650ustar00rootroot00000000000000# 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.8.0/docs/usage/docstrings/numpy.md000066400000000000000000000010011454701760200252470ustar00rootroot00000000000000# 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.8.0/docs/usage/docstrings/sphinx.md000066400000000000000000000004111454701760200254140ustar00rootroot00000000000000# 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.8.0/docs/usage/extensions.md000066400000000000000000000012101454701760200241210ustar00rootroot00000000000000# 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.8.0/docs/usage/index.md000066400000000000000000000232761454701760200230510ustar00rootroot00000000000000# 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. Enabling this option will tell the handler to resolve aliases recursively when they are made public through the [`__all__`][__all__] variable. 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.8.0/duties.py000066400000000000000000000222631454701760200212260ustar00rootroot00000000000000"""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 from duty.callables import black, coverage, lazy, mkdocs, mypy, pytest, ruff, safety 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("PDM_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) -> None: """Update the changelog in-place with latest commits. Parameters: ctx: The context instance (passed automatically). """ from git_changelog.cli import main as git_changelog ctx.run(git_changelog, args=[[]], 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! Parameters: ctx: The context instance (passed automatically). """ @duty def check_quality(ctx: Context) -> None: """Check the code quality. Parameters: ctx: The context instance (passed automatically). """ os.environ["MYPYPATH"] = "src" ctx.run( ruff.check(*PY_SRC_LIST, config="config/ruff.toml"), title=pyprefix("Checking code quality"), command=f"ruff check --config config/ruff.toml {PY_SRC}", ) @duty def check_dependencies(ctx: Context) -> None: """Check for vulnerabilities in dependencies. Parameters: ctx: The context instance (passed automatically). """ # retrieve the list of dependencies requirements = ctx.run( ["pdm", "export", "-f", "requirements", "--without-hashes"], title="Exporting dependencies as requirements", allow_overrides=False, ) ctx.run( safety.check(requirements), title="Checking dependencies", command="pdm export -f requirements --without-hashes | safety check --stdin", ) @duty def check_docs(ctx: Context) -> None: """Check if the documentation builds correctly. Parameters: ctx: The context instance (passed automatically). """ Path("htmlcov").mkdir(parents=True, exist_ok=True) Path("htmlcov/index.html").touch(exist_ok=True) with material_insiders(): ctx.run( mkdocs.build(strict=True, verbose=True), title=pyprefix("Building documentation"), command="mkdocs build -vs", ) @duty def check_types(ctx: Context) -> None: """Check that the code is correctly typed. Parameters: ctx: The context instance (passed automatically). """ os.environ["MYPYPATH"] = "src" ctx.run( mypy.run(*PY_SRC_LIST, config_file="config/mypy.ini"), title=pyprefix("Type-checking"), command=f"mypy --config-file config/mypy.ini {PY_SRC}", ) @duty def check_api(ctx: Context) -> None: """Check for API breaking changes. Parameters: ctx: The context instance (passed automatically). """ from griffe.cli import check as g_check griffe_check = lazy(g_check, name="griffe.check") ctx.run( griffe_check("mkdocstrings_handlers", search_paths=["src"], color=True), title="Checking for API breaking changes", command="griffe check -ssrc mkdocstrings_handlers", nofail=True, ) @duty(silent=True) def clean(ctx: Context) -> None: """Delete temporary files. Parameters: ctx: The context instance (passed automatically). """ ctx.run("rm -rf .coverage*") ctx.run("rm -rf .mypy_cache") ctx.run("rm -rf .pytest_cache") ctx.run("rm -rf tests/.pytest_cache") ctx.run("rm -rf build") ctx.run("rm -rf dist") ctx.run("rm -rf htmlcov") ctx.run("rm -rf pip-wheel-metadata") ctx.run("rm -rf site") ctx.run("find . -type d -name __pycache__ | xargs rm -rf") ctx.run("find . -name '*.rej' -delete") @duty def docs(ctx: Context, host: str = "127.0.0.1", port: int = 8000) -> None: """Serve the documentation (localhost:8000). Parameters: ctx: The context instance (passed automatically). host: The host to serve the docs from. port: The port to serve the docs on. """ with material_insiders(): ctx.run( mkdocs.serve(dev_addr=f"{host}:{port}"), title="Serving documentation", capture=False, ) @duty def docs_deploy(ctx: Context) -> None: """Deploy the documentation on GitHub pages. Parameters: ctx: The context instance (passed automatically). """ 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( 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. Parameters: ctx: The context instance (passed automatically). """ ctx.run( ruff.check(*PY_SRC_LIST, config="config/ruff.toml", fix_only=True, exit_zero=True), title="Auto-fixing code", ) ctx.run(black.run(*PY_SRC_LIST, config="config/black.toml"), title="Formatting code") @duty(post=["docs-deploy"]) def release(ctx: Context, version: str) -> None: """Release a new Python package. Parameters: ctx: The context instance (passed automatically). 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!)", ) 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) ctx.run("pdm build", title="Building dist/wheel", pty=PTY) ctx.run("twine upload --skip-existing dist/*", title="Publishing version", pty=PTY) @duty(silent=True, aliases=["coverage"]) def cov(ctx: Context) -> None: """Report coverage as text and HTML. Parameters: ctx: The context instance (passed automatically). """ ctx.run(coverage.combine, nofail=True) ctx.run(coverage.report(rcfile="config/coverage.ini"), capture=False) ctx.run(coverage.html(rcfile="config/coverage.ini")) @duty def test(ctx: Context, match: str = "") -> None: """Run the test suite. Parameters: ctx: The context instance (passed automatically). 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( pytest.run("-n", "auto", "tests", config_file="config/pytest.ini", select=match, color="yes"), title=pyprefix("Running tests"), command=f"pytest -c config/pytest.ini -n auto -k{match!r} --color=yes tests", ) @duty def vscode(ctx: Context) -> None: """Configure VSCode. This task will overwrite the following files, so make sure to back them up: - `.vscode/launch.json` - `.vscode/settings.json` - `.vscode/tasks.json` Parameters: ctx: The context instance (passed automatically). """ def update_config(filename: str) -> None: source_file = Path("config", "vscode", filename) target_file = Path(".vscode", filename) target_file.parent.mkdir(exist_ok=True) target_file.write_text(source_file.read_text()) for filename in ("launch.json", "settings.json", "tasks.json"): ctx.run(update_config, args=[filename], title=f"Update .vscode/{filename}") mkdocstrings-python-handlers-1.8.0/logo.png000077700000000000000000000000001454701760200234112docs/logo.pngustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/mkdocs.yml000066400000000000000000000116431454701760200213620ustar00rootroot00000000000000site_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.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 options: docstring_options: ignore_init_summary: true docstring_section_style: list filters: ["!^_"] heading_level: 1 inherited_members: true merge_init_into_class: 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.8.0/pyproject.toml000066400000000000000000000047441454701760200222770ustar00rootroot00000000000000[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 = "pawamoy@pm.me"}] 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", "Topic :: Documentation", "Topic :: Software Development", "Topic :: Software Development :: Documentation", "Topic :: Utilities", "Typing :: Typed", ] dependencies = [ "mkdocstrings>=0.20", "griffe>=0.37", ] [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"} plugins = [ "pdm-multirun", ] [tool.pdm.build] package-dir = "src" includes = ["src/mkdocstrings_handlers"] editable-backend = "editables" [tool.pdm.dev-dependencies] duty = ["duty>=0.10"] ci-quality = ["mkdocstrings-python[duty,docs,quality,typing,security]"] ci-tests = ["mkdocstrings-python[duty,docs,tests]"] docs = [ "black>=23.9", "markdown-callouts>=0.3", "markdown-exec>=1.7", "mkdocs>=1.5", "mkdocs-coverage>=1.0", "mkdocs-gen-files>=0.5", "mkdocs-git-committers-plugin-2>=1.2", "mkdocs-literate-nav>=0.6", "mkdocs-material>=9.4", "mkdocs-minify-plugin>=0.7", "tomli>=2.0; python_version < '3.11'", ] maintain = [ "black>=23.9", "blacken-docs>=1.16", "git-changelog>=2.3", ] quality = [ "ruff>=0.0", ] tests = [ "pytest>=7.4", "pytest-cov>=4.1", "pytest-randomly>=3.15", "pytest-xdist>=3.3", ] typing = [ "mypy>=1.5", "types-markdown>=3.5", "types-pyyaml>=6.0", ] security = [ "safety>=2.3", ] mkdocstrings-python-handlers-1.8.0/scripts/000077500000000000000000000000001454701760200210415ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/scripts/gen_credits.py000066400000000000000000000114701454701760200237040ustar00rootroot00000000000000"""Script to generate the project's credits.""" from __future__ import annotations import os import re import sys from importlib.metadata import PackageNotFoundError, metadata from itertools import chain from pathlib import Path from textwrap import dedent from typing import Mapping, cast from jinja2 import StrictUndefined from jinja2.sandbox import SandboxedEnvironment # 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"] pdm = pyproject["tool"]["pdm"] with project_dir.joinpath("pdm.lock").open("rb") as lock_file: lock_data = tomllib.load(lock_file) lock_pkgs = {pkg["name"].lower(): pkg for pkg in lock_data["package"]} project_name = project["name"] regex = re.compile(r"(?P[\w.-]+)(?P.*)$") def _get_license(pkg_name: str) -> str: try: data = metadata(pkg_name) except PackageNotFoundError: return "?" license_name = cast(dict, data).get("License", "").strip() multiple_lines = bool(license_name.count("\n")) # TODO: Remove author logic once all my packages licenses are fixed. author = "" if multiple_lines or not license_name or license_name == "UNKNOWN": for header, value in cast(dict, data).items(): if header == "Classifier" and value.startswith("License ::"): license_name = value.rsplit("::", 1)[1].strip() elif header == "Author-email": author = value if license_name == "Other/Proprietary License" and "pawamoy" in author: license_name = "ISC" return license_name or "?" def _get_deps(base_deps: Mapping[str, Mapping[str, str]]) -> dict[str, dict[str, str]]: deps = {} for dep in base_deps: parsed = regex.match(dep).groupdict() # type: ignore[union-attr] dep_name = parsed["dist"].lower() if dep_name not in lock_pkgs: continue deps[dep_name] = {"license": _get_license(dep_name), **parsed, **lock_pkgs[dep_name]} again = True while again: again = False for pkg_name in lock_pkgs: if pkg_name in deps: for pkg_dependency in lock_pkgs[pkg_name].get("dependencies", []): parsed = regex.match(pkg_dependency).groupdict() # type: ignore[union-attr] dep_name = parsed["dist"].lower() if dep_name in lock_pkgs and dep_name not in deps and dep_name != project["name"]: deps[dep_name] = {"license": _get_license(dep_name), **parsed, **lock_pkgs[dep_name]} again = True return deps def _render_credits() -> str: dev_dependencies = _get_deps(chain(*pdm.get("dev-dependencies", {}).values())) # type: ignore[arg-type] prod_dependencies = _get_deps( chain( # type: ignore[arg-type] project.get("dependencies", []), chain(*project.get("optional-dependencies", {}).values()), ), ) template_data = { "project_name": project_name, "prod_dependencies": sorted(prod_dependencies.values(), key=lambda dep: dep["name"]), "dev_dependencies": sorted(dev_dependencies.values(), key=lambda dep: dep["name"]), "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/) | [`pdm`](https://pdm.fming.dev/) | [`copier-pdm`](https://github.com/pawamoy/copier-pdm) {% macro dep_line(dep) -%} [`{{ dep.name }}`](https://pypi.org/project/{{ dep.name }}/) | {{ dep.summary }} | {{ ("`" ~ dep.spec ~ "`") if dep.spec else "" }} | `{{ dep.version }}` | {{ dep.license }} {%- endmacro %} ### Runtime dependencies Project | Summary | Version (accepted) | Version (last resolved) | License ------- | ------- | ------------------ | ----------------------- | ------- {% for dep in prod_dependencies -%} {{ dep_line(dep) }} {% endfor %} ### Development dependencies Project | Summary | Version (accepted) | Version (last resolved) | License ------- | ------- | ------------------ | ----------------------- | ------- {% for dep in dev_dependencies -%} {{ dep_line(dep) }} {% endfor %} {% 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.8.0/scripts/gen_ref_nav.py000066400000000000000000000021631454701760200236660ustar00rootroot00000000000000"""Generate the code reference pages and navigation.""" from pathlib import Path import mkdocs_gen_files nav = mkdocs_gen_files.Nav() mod_symbol = '' src = Path(__file__).parent.parent / "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"::: {ident}") mkdocs_gen_files.set_edit_path(full_doc_path, ".." / path) with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file: nav_file.writelines(nav.build_literate_nav()) mkdocstrings-python-handlers-1.8.0/scripts/insiders.py000066400000000000000000000145731454701760200232450ustar00rootroot00000000000000"""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") for feature in self.features: feature.render(rel_base) print("") 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) 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.8.0/scripts/setup.sh000077500000000000000000000006021454701760200225360ustar00rootroot00000000000000#!/usr/bin/env bash set -e if ! command -v pdm &>/dev/null; then if ! command -v pipx &>/dev/null; then python3 -m pip install --user pipx fi pipx install pdm fi if ! pdm self list 2>/dev/null | grep -q pdm-multirun; then pdm install --plugins fi if [ -n "${PDM_MULTIRUN_VERSIONS}" ]; then pdm multirun -v pdm install -G:all else pdm install -G:all fi mkdocstrings-python-handlers-1.8.0/src/000077500000000000000000000000001454701760200201415ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/000077500000000000000000000000001454701760200245305ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/py.typed000066400000000000000000000000001454701760200262150ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/000077500000000000000000000000001454701760200260515ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/__init__.py000066400000000000000000000005061454701760200301630ustar00rootroot00000000000000"""This package implements a handler for the Python language.""" from mkdocstrings_handlers.python.handler import get_handler __all__ = ["get_handler"] # TODO: CSS classes everywhere in templates # TODO: name normalization (filenames, Jinja2 variables, HTML tags, CSS classes) # TODO: Jinja2 blocks everywhere in templates mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/debug.py000066400000000000000000000053141454701760200275140ustar00rootroot00000000000000"""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.""" 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, 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}") 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.8.0/src/mkdocstrings_handlers/python/handler.py000066400000000000000000000540131454701760200300430ustar00rootroot00000000000000"""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 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.""" 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] = { "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, "unwrap_annotated": False, } """Default handler configuration. Attributes: General options: 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. 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 = False, **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) self._config_file_path = config_file_path self._load_external_modules = load_external_modules paths = paths or [] glob_base_dir = os.path.dirname(os.path.abspath(config_file_path)) if config_file_path else "." with chdir(glob_base_dir): resolved_globs = [glob.glob(path) for path in paths] paths = [path for glob_list in resolved_globs for path in glob_list] if not paths and config_file_path: paths.append(os.path.dirname(config_file_path)) search_paths = [path for path in sys.path if path] # eliminate empty path for path in reversed(paths): if not os.path.isabs(path) and config_file_path: path = os.path.abspath(os.path.join(os.path.dirname(config_file_path), path)) # noqa: PLW2901 if path not in search_paths: search_paths.insert(0, path) self._paths = search_paths self._modules_collection: ModulesCollection = ModulesCollection() self._lines_collection: LinesCollection = LinesCollection() self._locale = locale @classmethod def load_inventory( cls, in_file: BinaryIO, url: str, base_url: str | None = None, domains: list[str] | None = None, **kwargs: Any, # noqa: ARG003 ) -> Iterator[tuple[str, str]]: """Yield items and their URLs from an inventory file streamed from `in_file`. This implements mkdocstrings' `load_inventory` "protocol" (see [`mkdocstrings.plugin`][mkdocstrings.plugin]). Arguments: in_file: The binary file-like object to read the inventory from. url: The URL that this file is being streamed from (used to guess `base_url`). base_url: The URL that this inventory's sub-paths are relative to. domains: A list of domain strings to filter the inventory by, when not passed, "py" will be used. **kwargs: Ignore additional arguments passed from the config. Yields: Tuples of (item identifier, item URL). """ domains = domains or ["py"] if base_url is None: base_url = posixpath.dirname(url) for item in Inventory.parse_sphinx(in_file, domain_filter=domains).values(): yield item.name, posixpath.join(base_url, item.uri) def collect(self, identifier: str, config: Mapping[str, Any]) -> CollectorItem: # noqa: D102 module_name = identifier.split(".", 1)[0] unknown_module = module_name not in self._modules_collection if config.get("fallback", False) and unknown_module: raise CollectionError("Not loading additional modules during fallback") final_config = ChainMap(config, self.default_config) # type: ignore[arg-type] parser_name = final_config["docstring_style"] parser_options = final_config["docstring_options"] parser = parser_name and Parser(parser_name) if unknown_module: extensions = self.normalize_extension_paths(final_config.get("extensions", [])) loader = GriffeLoader( extensions=load_extensions(extensions), search_paths=self._paths, docstring_parser=parser, docstring_options=parser_options, modules_collection=self._modules_collection, lines_collection=self._lines_collection, allow_inspection=final_config["allow_inspection"], ) try: for pre_loaded_module in final_config.get("preload_modules") or []: if pre_loaded_module not in self._modules_collection: loader.load(pre_loaded_module) loader.load(module_name) except ImportError as error: raise CollectionError(str(error)) from error unresolved, iterations = loader.resolve_aliases( implicit=False, external=self._load_external_modules, ) if unresolved: logger.debug(f"{len(unresolved)} aliases were still unresolved after {iterations} iterations") logger.debug(f"Unresolved aliases: {', '.join(sorted(unresolved))}") try: doc_object = self._modules_collection[identifier] except KeyError as error: raise CollectionError(f"{identifier} could not be found") from error except AliasResolutionError as error: raise CollectionError(str(error)) from error if not unknown_module: with suppress(AliasResolutionError): if doc_object.docstring is not None: doc_object.docstring.parser = parser doc_object.docstring.parser_options = parser_options return doc_object def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str: # noqa: D102 (ignore missing docstring) final_config = ChainMap(config, self.default_config) # type: ignore[arg-type] template_name = rendering.do_get_template(data) template = self.env.get_template(template_name) # Heading level is a "state" variable, that will change at each step # of the rendering recursion. Therefore, it's easier to use it as a plain value # than as an item in a dictionary. heading_level = final_config["heading_level"] try: final_config["members_order"] = rendering.Order(final_config["members_order"]) except ValueError as error: choices = "', '".join(item.value for item in rendering.Order) raise PluginError( f"Unknown members_order '{final_config['members_order']}', choose between '{choices}'.", ) from error if final_config["filters"]: final_config["filters"] = [ (re.compile(filtr.lstrip("!")), filtr.startswith("!")) for filtr in final_config["filters"] ] summary = final_config["summary"] if summary is True: final_config["summary"] = { "attributes": True, "functions": True, "classes": True, "modules": True, } elif summary is False: final_config["summary"] = { "attributes": False, "functions": False, "classes": False, "modules": False, } else: final_config["summary"] = { "attributes": summary.get("attributes", False), "functions": summary.get("functions", False), "classes": summary.get("classes", False), "modules": summary.get("modules", False), } return template.render( **{ "config": final_config, data.kind.value: data, "heading_level": heading_level, "root": True, "locale": self._locale, }, ) def update_env(self, md: Markdown, config: dict) -> None: # noqa: D102 (ignore missing docstring) super().update_env(md, config) self.env.trim_blocks = True self.env.lstrip_blocks = True self.env.keep_trailing_newline = False self.env.filters["split_path"] = rendering.do_split_path self.env.filters["crossref"] = rendering.do_crossref self.env.filters["multi_crossref"] = rendering.do_multi_crossref self.env.filters["order_members"] = rendering.do_order_members self.env.filters["format_code"] = rendering.do_format_code self.env.filters["format_signature"] = rendering.do_format_signature self.env.filters["format_attribute"] = rendering.do_format_attribute self.env.filters["filter_objects"] = rendering.do_filter_objects self.env.filters["stash_crossref"] = lambda ref, length: ref self.env.filters["get_template"] = rendering.do_get_template self.env.filters["as_attributes_section"] = rendering.do_as_attributes_section self.env.filters["as_functions_section"] = rendering.do_as_functions_section self.env.filters["as_classes_section"] = rendering.do_as_classes_section self.env.filters["as_modules_section"] = rendering.do_as_modules_section self.env.tests["existing_template"] = lambda template_name: template_name in self.env.list_templates() def get_anchors(self, data: CollectorItem) -> tuple[str, ...]: # noqa: D102 (ignore missing docstring) anchors = [data.path] try: if data.canonical_path != data.path: anchors.append(data.canonical_path) for anchor in data.aliases: if anchor not in anchors: anchors.append(anchor) except AliasResolutionError: return tuple(anchors) return tuple(anchors) def normalize_extension_paths(self, extensions: Sequence) -> Sequence: """Resolve extension paths relative to config file.""" if self._config_file_path is None: return extensions base_path = os.path.dirname(self._config_file_path) normalized = [] for ext in extensions: if isinstance(ext, dict): pth, options = next(iter(ext.items())) pth = str(pth) else: pth = str(ext) options = None if pth.endswith(".py") or ".py:" in pth or "/" in pth or "\\" in pth: # noqa: SIM102 # This is a sytem path. Normalize it. if not os.path.isabs(pth): # Make path absolute relative to config file path. pth = os.path.normpath(os.path.join(base_path, pth)) if options is not None: normalized.append({pth: options}) else: normalized.append(pth) return normalized def get_handler( *, theme: str, custom_templates: str | None = None, config_file_path: str | None = None, paths: list[str] | None = None, locale: str = "en", load_external_modules: bool = False, **config: Any, # noqa: ARG001 ) -> PythonHandler: """Simply return an instance of `PythonHandler`. Arguments: theme: The theme to use when rendering contents. custom_templates: Directory containing 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. **config: Configuration passed to the handler. Returns: An instance of `PythonHandler`. """ return PythonHandler( handler="python", theme=theme, custom_templates=custom_templates, config_file_path=config_file_path, paths=paths, locale=locale, load_external_modules=load_external_modules, ) mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/rendering.py000066400000000000000000000372561454701760200304150ustar00rootroot00000000000000"""This module implements rendering utilities.""" from __future__ import annotations import enum import random import re import string import sys import warnings from functools import lru_cache, partial from typing import TYPE_CHECKING, Any, Callable, Match, Pattern, Sequence from griffe.docstrings.dataclasses import ( DocstringSectionAttributes, DocstringSectionClasses, DocstringSectionFunctions, DocstringSectionModules, ) from jinja2 import pass_context from markupsafe import Markup from mkdocstrings.loggers import get_logger if TYPE_CHECKING: from griffe.dataclasses import Alias, Attribute, Class, Function, Module, Object from jinja2.runtime import Context from mkdocstrings.handlers.base import CollectorItem logger = get_logger(__name__) class Order(enum.Enum): """Enumeration for the possible members ordering.""" alphabetical = "alphabetical" """Alphabetical order.""" source = "source" """Source code order.""" def _sort_key_alphabetical(item: CollectorItem) -> Any: # chr(sys.maxunicode) is a string that contains the final unicode # character, so if 'name' isn't found on the object, the item will go to # the end of the list. return item.name or chr(sys.maxunicode) def _sort_key_source(item: CollectorItem) -> Any: # if 'lineno' is none, the item will go to the start of the list. if item.is_alias: return item.alias_lineno if item.alias_lineno is not None else -1 return item.lineno if item.lineno is not None else -1 order_map = { Order.alphabetical: _sort_key_alphabetical, Order.source: _sort_key_source, } def do_format_code(code: str, line_length: int) -> str: """Format code using Black. Parameters: code: The code to format. line_length: The line length to give to Black. Returns: The same code, formatted. """ code = code.strip() if len(code) < line_length: return code formatter = _get_black_formatter() return formatter(code, line_length) _stash_key_alphabet = string.ascii_letters + string.digits def _gen_key(length: int) -> str: return "_" + "".join(random.choice(_stash_key_alphabet) for _ in range(max(1, length - 1))) # noqa: S311 def _gen_stash_key(stash: dict[str, str], length: int) -> str: key = _gen_key(length) while key in stash: key = _gen_key(length) return key def _stash_crossref(stash: dict[str, str], crossref: str, *, length: int) -> str: key = _gen_stash_key(stash, length) stash[key] = crossref return key def _format_signature(name: Markup, signature: str, line_length: int) -> str: name = str(name).strip() # type: ignore[assignment] signature = signature.strip() if len(name + signature) < line_length: return name + signature # Black cannot format names with dots, so we replace # the whole name with a string of equal length name_length = len(name) formatter = _get_black_formatter() formatable = f"def {'x' * name_length}{signature}: pass" formatted = formatter(formatable, line_length) # We put back the original name # and remove starting `def ` and trailing `: pass` return name + formatted[4:-5].strip()[name_length:-1] @pass_context def do_format_signature( context: Context, callable_path: Markup, function: Function, line_length: int, *, annotations: bool | None = None, crossrefs: bool = False, ) -> str: """Format a signature using Black. Parameters: context: Jinja context, passed automatically. callable_path: The path of the callable we render the signature of. function: The function we render the signature of. line_length: The line length to give to Black. annotations: Whether to show type annotations. crossrefs: Whether to cross-reference types in the signature. Returns: The same code, formatted. """ env = context.environment template = env.get_template("signature.html") config_annotations = context.parent["config"]["show_signature_annotations"] old_stash_ref_filter = env.filters["stash_crossref"] stash: dict[str, str] = {} if (annotations or config_annotations) and crossrefs: env.filters["stash_crossref"] = partial(_stash_crossref, stash) if annotations is None: new_context = context.parent else: new_context = dict(context.parent) new_context["config"] = dict(new_context["config"]) new_context["config"]["show_signature_annotations"] = annotations try: signature = template.render(new_context, function=function, signature=True) finally: env.filters["stash_crossref"] = old_stash_ref_filter signature = _format_signature(callable_path, signature, line_length) signature = str( env.filters["highlight"]( Markup.escape(signature), language="python", inline=False, classes=["doc-signature"], ), ) if stash: for key, value in stash.items(): signature = re.sub(rf"\b{key}\b", value, signature) return signature @pass_context def do_format_attribute( context: Context, attribute_path: Markup, attribute: Attribute, line_length: int, *, crossrefs: bool = False, ) -> str: """Format an attribute using Black. Parameters: context: Jinja context, passed automatically. attribute_path: The path of the callable we render the signature of. attribute: The attribute we render the signature of. line_length: The line length to give to Black. crossrefs: Whether to cross-reference types in the signature. Returns: The same code, formatted. """ env = context.environment template = env.get_template("expression.html") annotations = context.parent["config"]["show_signature_annotations"] separate_signature = context.parent["config"]["separate_signature"] old_stash_ref_filter = env.filters["stash_crossref"] stash: dict[str, str] = {} if separate_signature and crossrefs: env.filters["stash_crossref"] = partial(_stash_crossref, stash) try: signature = str(attribute_path).strip() if annotations and attribute.annotation: annotation = template.render(context.parent, expression=attribute.annotation, signature=True) signature += f": {annotation}" if attribute.value: value = template.render(context.parent, expression=attribute.value, signature=True) signature += f" = {value}" finally: env.filters["stash_crossref"] = old_stash_ref_filter signature = do_format_code(signature, line_length) signature = str( env.filters["highlight"]( Markup.escape(signature), language="python", inline=False, classes=["doc-signature"], ), ) if stash: for key, value in stash.items(): signature = re.sub(rf"\b{key}\b", value, signature) return signature def do_order_members( members: Sequence[Object | Alias], order: Order, members_list: bool | list[str] | None, ) -> Sequence[Object | Alias]: """Order members given an ordering method. Parameters: members: The members to order. order: The ordering method. members_list: An optional member list (manual ordering). Returns: The same members, ordered. """ if isinstance(members_list, list) and members_list: sorted_members = [] members_dict = {member.name: member for member in members} for name in members_list: if name in members_dict: sorted_members.append(members_dict[name]) return sorted_members return sorted(members, key=order_map[order]) @lru_cache def _warn_crossref() -> None: warnings.warn( "The `crossref` filter is deprecated and will be removed in a future version", DeprecationWarning, stacklevel=1, ) def do_crossref(path: str, *, brief: bool = True) -> Markup: """Deprecated. Filter to create cross-references. Parameters: path: The path to link to. brief: Show only the last part of the path, add full path as hover. Returns: Markup text. """ _warn_crossref() full_path = path if brief: path = full_path.split(".")[-1] return Markup("{path}").format(full_path=full_path, path=path) @lru_cache def _warn_multi_crossref() -> None: warnings.warn( "The `multi_crossref` filter is deprecated and will be removed in a future version", DeprecationWarning, stacklevel=1, ) def do_multi_crossref(text: str, *, code: bool = True) -> Markup: """Deprecated. Filter to create cross-references. Parameters: text: The text to scan. code: Whether to wrap the result in a code tag. Returns: Markup text. """ _warn_multi_crossref() group_number = 0 variables = {} def repl(match: Match) -> str: nonlocal group_number group_number += 1 path = match.group() path_var = f"path{group_number}" variables[path_var] = path return f"{{{path_var}}}" text = re.sub(r"([\w.]+)", repl, text) if code: text = f"{text}" return Markup(text).format(**variables) def do_split_path(path: str, full_path: str) -> list[tuple[str, str]]: """Split object paths for building cross-references. Parameters: path: The path to split. Returns: A list of pairs (title, full path). """ if "." not in path: return [(path, full_path)] pairs = [] full_path = "" for part in path.split("."): if full_path: full_path += f".{part}" else: full_path = part pairs.append((part, full_path)) return pairs def _keep_object(name: str, filters: Sequence[tuple[Pattern, bool]]) -> bool: keep = None rules = set() for regex, exclude in filters: rules.add(exclude) if regex.search(name): keep = not exclude if keep is None: if rules == {False}: # only included stuff, no match = reject return False # only excluded stuff, or included and excluded stuff, no match = keep return True return keep def do_filter_objects( objects_dictionary: dict[str, Object | Alias], *, filters: Sequence[tuple[Pattern, bool]] | None = None, members_list: bool | list[str] | None = None, inherited_members: bool | list[str] = False, keep_no_docstrings: bool = True, ) -> list[Object | Alias]: """Filter a dictionary of objects based on their docstrings. Parameters: objects_dictionary: The dictionary of objects. filters: Filters to apply, based on members' names. Each element is a tuple: a pattern, and a boolean indicating whether to reject the object if the pattern matches. members_list: An optional, explicit list of members to keep. When given and empty, return an empty list. When given and not empty, ignore filters and docstrings presence/absence. inherited_members: Whether to keep inherited members or exclude them. keep_no_docstrings: Whether to keep objects with no/empty docstrings (recursive check). Returns: A list of objects. """ inherited_members_specified = False if inherited_members is True: # Include all inherited members. objects = list(objects_dictionary.values()) elif inherited_members is False: # Include no inherited members. objects = [obj for obj in objects_dictionary.values() if not obj.inherited] else: # Include specific inherited members. inherited_members_specified = True objects = [ obj for obj in objects_dictionary.values() if not obj.inherited or obj.name in set(inherited_members) ] if members_list is True: # Return all pre-selected members. return objects if members_list is False or members_list == []: # Return selected inherited members, if any. return [obj for obj in objects if obj.inherited] if members_list is not None: # Return selected members (keeping any pre-selected inherited members). return [ obj for obj in objects if obj.name in set(members_list) or (inherited_members_specified and obj.inherited) ] # Use filters and docstrings. if filters: objects = [ obj for obj in objects if _keep_object(obj.name, filters) or (inherited_members_specified and obj.inherited) ] if keep_no_docstrings: return objects return [obj for obj in objects if obj.has_docstrings or (inherited_members_specified and obj.inherited)] @lru_cache(maxsize=1) def _get_black_formatter() -> Callable[[str, int], str]: try: from black import InvalidInput, Mode, format_str except ModuleNotFoundError: logger.info("Formatting signatures requires Black to be installed.") return lambda text, _: text def formatter(code: str, line_length: int) -> str: mode = Mode(line_length=line_length) try: return format_str(code, mode=mode) except InvalidInput: return code return formatter def do_get_template(obj: Object) -> str: """Get the template name used to render an object. Parameters: obj: A Griffe object. Returns: A template name. """ extra_data = getattr(obj, "extra", {}).get("mkdocstrings", {}) return extra_data.get("template", "") or f"{obj.kind.value}.html" @pass_context def do_as_attributes_section( context: Context, # noqa: ARG001 attributes: Sequence[Attribute], # noqa: ARG001 *, check_public: bool = True, # noqa: ARG001 ) -> DocstringSectionAttributes: """Build an attributes section from a list of attributes. Parameters: attributes: The attributes to build the section from. check_public: Whether to check if the attribute is public. Returns: An attributes docstring section. """ return DocstringSectionAttributes([]) @pass_context def do_as_functions_section( context: Context, # noqa: ARG001 functions: Sequence[Function], # noqa: ARG001 *, check_public: bool = True, # noqa: ARG001 ) -> DocstringSectionFunctions: """Build a functions section from a list of functions. Parameters: functions: The functions to build the section from. check_public: Whether to check if the function is public. Returns: A functions docstring section. """ return DocstringSectionFunctions([]) @pass_context def do_as_classes_section( context: Context, # noqa: ARG001 classes: Sequence[Class], # noqa: ARG001 *, check_public: bool = True, # noqa: ARG001 ) -> DocstringSectionClasses: """Build a classes section from a list of classes. Parameters: classes: The classes to build the section from. check_public: Whether to check if the class is public. Returns: A classes docstring section. """ return DocstringSectionClasses([]) @pass_context def do_as_modules_section( context: Context, # noqa: ARG001 modules: Sequence[Module], # noqa: ARG001 *, check_public: bool = True, # noqa: ARG001 ) -> DocstringSectionModules: """Build a modules section from a list of modules. Parameters: modules: The modules to build the section from. check_public: Whether to check if the module is public. Returns: A modules docstring section. """ return DocstringSectionModules([]) mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/000077500000000000000000000000001454701760200300475ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/000077500000000000000000000000001454701760200316455ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/000077500000000000000000000000001454701760200327165ustar00rootroot00000000000000attribute.html000066400000000000000000000056001454701760200355310ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base{{ log.debug("Rendering " + attribute.path) }}
{% with obj = attribute, html_id = attribute.path %} {% if root %} {% set show_full_path = config.show_root_full_path %} {% set root_members = True %} {% elif root_members %} {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %} {% set root_members = False %} {% else %} {% set show_full_path = config.show_object_full_path %} {% endif %} {% set attribute_name = attribute.path if show_full_path else attribute.name %} {% if not root or config.show_root_heading %} {% filter heading( heading_level, role="data" if attribute.parent.kind.value == "module" else "attr", id=html_id, class="doc doc-heading", toc_label=(' '|safe if config.show_symbol_type_toc else '') + attribute.name, ) %} {% block heading scoped %} {% if config.show_symbol_type_heading %}{% endif %} {% if config.separate_signature %} {{ attribute_name }} {% else %} {%+ filter highlight(language="python", inline=True) %} {{ attribute_name }}{% if attribute.annotation %}: {{ attribute.annotation }}{% endif %} {% if attribute.value %} = {{ attribute.value }}{% endif %} {% endfilter %} {% endif %} {% endblock heading %} {% block labels scoped %} {% with labels = attribute.labels %} {% include "labels.html" with context %} {% endwith %} {% endblock labels %} {% endfilter %} {% block signature scoped %} {% if config.separate_signature %} {% filter format_attribute(attribute, config.line_length, crossrefs=config.signature_crossrefs) %} {{ attribute.name }} {% endfilter %} {% endif %} {% endblock signature %} {% else %} {% if config.show_root_toc_entry %} {% filter heading(heading_level, role="data" if attribute.parent.kind.value == "module" else "attr", id=html_id, toc_label=(' '|safe if config.show_symbol_type_toc else '') + attribute.name, hidden=True, ) %} {% endfilter %} {% endif %} {% set heading_level = heading_level - 1 %} {% endif %}
{% block contents scoped %} {% block docstring scoped %} {% with docstring_sections = attribute.docstring.parsed %} {% include "docstring.html" with context %} {% endwith %} {% endblock docstring %} {% endblock contents %}
{% endwith %}
children.html000066400000000000000000000131151454701760200353160ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base{% if obj.members %} {{ log.debug("Rendering children of " + obj.path) }}
{% if root_members %} {% set members_list = config.members %} {% else %} {% set members_list = none %} {% endif %} {% if config.group_by_category %} {% with %} {% if config.show_category_heading %} {% set extra_level = 1 %} {% else %} {% set extra_level = 0 %} {% endif %} {% with attributes = obj.attributes|filter_objects( filters=config.filters, members_list=members_list, inherited_members=config.inherited_members, keep_no_docstrings=config.show_if_no_docstring, ) %} {% if attributes %} {% if config.show_category_heading %} {% filter heading(heading_level, id=html_id ~ "-attributes") %}Attributes{% endfilter %} {% endif %} {% with heading_level = heading_level + extra_level %} {% for attribute in attributes|order_members(config.members_order, members_list) %} {% if members_list is not none or attribute.is_public(check_name=False) %} {% include attribute|get_template with context %} {% endif %} {% endfor %} {% endwith %} {% endif %} {% endwith %} {% with classes = obj.classes|filter_objects( filters=config.filters, members_list=members_list, inherited_members=config.inherited_members, keep_no_docstrings=config.show_if_no_docstring, ) %} {% if classes %} {% if config.show_category_heading %} {% filter heading(heading_level, id=html_id ~ "-classes") %}Classes{% endfilter %} {% endif %} {% with heading_level = heading_level + extra_level %} {% for class in classes|order_members(config.members_order, members_list) %} {% if members_list is not none or class.is_public(check_name=False) %} {% include class|get_template with context %} {% endif %} {% endfor %} {% endwith %} {% endif %} {% endwith %} {% with functions = obj.functions|filter_objects( filters=config.filters, members_list=members_list, inherited_members=config.inherited_members, keep_no_docstrings=config.show_if_no_docstring, ) %} {% if functions %} {% if config.show_category_heading %} {% filter heading(heading_level, id=html_id ~ "-functions") %}Functions{% endfilter %} {% endif %} {% with heading_level = heading_level + extra_level %} {% for function in functions|order_members(config.members_order, members_list) %} {% if not (obj.kind.value == "class" and function.name == "__init__" and config.merge_init_into_class) %} {% if members_list is not none or function.is_public(check_name=False) %} {% include function|get_template with context %} {% endif %} {% endif %} {% endfor %} {% endwith %} {% endif %} {% endwith %} {% if config.show_submodules %} {% with modules = obj.modules|filter_objects( filters=config.filters, members_list=members_list, inherited_members=config.inherited_members, keep_no_docstrings=config.show_if_no_docstring, ) %} {% if modules %} {% if config.show_category_heading %} {% filter heading(heading_level, id=html_id ~ "-modules") %}Modules{% endfilter %} {% endif %} {% with heading_level = heading_level + extra_level %} {% for module in modules|order_members(config.members_order.alphabetical, members_list) %} {% if members_list is not none or module.is_public(check_name=False) %} {% include module|get_template with context %} {% endif %} {% endfor %} {% endwith %} {% endif %} {% endwith %} {% endif %} {% endwith %} {% else %} {% for child in obj.all_members |filter_objects( filters=config.filters, members_list=members_list, inherited_members=config.inherited_members, keep_no_docstrings=config.show_if_no_docstring, ) |order_members(config.members_order, members_list) %} {% if not (obj.is_class and child.name == "__init__" and config.merge_init_into_class) %} {% if members_list is not none or child.is_public(check_name=False) %} {% if child.is_attribute %} {% with attribute = child %} {% include attribute|get_template with context %} {% endwith %} {% elif child.is_class %} {% with class = child %} {% include class|get_template with context %} {% endwith %} {% elif child.is_function %} {% with function = child %} {% include function|get_template with context %} {% endwith %} {% elif child.is_module and config.show_submodules %} {% with module = child %} {% include module|get_template with context %} {% endwith %} {% endif %} {% endif %} {% endif %} {% endfor %} {% endif %}
{% endif %} class.html000066400000000000000000000124451454701760200346400ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base{{ log.debug("Rendering " + class.path) }}
{% with obj = class, html_id = class.path %} {% if root %} {% set show_full_path = config.show_root_full_path %} {% set root_members = True %} {% elif root_members %} {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %} {% set root_members = False %} {% else %} {% set show_full_path = config.show_object_full_path %} {% endif %} {% set class_name = class.path if show_full_path else class.name %} {% if not root or config.show_root_heading %} {% filter heading( heading_level, role="class", id=html_id, class="doc doc-heading", toc_label=(' '|safe if config.show_symbol_type_toc else '') + class.name, ) %} {% block heading scoped %} {% if config.show_symbol_type_heading %}{% endif %} {% if config.separate_signature %} {{ class_name }} {% elif config.merge_init_into_class and "__init__" in class.all_members %} {% with function = class.all_members["__init__"] %} {%+ filter highlight(language="python", inline=True) %} {{ class_name }}{% include "signature.html" with context %} {% endfilter %} {% endwith %} {% else %} {{ class_name }} {% endif %} {% endblock heading %} {% block labels scoped %} {% with labels = class.labels %} {% include "labels.html" with context %} {% endwith %} {% endblock labels %} {% endfilter %} {% block signature scoped %} {% if config.separate_signature and config.merge_init_into_class %} {% if "__init__" in class.all_members %} {% with function = class.all_members["__init__"] %} {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %} {{ class.name }} {% endfilter %} {% endwith %} {% endif %} {% endif %} {% endblock signature %} {% else %} {% if config.show_root_toc_entry %} {% filter heading(heading_level, role="class", id=html_id, toc_label=(' '|safe if config.show_symbol_type_toc else '') + class.name, hidden=True, ) %} {% endfilter %} {% endif %} {% set heading_level = heading_level - 1 %} {% endif %}
{% block contents scoped %} {% block bases scoped %} {% if config.show_bases and class.bases %}

Bases: {% for expression in class.bases -%} {% include "expression.html" with context %}{% if not loop.last %}, {% endif %} {% endfor -%}

{% endif %} {% endblock bases %} {% block docstring scoped %} {% with docstring_sections = class.docstring.parsed %} {% include "docstring.html" with context %} {% endwith %} {% if config.merge_init_into_class %} {% if "__init__" in class.all_members and class.all_members["__init__"].has_docstring %} {% with docstring_sections = class.all_members["__init__"].docstring.parsed %} {% include "docstring.html" with context %} {% endwith %} {% endif %} {% endif %} {% endblock docstring %} {% block source scoped %} {% if config.show_source %} {% if config.merge_init_into_class %} {% if "__init__" in class.all_members and class.all_members["__init__"].source %} {% with init = class.all_members["__init__"] %}
Source code in {%- if init.relative_filepath.is_absolute() -%} {{ init.relative_package_filepath }} {%- else -%} {{ init.relative_filepath }} {%- endif -%} {{ init.source|highlight(language="python", linestart=init.lineno, linenums=True) }}
{% endwith %} {% endif %} {% elif class.source %}
Source code in {%- if class.relative_filepath.is_absolute() -%} {{ class.relative_package_filepath }} {%- else -%} {{ class.relative_filepath }} {%- endif -%} {{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }}
{% endif %} {% endif %} {% endblock source %} {% block children scoped %} {% set root = False %} {% set heading_level = heading_level + 1 %} {% include "children.html" with context %} {% endblock children %} {% endblock contents %}
{% endwith %}
docstring.html000066400000000000000000000041631454701760200355250ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base{% if docstring_sections %} {{ log.debug("Rendering docstring") }} {% for section in docstring_sections %} {% if config.show_docstring_description and section.kind.value == "text" %} {{ section.value|convert_markdown(heading_level, html_id) }} {% elif config.show_docstring_attributes and section.kind.value == "attributes" %} {% include "docstring/attributes.html" with context %} {% elif config.show_docstring_functions and section.kind.value == "functions" %} {% include "docstring/functions.html" with context %} {% elif config.show_docstring_classes and section.kind.value == "classes" %} {% include "docstring/classes.html" with context %} {% elif config.show_docstring_modules and section.kind.value == "modules" %} {% include "docstring/modules.html" with context %} {% elif config.show_docstring_parameters and section.kind.value == "parameters" %} {% include "docstring/parameters.html" with context %} {% elif config.show_docstring_other_parameters and section.kind.value == "other parameters" %} {% include "docstring/other_parameters.html" with context %} {% elif config.show_docstring_raises and section.kind.value == "raises" %} {% include "docstring/raises.html" with context %} {% elif config.show_docstring_warns and section.kind.value == "warns" %} {% include "docstring/warns.html" with context %} {% elif config.show_docstring_yields and section.kind.value == "yields" %} {% include "docstring/yields.html" with context %} {% elif config.show_docstring_receives and section.kind.value == "receives" %} {% include "docstring/receives.html" with context %} {% elif config.show_docstring_returns and section.kind.value == "returns" %} {% include "docstring/returns.html" with context %} {% elif config.show_docstring_examples and section.kind.value == "examples" %} {% include "docstring/examples.html" with context %} {% elif config.show_docstring_description and section.kind.value == "admonition" %} {% include "docstring/admonition.html" with context %} {% endif %} {% endfor %} {% endif %} docstring/000077500000000000000000000000001454701760200346335ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_baseadmonition.html000066400000000000000000000004221454701760200376600ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/docstring{{ log.debug("Rendering admonition") }}
{{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }} {{ section.value.contents|convert_markdown(heading_level, html_id) }}
attributes.html000066400000000000000000000060101454701760200377040ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/docstring{{ log.debug("Rendering attributes section") }} {% import "language.html" as lang with context %} {% if config.docstring_section_style == "table" %} {% block table_style %}

{{ section.title or lang.t("Attributes:") }}

{% for attribute in section.value %} {% endfor %}
{{ lang.t("Name") }} {{ lang.t("Type") }} {{ lang.t("Description") }}
{{ attribute.name }} {% if attribute.annotation %} {% with expression = attribute.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %}
{{ attribute.description|convert_markdown(heading_level, html_id) }}
{% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %}

{{ section.title or lang.t("Attributes:") }}

    {% for attribute in section.value %}
  • {{ attribute.name }} {% if attribute.annotation %} {% with expression = attribute.annotation %} ({% include "expression.html" with context %}) {% endwith %} {% endif %} –
    {{ attribute.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
{% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style %} {% for attribute in section.value %} {% endfor %}
{{ (section.title or lang.t("ATTRIBUTE")).rstrip(":").upper() }} {{ lang.t("DESCRIPTION") }}
{{ attribute.name }}
{{ attribute.description|convert_markdown(heading_level, html_id) }}

{% if attribute.annotation %} TYPE: {% with expression = attribute.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %}

{% endblock spacy_style %} {% endif %}classes.html000066400000000000000000000041131454701760200371550ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/docstring{{ log.debug("Rendering classes section") }} {% import "language.html" as lang with context %} {% if config.docstring_section_style == "table" %} {% block table_style %}

{{ section.title or lang.t("Classes:") }}

{% for class in section.value %} {% endfor %}
{{ lang.t("Name") }} {{ lang.t("Description") }}
{{ class.name }}
{{ class.description|convert_markdown(heading_level, html_id) }}
{% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %}

{{ section.title or lang.t("Classes:") }}

    {% for class in section.value %}
  • {{ class.name }} –
    {{ class.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
{% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style %} {% for class in section.value %} {% endfor %}
{{ (section.title or lang.t("CLASS")).rstrip(":").upper() }} {{ lang.t("DESCRIPTION") }}
{{ class.name }}
{{ class.description|convert_markdown(heading_level, html_id) }}
{% endblock spacy_style %} {% endif %}examples.html000066400000000000000000000007141454701760200373410ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/docstring{{ log.debug("Rendering examples section") }} {% import "language.html" as lang with context %}

{{ section.title or lang.t("Examples:") }}

{% for section_type, sub_section in section.value %} {% if section_type.value == "text" %} {{ sub_section|convert_markdown(heading_level, html_id) }} {% elif section_type.value == "examples" %} {{ sub_section|highlight(language="pycon", linenums=False) }} {% endif %} {% endfor %} functions.html000066400000000000000000000051261454701760200375350ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/docstring{{ log.debug("Rendering functions section") }} {% import "language.html" as lang with context %} {% if config.docstring_section_style == "table" %} {% block table_style %}

{{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}

{% for function in section.value %} {% if not function.name == "__init__" or not config.merge_init_into_class %} {% endif %} {% endfor %}
{{ lang.t("Name") }} {{ lang.t("Description") }}
{{ function.name }}
{{ function.description|convert_markdown(heading_level, html_id) }}
{% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %}

{{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}

    {% for function in section.value %} {% if not function.name == "__init__" or not config.merge_init_into_class %}
  • {{ function.name }} –
    {{ function.description|convert_markdown(heading_level, html_id) }}
    • {% endif %} {% endfor %}
{% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style %} {% for function in section.value %} {% if not function.name == "__init__" or not config.merge_init_into_class %} {% endif %} {% endfor %}
{{ (section.title or lang.t("METHOD") if obj.is_class else lang.t("FUNCTION")).rstrip(":").upper() }} {{ lang.t("DESCRIPTION") }}
{{ function.name }}
{{ function.description|convert_markdown(heading_level, html_id) }}
{% endblock spacy_style %} {% endif %}modules.html000066400000000000000000000041311454701760200371700ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/docstring{{ log.debug("Rendering modules section") }} {% import "language.html" as lang with context %} {% if config.docstring_section_style == "table" %} {% block table_style %}

{{ section.title or lang.t("Modules:") }}

{% for module in section.value %} {% endfor %}
{{ lang.t("Name") }} {{ lang.t("Description") }}
{{ module.name }}
{{ module.description|convert_markdown(heading_level, html_id) }}
{% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %}

{{ section.title or lang.t("Modules:") }}

    {% for module in section.value %}
  • {{ module.name }} –
    {{ module.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
{% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style %} {% for module in section.value %} {% endfor %}
{{ (section.title or lang.t("MODULE")).rstrip(":").upper() }} {{ lang.t("DESCRIPTION") }}
{{ module.name }}
{{ module.description|convert_markdown(heading_level, html_id) }}
{% endblock spacy_style %} {% endif %}other_parameters.html000066400000000000000000000054621454701760200410740ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/docstring{{ log.debug("Rendering other parameters section") }} {% import "language.html" as lang with context %} {% if config.docstring_section_style == "table" %} {% block table_style %}

{{ section.title or lang.t("Other Parameters:") }}

{% for parameter in section.value %} {% endfor %}
{{ lang.t("Name") }} {{ lang.t("Type") }} {{ lang.t("Description") }}
{{ parameter.name }} {% if parameter.annotation %} {% with expression = parameter.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %}
{{ parameter.description|convert_markdown(heading_level, html_id) }}
{% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %}

{{ section.title or lang.t("Other Parameters:") }}

    {% for parameter in section.value %}
  • {{ parameter.name }} {% if parameter.annotation %} {% with expression = parameter.annotation %} ({% include "expression.html" with context %}) {% endwith %} {% endif %} –
    {{ parameter.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
{% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style %} {% for parameter in section.value %} {% endfor %}
{{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }} {{ lang.t("DESCRIPTION") }}
{{ parameter.name }}
{{ parameter.description|convert_markdown(heading_level, html_id) }}

{% if parameter.annotation %} {{ lang.t("TYPE:") }} {% with expression = parameter.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %}

{% endblock spacy_style %} {% endif %}parameters.html000066400000000000000000000073571454701760200377000ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/docstring{{ log.debug("Rendering parameters section") }} {% import "language.html" as lang with context %} {% if config.docstring_section_style == "table" %} {% block table_style %}

{{ section.title or lang.t("Parameters:") }}

{% for parameter in section.value %} {% endfor %}
{{ lang.t("Name") }} {{ lang.t("Type") }} {{ lang.t("Description") }} {{ lang.t("Default") }}
{{ parameter.name }} {% if parameter.annotation %} {% with expression = parameter.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %}
{{ parameter.description|convert_markdown(heading_level, html_id) }}
{% if parameter.default %} {% with expression = parameter.default %} {% include "expression.html" with context %} {% endwith %} {% else %} {{ lang.t("required") }} {% endif %}
{% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %}

{{ section.title or lang.t("Parameters:") }}

    {% for parameter in section.value %}
  • {{ parameter.name }} {% if parameter.annotation %} {% with expression = parameter.annotation %} ({% include "expression.html" with context %} {%- if parameter.default %}, {{ lang.t("default:") }} {% with expression = parameter.default %} {% include "expression.html" with context %} {% endwith %} {% endif %}) {% endwith %} {% endif %} –
    {{ parameter.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
{% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style %} {% for parameter in section.value %} {% endfor %}
{{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }} {{ lang.t("DESCRIPTION") }}
{{ parameter.name }}
{{ parameter.description|convert_markdown(heading_level, html_id) }}

{% if parameter.annotation %} {{ lang.t("TYPE:") }} {% with expression = parameter.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %} {% if parameter.default %} {{ lang.t("DEFAULT:") }} {% with expression = parameter.default %} {% include "expression.html" with context %} {% endwith %} {% endif %}

{% endblock spacy_style %} {% endif %} raises.html000066400000000000000000000046561454701760200370220ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/docstring{{ log.debug("Rendering raises section") }} {% import "language.html" as lang with context %} {% if config.docstring_section_style == "table" %} {% block table_style %}

{{ section.title or lang.t("Raises:") }}

{% for raises in section.value %} {% endfor %}
{{ lang.t("Type") }} {{ lang.t("Description") }}
{% if raises.annotation %} {% with expression = raises.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %}
{{ raises.description|convert_markdown(heading_level, html_id) }}
{% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %}

{{ lang.t(section.title) or lang.t("Raises:") }}

    {% for raises in section.value %}
  • {% if raises.annotation %} {% with expression = raises.annotation %} {% include "expression.html" with context %} {% endwith %} – {% endif %}
    {{ raises.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
{% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style %} {% for raises in section.value %} {% endfor %}
{{ (section.title or lang.t("RAISES")).rstrip(":").upper() }} {{ lang.t("DESCRIPTION") }}
{% with expression = raises.annotation %} {% include "expression.html" with context %} {% endwith %}
{{ raises.description|convert_markdown(heading_level, html_id) }}
{% endblock spacy_style %} {% endif %}receives.html000066400000000000000000000066571454701760200373440ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/docstring{{ log.debug("Rendering receives section") }} {% import "language.html" as lang with context %} {% if config.docstring_section_style == "table" %} {% block table_style %} {% set name_column = section.value|selectattr("name")|any %}

{{ section.title or lang.t("Receives:") }}

{% if name_column %}{% endif %} {% for receives in section.value %} {% if name_column %}{% endif %} {% endfor %}
{{ lang.t("Name") }}{{ lang.t("Type") }} {{ lang.t("Description") }}
{% if receives.name %}{{ receives.name }}{% endif %} {% if receives.annotation %} {% with expression = receives.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %}
{{ receives.description|convert_markdown(heading_level, html_id) }}
{% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %}

{{ section.title or lang.t("Receives:") }}

    {% for receives in section.value %}
  • {% if receives.name %}{{ receives.name }}{% endif %} {% if receives.annotation %} {% with expression = receives.annotation %} {% if receives.name %} ({% endif %} {% include "expression.html" with context %} {% if receives.name %}){% endif %} {% endwith %} {% endif %} –
    {{ receives.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
{% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style %} {% for receives in section.value %} {% endfor %}
{{ (section.title or lang.t("RECEIVES")).rstrip(":").upper() }} {{ lang.t("DESCRIPTION") }}
{% if receives.name %} {{ receives.name }} {% elif receives.annotation %} {% with expression = receives.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %}
{{ receives.description|convert_markdown(heading_level, html_id) }}
{% if receives.name and receives.annotation %}

{{ lang.t("TYPE:") }} {% with expression = receives.annotation %} {% include "expression.html" with context %} {% endwith %}

{% endif %}
{% endblock spacy_style %} {% endif %}returns.html000066400000000000000000000066271454701760200372360ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/docstring{{ log.debug("Rendering returns section") }} {% import "language.html" as lang with context %} {% if config.docstring_section_style == "table" %} {% block table_style %} {% set name_column = section.value|selectattr("name")|any %}

{{ section.title or lang.t("Returns:") }}

{% if name_column %}{% endif %} {% for returns in section.value %} {% if name_column %}{% endif %} {% endfor %}
{{ lang.t("Name") }}{{ lang.t("Type") }} {{ lang.t("Description") }}
{% if returns.name %}{{ returns.name }}{% endif %} {% if returns.annotation %} {% with expression = returns.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %}
{{ returns.description|convert_markdown(heading_level, html_id) }}
{% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %}

{{ section.title or lang.t("Returns:") }}

    {% for returns in section.value %}
  • {% if returns.name %}{{ returns.name }}{% endif %} {% if returns.annotation %} {% with expression = returns.annotation %} {% if returns.name %} ({% endif %} {% include "expression.html" with context %} {% if returns.name %}){% endif %} {% endwith %} {% endif %} –
    {{ returns.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
{% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style %} {% for returns in section.value %} {% endfor %}
{{ (section.title or lang.t("RETURNS")).rstrip(":").upper() }} {{ lang.t("DESCRIPTION").upper() }}
{% if returns.name %} {{ returns.name }} {% elif returns.annotation %} {% with expression = returns.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %}
{{ returns.description|convert_markdown(heading_level, html_id) }}
{% if returns.name and returns.annotation %}

{{ lang.t("TYPE:") }} {% with expression = returns.annotation %} {% include "expression.html" with context %} {% endwith %}

{% endif %}
{% endblock spacy_style %} {% endif %}warns.html000066400000000000000000000046251454701760200366620ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/docstring{{ log.debug("Rendering warns section") }} {% import "language.html" as lang with context %} {% if config.docstring_section_style == "table" %} {% block table_style %}

{{ section.title or lang.t("Warns:") }}

{% for warns in section.value %} {% endfor %}
{{ lang.t("Type") }} {{ lang.t("Description") }}
{% if warns.annotation %} {% with expression = warns.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %}
{{ warns.description|convert_markdown(heading_level, html_id) }}
{% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %}

{{ section.title or lang.t("Warns:") }}

    {% for warns in section.value %}
  • {% if warns.annotation %} {% with expression = warns.annotation %} {% include "expression.html" with context %} {% endwith %} – {% endif %}
    {{ warns.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
{% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style %} {% for warns in section.value %} {% endfor %}
{{ (section.title or lang.t("WARNS")).rstrip(":").upper() }} {{ lang.t("DESCRIPTION") }}
{% with expression = warns.annotation %} {% include "expression.html" with context %} {% endwith %}
{{ warns.description|convert_markdown(heading_level, html_id) }}
{% endblock spacy_style %} {% endif %}yields.html000066400000000000000000000065641454701760200370250ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/docstring{{ log.debug("Rendering yields section") }} {% import "language.html" as lang with context %} {% if config.docstring_section_style == "table" %} {% block table_style %} {% set name_column = section.value|selectattr("name")|any %}

{{ section.title or lang.t("Yields:") }}

{% if name_column %}{% endif %} {% for yields in section.value %} {% if name_column %}{% endif %} {% endfor %}
{{ lang.t("Name") }}{{ lang.t("Type") }} {{ lang.t("Description") }}
{% if yields.name %}{{ yields.name }}{% endif %} {% if yields.annotation %} {% with expression = yields.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %}
{{ yields.description|convert_markdown(heading_level, html_id) }}
{% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %}

{{ section.title or lang.t("Yields:") }}

    {% for yields in section.value %}
  • {% if yields.name %}{{ yields.name }}{% endif %} {% if yields.annotation %} {% with expression = yields.annotation %} {% if yields.name %} ({% endif %} {% include "expression.html" with context %} {% if yields.name %}){% endif %} {% endwith %} {% endif %} –
    {{ yields.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
{% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style %} {% for yields in section.value %} {% endfor %}
{{ (section.title or lang.t("YIELDS")).rstrip(":").upper() }} {{ lang.t("DESCRIPTION") }}
{% if yields.name %} {{ yields.name }} {% elif yields.annotation %} {% with expression = yields.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %}
{{ yields.description|convert_markdown(heading_level, html_id) }}
{% if yields.name and yields.annotation %}

{{ lang.t("TYPE:") }}: {% with expression = yields.annotation %} {% include "expression.html" with context %} {% endwith %}

{% endif %}
{% endblock spacy_style %} {% endif %}expression.html000066400000000000000000000040361454701760200357270ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base{%- macro crossref(name, annotation_path) -%} {%- with full = name.canonical_path -%} {%- if annotation_path == "brief" -%} {%- set annotation = name.canonical_name -%} {%- elif annotation_path == "source" -%} {%- set annotation = name.name -%} {%- elif annotation_path == "full" -%} {%- set annotation = full -%} {%- endif -%} {%- for title, path in annotation|split_path(full) -%} {%- if not signature or config.signature_crossrefs -%} {%- filter stash_crossref(length=title|length) -%} {{ title }} {%- endfilter -%} {%- else -%} {{ title }} {%- endif -%} {%- if not loop.last -%}.{%- endif -%} {%- endfor -%} {%- endwith -%} {%- endmacro -%} {%- macro render(expression, annotations_path) -%} {%- if expression is string -%} {%- if signature -%}{{ expression|safe }}{%- else -%}{{ expression }}{%- endif -%} {%- elif expression.classname == "ExprName" -%} {{ crossref(expression, annotations_path) }} {%- elif config.unwrap_annotated and expression.classname == "ExprSubscript" and expression.canonical_path in ("typing.Annotated", "typing_extensions.Annotated") -%} {{ render(expression.slice.elements[0], annotations_path) }} {%- elif expression.classname == "ExprAttribute" -%} {%- if annotations_path == "brief" -%} {{ render(expression.last, "brief") }} {%- elif annotations_path == "full" -%} {{ render(expression.first, "full") }} {%- for element in expression -%} {%- if not loop.first -%} {{ render(element, "brief") }} {%- endif -%} {%- endfor -%} {%- else -%} {%- for element in expression -%} {{ render(element, annotations_path) }} {%- endfor -%} {%- endif -%} {%- else -%} {%- for element in expression -%} {{ render(element, annotations_path) }} {%- endfor -%} {%- endif -%} {%- endmacro -%} {{ render(expression, config.annotations_path) }} function.html000066400000000000000000000066731454701760200353660ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base{{ log.debug("Rendering " + function.path) }} {% import "language.html" as lang with context %}
{% with obj = function, html_id = function.path %} {% if root %} {% set show_full_path = config.show_root_full_path %} {% set root_members = True %} {% elif root_members %} {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %} {% set root_members = False %} {% else %} {% set show_full_path = config.show_object_full_path %} {% endif %} {% set function_name = function.path if show_full_path else function.name %} {% set symbol_type = "method" if function.parent.is_class else "function" %} {% if not root or config.show_root_heading %} {% filter heading( heading_level, role="function", id=html_id, class="doc doc-heading", toc_label=((' ')|safe if config.show_symbol_type_toc else '') + function.name, ) %} {% block heading scoped %} {% if config.show_symbol_type_heading %}{% endif %} {% if config.separate_signature %} {{ function_name }} {% else %} {%+ filter highlight(language="python", inline=True) %} {{ function_name }}{% include "signature.html" with context %} {% endfilter %} {% endif %} {% endblock heading %} {% block labels scoped %} {% with labels = function.labels %} {% include "labels.html" with context %} {% endwith %} {% endblock labels %} {% endfilter %} {% block signature scoped %} {% if config.separate_signature %} {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %} {{ function.name }} {% endfilter %} {% endif %} {% endblock signature %} {% else %} {% if config.show_root_toc_entry %} {% filter heading( heading_level, role="function", id=html_id, toc_label=((' ')|safe if config.show_symbol_type_toc else '') + function.name, hidden=True, ) %} {% endfilter %} {% endif %} {% set heading_level = heading_level - 1 %} {% endif %}
{% block contents scoped %} {% block docstring scoped %} {% with docstring_sections = function.docstring.parsed %} {% include "docstring.html" with context %} {% endwith %} {% endblock docstring %} {% block source scoped %} {% if config.show_source and function.source %}
{{ lang.t("Source code in") }} {%- if function.relative_filepath.is_absolute() -%} {{ function.relative_package_filepath }} {%- else -%} {{ function.relative_filepath }} {%- endif -%} {{ function.source|highlight(language="python", linestart=function.lineno, linenums=True) }}
{% endif %} {% endblock source %} {% endblock contents %}
{% endwith %}
labels.html000066400000000000000000000003721454701760200347710ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base{% if labels %} {{ log.debug("Rendering labels") }} {% for label in labels|sort %} {{ label }} {% endfor %} {% endif %} languages/000077500000000000000000000000001454701760200346055ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_baseen.html000066400000000000000000000017061454701760200361010ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/languages {% macro t(key) %}{{ { "ATTRIBUTE": "ATTRIBUTE", "Attributes:": "Attributes:", "Classes:": "Classes:", "CLASS": "CLASS", "DEFAULT:": "DEFAULT:", "Default": "Default", "default:": "default:", "DESCRIPTION": "DESCRIPTION", "Description": "Description", "Examples:": "Examples:", "Functions:": "Functions:", "FUNCTION": "FUNCTION", "Methods:": "Methods:", "METHOD": "METHOD", "Modules:": "Modules:", "MODULE": "MODULE", "Name": "Name", "Other Parameters:": "Other Parameters:", "PARAMETER": "PARAMETER", "Parameters:": "Parameters:", "RAISES": "RAISES", "Raises:" : "Raises:", "RECEIVES": "RECEIVES", "Receives:": "Receives:", "required": "required", "RETURNS": "RETURNS", "Returns:": "Returns:", "Source code in": "Source code in", "TYPE:": "TYPE:", "Type": "Type", "WARNS": "WARNS", "Warns:": "Warns:", "YIELDS": "YIELDS", "Yields:": "Yields:", }[key] }}{% endmacro %}ja.html000066400000000000000000000017301454701760200360660ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/languages {% macro t(key) %}{{ { "ATTRIBUTE": "属性", "Attributes:": "属性：", "Classes:": "", "CLASS": "", "DEFAULT:": "デフォルト：", "Default": "デフォルト", "default:": "デフォルト：", "DESCRIPTION": "デスクリプション", "Description": "デスクリプション", "Examples:": "例：", "Functions:": "", "FUNCTION": "", "Methods:": "", "METHOD": "", "Modules:": "", "MODULE": "", "Name": "名前", "Other Parameters:": "他の引数：", "PARAMETER": "引数", "Parameters:": "引数：", "RAISES": "発生", "Raises:" : "発生：", "RECEIVES": "取得", "Receives:": "取得：", "required": "必須", "RETURNS": "戻り値", "Returns:": "戻り値：", "Source code in": "ソースコード位置：", "TYPE:": "タイプ：", "Type": "タイプ", "WARNS": "警告", "Warns:": "警告：", "YIELDS": "返す", "Yields:": "返す：", }[key] }}{% endmacro %}zh.html000066400000000000000000000016061454701760200361170ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/languages {% macro t(key) %}{{ { "ATTRIBUTE": "属性", "Attributes:": "属性：", "Classes:": "", "CLASS": "", "DEFAULT:": "默认：", "Default": "默认", "default:": "默认：", "DESCRIPTION": "描述", "Description": "描述", "Examples:": "示例：", "Functions:": "", "FUNCTION": "", "Methods:": "", "METHOD": "", "Modules:": "", "MODULE": "", "Name": "名称", "Other Parameters:": "其他参数：", "PARAMETER": "参数", "Parameters:": "参数：", "RAISES": "引发", "Raises:" : "引发：", "Receives:": "接收：", "RECEIVES": "接收", "required": "必需", "RETURNS": "返回", "Returns:": "返回：", "Source code in": "源代码位于：", "TYPE:": "类型：", "Type": "类型", "Warns:": "警告：", "WARNS": "警告", "YIELDS": "产生", "Yields:": "产生：", }[key] }}{% endmacro %}module.html000066400000000000000000000046601454701760200350200ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base{{ log.debug("Rendering " + module.path) }}
{% with obj = module, html_id = module.path %} {% if root %} {% set show_full_path = config.show_root_full_path %} {% set root_members = True %} {% elif root_members %} {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %} {% set root_members = False %} {% else %} {% set show_full_path = config.show_object_full_path %} {% endif %} {% set module_name = module.path if show_full_path else module.name %} {% if not root or config.show_root_heading %} {% filter heading( heading_level, role="module", id=html_id, class="doc doc-heading", toc_label=(' '|safe if config.show_symbol_type_toc else '') + module.name, ) %} {% block heading scoped %} {% if config.show_symbol_type_heading %}{% endif %} {% if config.separate_signature %} {{ module_name }} {% else %} {{ module_name }} {% endif %} {% endblock heading %} {% block labels scoped %} {% with labels = module.labels %} {% include "labels.html" with context %} {% endwith %} {% endblock labels %} {% endfilter %} {% else %} {% if config.show_root_toc_entry %} {% filter heading(heading_level, role="module", id=html_id, toc_label=(' '|safe if config.show_symbol_type_toc else '') + module.name, hidden=True, ) %} {% endfilter %} {% endif %} {% set heading_level = heading_level - 1 %} {% endif %}
{% block contents scoped %} {% block docstring scoped %} {% with docstring_sections = module.docstring.parsed %} {% include "docstring.html" with context %} {% endwith %} {% endblock docstring %} {% block children scoped %} {% set root = False %} {% set heading_level = heading_level + 1 %} {% include "children.html" with context %} {% endblock children %} {% endblock contents %}
{% endwith %}
signature.html000066400000000000000000000054211454701760200355300ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base{%- if config.show_signature -%} {{ log.debug("Rendering signature") }} {%- with -%} {%- set ns = namespace( has_pos_only=False, render_pos_only_separator=True, render_kw_only_separator=True, annotation="", equal="=", ) -%} ( {%- for parameter in function.parameters -%} {%- if parameter.name not in ("self", "cls") or loop.index0 > 0 or not (function.parent and function.parent.is_class) -%} {%- if parameter.kind.value == "positional-only" -%} {%- set ns.has_pos_only = True -%} {%- else -%} {%- if ns.has_pos_only and ns.render_pos_only_separator -%} {%- set ns.render_pos_only_separator = False %}/, {% endif -%} {%- if parameter.kind.value == "keyword-only" -%} {%- if ns.render_kw_only_separator -%} {%- set ns.render_kw_only_separator = False %}*, {% endif -%} {%- endif -%} {%- endif -%} {%- if config.show_signature_annotations and parameter.annotation is not none -%} {%- set ns.equal = " = " -%} {%- if config.separate_signature and config.signature_crossrefs -%} {%- with expression = parameter.annotation -%} {%- set ns.annotation -%}: {% include "expression.html" with context %}{%- endset -%} {%- endwith -%} {%- else -%} {%- set ns.annotation = ": " + parameter.annotation|safe -%} {%- endif -%} {%- else -%} {%- set ns.equal = "=" -%} {%- set ns.annotation = "" -%} {%- endif -%} {%- if parameter.default is not none and parameter.kind.value != "variadic positional" and parameter.kind.value != "variadic keyword" -%} {%- set default = ns.equal + parameter.default|safe -%} {%- endif -%} {%- if parameter.kind.value == "variadic positional" -%} {%- set ns.render_kw_only_separator = False -%} {%- endif -%} {% if parameter.kind.value == "variadic positional" %}*{% elif parameter.kind.value == "variadic keyword" %}**{% endif -%} {{ parameter.name }}{{ ns.annotation }}{{ default }} {%- if not loop.last %}, {% endif -%} {%- endif -%} {%- endfor -%} ) {%- if config.show_signature_annotations and function.annotation and not (config.merge_init_into_class and function.name == "__init__" ) %} -> {% if config.separate_signature and config.signature_crossrefs -%} {%- with expression = function.annotation %}{% include "expression.html" with context %}{%- endwith -%} {%- else -%} {{ function.annotation|safe }} {%- endif -%} {%- endif -%} {%- endwith -%} {%- endif -%}summary.html000066400000000000000000000000001454701760200352100ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_basesummary/000077500000000000000000000000001454701760200343345ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_baseattributes.html000066400000000000000000000000001454701760200373760ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/summaryclasses.html000066400000000000000000000000001454701760200366450ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/summaryfunctions.html000066400000000000000000000000001454701760200372200ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/summarymodules.html000066400000000000000000000000001454701760200366600ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/_base/summaryattribute.html000066400000000000000000000000451454701760200344560ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material{% extends "_base/attribute.html" %} mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/children.html000066400000000000000000000000441454701760200343210ustar00rootroot00000000000000{% extends "_base/children.html" %} mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/class.html000066400000000000000000000000411454701760200336330ustar00rootroot00000000000000{% extends "_base/class.html" %} docstring.html000066400000000000000000000000451454701760200344470ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material{% extends "_base/docstring.html" %} mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/docstring/000077500000000000000000000000001454701760200336415ustar00rootroot00000000000000admonition.html000066400000000000000000000000601454701760200366050ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/docstring{% extends "_base/docstring/admonition.html" %} attributes.html000066400000000000000000000000601454701760200366320ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/docstring{% extends "_base/docstring/attributes.html" %} classes.html000066400000000000000000000000551454701760200361050ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/docstring{% extends "_base/docstring/classes.html" %} examples.html000066400000000000000000000000561454701760200362670ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/docstring{% extends "_base/docstring/examples.html" %} functions.html000066400000000000000000000000571454701760200364620ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/docstring{% extends "_base/docstring/functions.html" %} modules.html000066400000000000000000000000551454701760200361200ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/docstring{% extends "_base/docstring/modules.html" %} other_parameters.html000066400000000000000000000000661454701760200400160ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/docstring{% extends "_base/docstring/other_parameters.html" %} parameters.html000066400000000000000000000000601454701760200366070ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/docstring{% extends "_base/docstring/parameters.html" %} raises.html000066400000000000000000000000541454701760200357350ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/docstring{% extends "_base/docstring/raises.html" %} receives.html000066400000000000000000000000561454701760200362560ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/docstring{% extends "_base/docstring/receives.html" %} returns.html000066400000000000000000000000551454701760200361520ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/docstring{% extends "_base/docstring/returns.html" %} warns.html000066400000000000000000000000531454701760200356000ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/docstring{% extends "_base/docstring/warns.html" %} yields.html000066400000000000000000000000541454701760200357400ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/docstring{% extends "_base/docstring/yields.html" %} expression.html000066400000000000000000000000461454701760200346530ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material{% extends "_base/expression.html" %} mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/function.html000066400000000000000000000000441454701760200343560ustar00rootroot00000000000000{% extends "_base/function.html" %} mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/labels.html000066400000000000000000000000421454701760200337710ustar00rootroot00000000000000{% extends "_base/labels.html" %} mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/language.html000066400000000000000000000006571454701760200343260ustar00rootroot00000000000000 {% set lang_pth = "languages/" ~ locale ~ ".html" %} {% if lang_pth is existing_template %} {% import lang_pth as lang %} {% import "languages/en.html" as fallback %} {% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %} {% else %} {% import "languages/en.html" as lang %} {% macro t(key) %}{{ lang.t(key) }}{% endmacro %} {% endif %} mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/languages/000077500000000000000000000000001454701760200336135ustar00rootroot00000000000000en.html000066400000000000000000000000471454701760200350250ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/languages{% extends "_base/languages/en.html" %}ja.html000066400000000000000000000000471454701760200350150ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/languages{% extends "_base/languages/ja.html" %}zh.html000066400000000000000000000000471454701760200350440ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/languages{% extends "_base/languages/zh.html" %}mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/module.html000066400000000000000000000000421454701760200340140ustar00rootroot00000000000000{% extends "_base/module.html" %} signature.html000066400000000000000000000000451454701760200344540ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material{% extends "_base/signature.html" %} mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/style.css000066400000000000000000000047541454701760200335310ustar00rootroot00000000000000/* Avoid breaking parameter names, etc. in table cells. */ .doc-contents td code { word-break: normal !important; } /* No line break before first paragraph of descriptions. */ .doc-md-description, .doc-md-description>p:first-child { display: inline; } /* Max width for docstring sections tables. */ .doc .md-typeset__table, .doc .md-typeset__table table { display: table !important; width: 100%; } .doc .md-typeset__table tr { display: table-row; } /* Defaults in Spacy table style. */ .doc-param-default { float: right; } /* Symbols in Navigation and ToC. */ :root, [data-md-color-scheme="default"] { --doc-symbol-attribute-fg-color: #953800; --doc-symbol-function-fg-color: #8250df; --doc-symbol-method-fg-color: #8250df; --doc-symbol-class-fg-color: #0550ae; --doc-symbol-module-fg-color: #5cad0f; --doc-symbol-attribute-bg-color: #9538001a; --doc-symbol-function-bg-color: #8250df1a; --doc-symbol-method-bg-color: #8250df1a; --doc-symbol-class-bg-color: #0550ae1a; --doc-symbol-module-bg-color: #5cad0f1a; } [data-md-color-scheme="slate"] { --doc-symbol-attribute-fg-color: #ffa657; --doc-symbol-function-fg-color: #d2a8ff; --doc-symbol-method-fg-color: #d2a8ff; --doc-symbol-class-fg-color: #79c0ff; --doc-symbol-module-fg-color: #baff79; --doc-symbol-attribute-bg-color: #ffa6571a; --doc-symbol-function-bg-color: #d2a8ff1a; --doc-symbol-method-bg-color: #d2a8ff1a; --doc-symbol-class-bg-color: #79c0ff1a; --doc-symbol-module-bg-color: #baff791a; } code.doc-symbol { border-radius: .1rem; font-size: .85em; padding: 0 .3em; font-weight: bold; } code.doc-symbol-attribute { color: var(--doc-symbol-attribute-fg-color); background-color: var(--doc-symbol-attribute-bg-color); } code.doc-symbol-attribute::after { content: "attr"; } code.doc-symbol-function { color: var(--doc-symbol-function-fg-color); background-color: var(--doc-symbol-function-bg-color); } code.doc-symbol-function::after { content: "func"; } code.doc-symbol-method { color: var(--doc-symbol-method-fg-color); background-color: var(--doc-symbol-method-bg-color); } code.doc-symbol-method::after { content: "meth"; } code.doc-symbol-class { color: var(--doc-symbol-class-fg-color); background-color: var(--doc-symbol-class-bg-color); } code.doc-symbol-class::after { content: "class"; } code.doc-symbol-module { color: var(--doc-symbol-module-fg-color); background-color: var(--doc-symbol-module-bg-color); } code.doc-symbol-module::after { content: "mod"; }mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/summary.html000066400000000000000000000000431454701760200342250ustar00rootroot00000000000000{% extends "_base/summary.html" %} mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/summary/000077500000000000000000000000001454701760200333425ustar00rootroot00000000000000attributes.html000066400000000000000000000000561454701760200363400ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/summary{% extends "_base/summary/attributes.html" %} classes.html000066400000000000000000000000531454701760200356040ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/summary{% extends "_base/summary/classes.html" %} functions.html000066400000000000000000000000551454701760200361610ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/summary{% extends "_base/summary/functions.html" %} modules.html000066400000000000000000000000531454701760200356170ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/material/summary{% extends "_base/summary/modules.html" %} mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/000077500000000000000000000000001454701760200323345ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/000077500000000000000000000000001454701760200343305ustar00rootroot00000000000000attributes.html000066400000000000000000000017511454701760200373310ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/docstring{{ log.debug() }} {% import "language.html" as lang with context %}
{{ section.title or lang.t("Attributes:") }}
    {% for attribute in section.value %}
  • {{ attribute.name }} {% if attribute.annotation %} {% with expression = attribute.annotation %} ({% include "expression.html" with context %}) {% endwith %} {% endif %} –
    {{ attribute.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
other_parameters.html000066400000000000000000000017571454701760200405150ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/docstring{{ log.debug() }} {% import "language.html" as lang with context %}
{{ section.title or lang.t("Other parameters:") }}
    {% for parameter in section.value %}
  • {{ parameter.name }} {% if parameter.annotation %} {% with expression = parameter.annotation %} ({% include "expression.html" with context %}) {% endwith %} {% endif %} –
    {{ parameter.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
parameters.html000066400000000000000000000023771454701760200373130ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/docstring{{ log.debug() }} {% import "language.html" as lang with context %}
{{ section.title or lang.t("Parameters:") }}
    {% for parameter in section.value %}
  • {{ parameter.name }} {% if parameter.annotation %} {% with expression = parameter.annotation %} ({% include "expression.html" with context %} {%- if parameter.default %}, {{ lang.t("default:") }} {% with expression = parameter.default %} {% include "expression.html" with context %} {% endwith %} {% endif %}) {% endwith %} {% endif %} –
    {{ parameter.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
raises.html000066400000000000000000000016401454701760200364260ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/docstring{{ log.debug() }} {% import "language.html" as lang with context %}
{{ section.title or lang.t("Raises:") }}
    {% for raises in section.value %}
  • {% if raises.annotation %} {% with expression = raises.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %} –
    {{ raises.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
receives.html000066400000000000000000000021531454701760200367450ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/docstring{{ log.debug() }} {% import "language.html" as lang with context %}
{{ section.title or lang.t("Receives:") }}
    {% for receives in section.value %}
  • {% if receives.name %}{{ receives.name }}{% endif %} {% if receives.annotation %} {% with expression = receives.annotation %} {% if receives.name %}({% endif %} {% include "expression.html" with context %} {% if receives.name %}){% endif %} {% endwith %} {% endif %} –
    {{ receives.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
returns.html000066400000000000000000000020701454701760200366400ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/docstring{{ log.debug() }} {% import "language.html" as lang with context %}
{{ section.title or lang.t("Returns:") }}
    {% for returns in section.value %}
  • {% if returns.name %}{{ returns.name }}{% endif %} {% if returns.annotation %} {% with expression = returns.annotation %} {% if returns.name %}({% endif %} {% include "expression.html" with context %} {% if returns.name %}){% endif %} {% endwith %} {% endif %} –
    {{ returns.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
warns.html000066400000000000000000000016331454701760200362740ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/docstring{{ log.debug() }} {% import "language.html" as lang with context %}
{{ section.title or lang.t("Warns:") }}
    {% for warns in section.value %}
  • {% if warns.annotation %} {% with expression = warns.annotation %} {% include "expression.html" with context %} {% endwith %} {% endif %} –
    {{ warns.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
yields.html000066400000000000000000000021321454701760200364260ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/docstring{{ log.debug() }} {% import "language.html" as lang with context %}
{{ section.title or lang.t("Yields:") }}
    {% for yields in section.value %}
  • {% if yields.name %}{{ yields.name }}{% endif %} {% if yields.annotation %} {% with expression = yields.annotation %} {% if yields.name %}({% endif %} {% include "expression.html" with context %} {% if yields.name %}){% endif %} {% endwith %} {% endif %} –
    {{ yields.description|convert_markdown(heading_level, html_id) }}
    • {% endfor %}
language.html000066400000000000000000000006571454701760200347360ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs {% set lang_pth = "languages/" ~ locale ~ ".html" %} {% if lang_pth is existing_template %} {% import lang_pth as lang %} {% import "languages/en.html" as fallback %} {% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %} {% else %} {% import "languages/en.html" as lang %} {% macro t(key) %}{{ lang.t(key) }}{% endmacro %} {% endif %} mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/languages/000077500000000000000000000000001454701760200343025ustar00rootroot00000000000000en.html000066400000000000000000000017061454701760200355170ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/languages {% macro t(key) %}{{ { "ATTRIBUTE": "ATTRIBUTE", "Attributes:": "Attributes:", "Classes:": "Classes:", "CLASS": "CLASS", "DEFAULT:": "DEFAULT:", "Default": "Default", "default:": "default:", "DESCRIPTION": "DESCRIPTION", "Description": "Description", "Examples:": "Examples:", "Functions:": "Functions:", "FUNCTION": "FUNCTION", "Methods:": "Methods:", "METHOD": "METHOD", "Modules:": "Modules:", "MODULE": "MODULE", "Name": "Name", "Other Parameters:": "Other Parameters:", "PARAMETER": "PARAMETER", "Parameters:": "Parameters:", "RAISES": "RAISES", "Raises:" : "Raises:", "RECEIVES": "RECEIVES", "Receives:": "Receives:", "required": "required", "RETURNS": "RETURNS", "Returns:": "Returns:", "Source code in": "Source code in", "TYPE:": "TYPE:", "Type": "Type", "WARNS": "WARNS", "Warns:": "Warns:", "YIELDS": "YIELDS", "Yields:": "Yields:", }[key] }}{% endmacro %}ja.html000066400000000000000000000017301454701760200355040ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/languages {% macro t(key) %}{{ { "ATTRIBUTE": "属性", "Attributes:": "属性：", "Classes:": "", "CLASS": "", "DEFAULT:": "デフォルト：", "Default": "デフォルト", "default:": "デフォルト：", "DESCRIPTION": "デスクリプション", "Description": "デスクリプション", "Examples:": "例：", "Functions:": "", "FUNCTION": "", "Methods:": "", "METHOD": "", "Modules:": "", "MODULE": "", "Name": "名前", "Other Parameters:": "他の引数：", "PARAMETER": "引数", "Parameters:": "引数：", "RAISES": "発生", "Raises:" : "発生：", "RECEIVES": "取得", "Receives:": "取得：", "required": "必須", "RETURNS": "戻り値", "Returns:": "戻り値：", "Source code in": "ソースコード位置：", "TYPE:": "タイプ：", "Type": "タイプ", "WARNS": "警告", "Warns:": "警告：", "YIELDS": "返す", "Yields:": "返す：", }[key] }}{% endmacro %}zh.html000066400000000000000000000016061454701760200355350ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/languages {% macro t(key) %}{{ { "ATTRIBUTE": "属性", "Attributes:": "属性：", "Classes:": "", "CLASS": "", "DEFAULT:": "默认：", "Default": "默认", "default:": "默认：", "DESCRIPTION": "描述", "Description": "描述", "Examples:": "示例：", "Functions:": "", "FUNCTION": "", "Methods:": "", "METHOD": "", "Modules:": "", "MODULE": "", "Name": "名称", "Other Parameters:": "其他参数：", "PARAMETER": "参数", "Parameters:": "参数：", "RAISES": "引发", "Raises:" : "引发：", "Receives:": "接收：", "RECEIVES": "接收", "required": "必需", "RETURNS": "返回", "Returns:": "返回：", "Source code in": "源代码位于：", "TYPE:": "类型：", "Type": "类型", "Warns:": "警告：", "WARNS": "警告", "YIELDS": "产生", "Yields:": "产生：", }[key] }}{% endmacro %}mkdocstrings-python-handlers-1.8.0/src/mkdocstrings_handlers/python/templates/readthedocs/style.css000066400000000000000000000017131454701760200342100ustar00rootroot00000000000000/* Avoid breaking parameters name, etc. in table cells. */ .doc-contents td code { word-break: normal !important; } /* No line break before first paragraph of descriptions. */ .doc-md-description, .doc-md-description>p:first-child { display: inline; } /* Avoid breaking code headings. */ .doc-heading code { white-space: normal; } /* Improve rendering of parameters, returns and exceptions. */ .doc-contents .field-name { min-width: 100px; } /* Other curious-spacing fixes. */ .doc-contents .field-name, .doc-contents .field-body { border: none !important; padding: 0 !important; } .doc-contents p { margin: 1em 0 1em; } .doc-contents .field-list { margin: 0 !important; } .doc-contents pre { padding: 0 !important; } .doc-contents .wy-table-responsive { margin-bottom: 0 !important; } .doc-contents td.code { padding: 0 !important; } .doc-contents td.linenos { padding: 0 8px !important; } .doc-children, footer { margin-top: 20px; }mkdocstrings-python-handlers-1.8.0/tests/000077500000000000000000000000001454701760200205145ustar00rootroot00000000000000mkdocstrings-python-handlers-1.8.0/tests/__init__.py000066400000000000000000000002561454701760200226300ustar00rootroot00000000000000"""Tests suite for `mkdocstrings_handlers`.""" from pathlib import Path TESTS_DIR = Path(__file__).parent TMP_DIR = TESTS_DIR / "tmp" FIXTURES_DIR = TESTS_DIR / "fixtures" mkdocstrings-python-handlers-1.8.0/tests/conftest.py000066400000000000000000000056401454701760200227200ustar00rootroot00000000000000"""Configuration for the pytest test suite.""" from __future__ import annotations from collections import ChainMap from typing import TYPE_CHECKING, Any, Iterator import pytest from markdown.core import Markdown from mkdocs.config.defaults import MkDocsConfig if TYPE_CHECKING: from pathlib import Path from mkdocs import config from mkdocstrings.plugin import MkdocstringsPlugin from mkdocstrings_handlers.python.handler import PythonHandler @pytest.fixture(name="mkdocs_conf") def fixture_mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Iterator[config.Config]: """Yield a MkDocs configuration object. Parameters: request: Pytest fixture. tmp_path: Pytest fixture. Yields: MkDocs config. """ conf = MkDocsConfig() while hasattr(request, "_parent_request") and hasattr(request._parent_request, "_parent_request"): request = request._parent_request conf_dict = { "site_name": "foo", "site_url": "https://example.org/", "site_dir": str(tmp_path), "plugins": [{"mkdocstrings": {"default_handler": "python"}}], **getattr(request, "param", {}), } # Re-create it manually as a workaround for https://github.com/mkdocs/mkdocs/issues/2289 mdx_configs: dict[str, Any] = dict(ChainMap(*conf_dict.get("markdown_extensions", []))) conf.load_dict(conf_dict) assert conf.validate() == ([], []) conf["mdx_configs"] = mdx_configs conf["markdown_extensions"].insert(0, "toc") # Guaranteed to be added by MkDocs. conf = conf["plugins"]["mkdocstrings"].on_config(conf) conf = conf["plugins"]["autorefs"].on_config(conf) yield conf conf["plugins"]["mkdocstrings"].on_post_build(conf) @pytest.fixture(name="plugin") def fixture_plugin(mkdocs_conf: config.Config) -> MkdocstringsPlugin: """Return a plugin instance. Parameters: mkdocs_conf: Pytest fixture: [tests.conftest.fixture_mkdocs_conf][]. Returns: mkdocstrings plugin instance. """ return mkdocs_conf["plugins"]["mkdocstrings"] @pytest.fixture(name="ext_markdown") def fixture_ext_markdown(mkdocs_conf: config.Config) -> Markdown: """Return a Markdown instance with MkdocstringsExtension. Parameters: mkdocs_conf: Pytest fixture: [tests.conftest.fixture_mkdocs_conf][]. Returns: A Markdown instance. """ return Markdown(extensions=mkdocs_conf["markdown_extensions"], extension_configs=mkdocs_conf["mdx_configs"]) @pytest.fixture(name="handler") def fixture_handler(plugin: MkdocstringsPlugin, ext_markdown: Markdown) -> PythonHandler: """Return a handler instance. Parameters: plugin: Pytest fixture: [tests.conftest.fixture_plugin][]. Returns: A handler instance. """ handler = plugin.handlers.get_handler("python") handler._update_env(ext_markdown, plugin.handlers._config) return handler # type: ignore[return-value] mkdocstrings-python-handlers-1.8.0/tests/test_handler.py000066400000000000000000000121261454701760200235440ustar00rootroot00000000000000"""Tests for the `handler` module.""" from __future__ import annotations import os from glob import glob from typing import TYPE_CHECKING import pytest from griffe.docstrings.dataclasses import DocstringSectionExamples, DocstringSectionKind from mkdocstrings_handlers.python.handler import CollectionError, PythonHandler, get_handler if TYPE_CHECKING: from pathlib import Path def test_collect_missing_module() -> None: """Assert error is raised for missing modules.""" handler = get_handler(theme="material") with pytest.raises(CollectionError): handler.collect("aaaaaaaa", {}) def test_collect_missing_module_item() -> None: """Assert error is raised for missing items within existing modules.""" handler = get_handler(theme="material") with pytest.raises(CollectionError): handler.collect("mkdocstrings.aaaaaaaa", {}) def test_collect_module() -> None: """Assert existing module can be collected.""" handler = get_handler(theme="material") assert handler.collect("mkdocstrings", {}) def test_collect_with_null_parser() -> None: """Assert we can pass `None` as parser when collecting.""" handler = get_handler(theme="material") assert handler.collect("mkdocstrings", {"docstring_style": None}) @pytest.mark.parametrize( "handler", [ {"theme": "mkdocs"}, {"theme": "readthedocs"}, {"theme": {"name": "material"}}, ], indirect=["handler"], ) def test_render_docstring_examples_section(handler: PythonHandler) -> None: """Assert docstrings' examples section can be rendered. Parameters: handler: A handler instance (parametrized). """ section = DocstringSectionExamples( value=[ (DocstringSectionKind.text, "This is an example."), (DocstringSectionKind.examples, ">>> print('Hello')\nHello"), ], ) template = handler.env.get_template("docstring/examples.html") rendered = template.render(section=section, locale="en") template.render(section=section, locale="not_existing") assert "

This is an example.

" in rendered assert "print" in rendered assert "Hello" in rendered def test_expand_globs(tmp_path: Path) -> None: """Assert globs are correctly expanded. Parameters: tmp_path: Pytext fixture that creates a temporary directory. """ globbed_names = ( "expanded_a", "expanded_b", "other_expanded_c", "other_expanded_d", ) globbed_paths = [tmp_path.joinpath(globbed_name) for globbed_name in globbed_names] for path in globbed_paths: path.touch() handler = PythonHandler( handler="python", theme="material", config_file_path=str(tmp_path.joinpath("mkdocs.yml")), paths=["*exp*"], ) for path in globbed_paths: assert str(path) in handler._paths def test_expand_globs_without_changing_directory() -> None: """Assert globs are correctly expanded when we are already in the right directory.""" handler = PythonHandler( handler="python", theme="material", config_file_path="mkdocs.yml", paths=["*.md"], ) for path in list(glob(os.path.abspath(".") + "/*.md")): assert path in handler._paths @pytest.mark.parametrize( ("expect_change", "extension"), [ (True, "extension.py"), (True, "extension.py:SomeExtension"), (True, "path/to/extension.py"), (True, "path/to/extension.py:SomeExtension"), (True, {"extension.py": {"option": "value"}}), (True, {"extension.py:SomeExtension": {"option": "value"}}), (True, {"path/to/extension.py": {"option": "value"}}), (True, {"path/to/extension.py:SomeExtension": {"option": "value"}}), (False, "/absolute/path/to/extension.py"), (False, "/absolute/path/to/extension.py:SomeExtension"), (False, {"/absolute/path/to/extension.py": {"option": "value"}}), (False, {"/absolute/path/to/extension.py:SomeExtension": {"option": "value"}}), (False, "dot.notation.path.to.extension"), (False, "dot.notation.path.to.pyextension"), (False, {"dot.notation.path.to.extension": {"option": "value"}}), (False, {"dot.notation.path.to.pyextension": {"option": "value"}}), ], ) def test_extension_paths(tmp_path: Path, expect_change: bool, extension: str | dict) -> None: """Assert extension paths are resolved relative to config file.""" handler = get_handler( theme="material", config_file_path=str(tmp_path.joinpath("mkdocs.yml")), ) normalized = handler.normalize_extension_paths([extension])[0] if expect_change: if isinstance(normalized, str) and isinstance(extension, str): assert normalized == str(tmp_path.joinpath(extension)) elif isinstance(normalized, dict) and isinstance(extension, dict): pth, options = next(iter(extension.items())) assert normalized == {str(tmp_path.joinpath(pth)): options} else: raise ValueError("Normalization must not change extension items type") else: assert normalized == extension mkdocstrings-python-handlers-1.8.0/tests/test_rendering.py000066400000000000000000000125121454701760200241030ustar00rootroot00000000000000"""Tests for the `rendering` module.""" from __future__ import annotations import re from dataclasses import dataclass from typing import TYPE_CHECKING, Any import pytest from griffe.collections import ModulesCollection from griffe.tests import temporary_visited_module from mkdocstrings_handlers.python import rendering if TYPE_CHECKING: from markupsafe import Markup @pytest.mark.parametrize( "code", [ "print('Hello')", "aaaaa(bbbbb, ccccc=1) + ddddd.eeeee[ffff] or {ggggg: hhhhh, iiiii: jjjjj}", ], ) def test_format_code(code: str) -> None: """Assert code can be Black-formatted. Parameters: code: Code to format. """ for length in (5, 100): assert rendering.do_format_code(code, length) @pytest.mark.parametrize( ("name", "signature"), [("Class.method", "(param: str = 'hello') -> 'OtherClass'")], ) def test_format_signature(name: Markup, signature: str) -> None: """Assert signatures can be Black-formatted. Parameters: signature: Signature to format. """ for length in (5, 100): assert rendering._format_signature(name, signature, length) @dataclass class _FakeObject: name: str inherited: bool = False @pytest.mark.parametrize( ("names", "filter_params", "expected_names"), [ (["aa", "ab", "ac", "da"], {"filters": [(re.compile("^a[^b]"), True)]}, {"ab", "da"}), (["aa", "ab", "ac", "da"], {"members_list": ["aa", "ab"]}, {"aa", "ab"}), ], ) def test_filter_objects(names: list[str], filter_params: dict[str, Any], expected_names: set[str]) -> None: """Assert the objects filter works correctly. Parameters: names: Names of the objects. filter_params: Parameters passed to the filter function. expected_names: Names expected to be kept. """ objects = {name: _FakeObject(name) for name in names} filtered = rendering.do_filter_objects(objects, **filter_params) # type: ignore[arg-type] filtered_names = {obj.name for obj in filtered} assert set(filtered_names) == set(expected_names) @pytest.mark.parametrize( ("members", "inherited_members", "expected_names"), [ (True, True, {"base", "main"}), (True, False, {"main"}), (True, ["base"], {"base", "main"}), (True, [], {"main"}), (False, True, {"base"}), (False, False, set()), (False, ["base"], {"base"}), (False, [], set()), ([], True, {"base"}), ([], False, set()), ([], ["base"], {"base"}), ([], [], set()), (None, True, {"base", "main"}), (None, False, {"main"}), (None, ["base"], {"base", "main"}), (None, [], {"main"}), (["base"], True, {"base"}), (["base"], False, set()), (["base"], ["base"], {"base"}), (["base"], [], set()), (["main"], True, {"main"}), (["main"], False, {"main"}), (["main"], ["base"], {"base", "main"}), (["main"], [], {"main"}), ], ) def test_filter_inherited_members( members: bool | list[str] | None, inherited_members: bool | list[str], expected_names: list[str], ) -> None: """Test inherited members filtering. Parameters: members: Members option (parametrized). inherited_members: Inherited members option (parametrized). expected_names: The expected result as a list of member names. """ collection = ModulesCollection() with temporary_visited_module( """ class Base: def base(self): ... class Main(Base): def main(self): ... """, modules_collection=collection, ) as module: collection["module"] = module objects = module["Main"].all_members filtered = rendering.do_filter_objects(objects, members_list=members, inherited_members=inherited_members) names = {obj.name for obj in filtered} assert names == expected_names @pytest.mark.parametrize( ("order", "members_list", "expected_names"), [ (rendering.Order.alphabetical, None, ["a", "b", "c"]), (rendering.Order.source, None, ["c", "b", "a"]), (rendering.Order.alphabetical, ["c", "b"], ["c", "b"]), (rendering.Order.source, ["a", "c"], ["a", "c"]), (rendering.Order.alphabetical, [], ["a", "b", "c"]), (rendering.Order.source, [], ["c", "b", "a"]), (rendering.Order.alphabetical, True, ["a", "b", "c"]), (rendering.Order.source, False, ["c", "b", "a"]), ], ) def test_ordering_members(order: rendering.Order, members_list: list[str | None], expected_names: list[str]) -> None: """Assert the objects are correctly ordered. Parameters: order: The order to use (alphabetical or source). members_list: The user specified members list. expected_names: The expected ordered list of object names. """ class Obj: def __init__(self, name: str, lineno: int | None = None, *, is_alias: bool = False) -> None: self.name = name self.lineno = lineno self.alias_lineno = lineno self.is_alias = is_alias members = [Obj("a", 10, is_alias=True), Obj("b", 9, is_alias=False), Obj("c", 8, is_alias=True)] ordered = rendering.do_order_members(members, order, members_list) # type: ignore[arg-type] assert [obj.name for obj in ordered] == expected_names mkdocstrings-python-handlers-1.8.0/tests/test_themes.py000066400000000000000000000024641454701760200234200ustar00rootroot00000000000000"""Tests for the different themes we claim to support.""" from __future__ import annotations import sys from typing import TYPE_CHECKING import pytest if TYPE_CHECKING: from markdown import Markdown from mkdocstrings.plugin import MkdocstringsPlugin @pytest.mark.parametrize( "plugin", [ {"theme": "mkdocs"}, {"theme": "readthedocs"}, {"theme": {"name": "material"}}, ], indirect=["plugin"], ) @pytest.mark.parametrize( "module", [ "mkdocstrings.extension", "mkdocstrings.inventory", "mkdocstrings.loggers", "mkdocstrings.plugin", "mkdocstrings.handlers.base", "mkdocstrings.handlers.rendering", "mkdocstrings_handlers.python", ], ) @pytest.mark.skipif(sys.version_info < (3, 7), reason="material is not installed on Python 3.6") def test_render_themes_templates_python(module: str, plugin: MkdocstringsPlugin, ext_markdown: Markdown) -> None: """Test rendering of a given theme's templates. Parameters: module: Parametrized argument. plugin: Pytest fixture: [tests.conftest.fixture_plugin][]. """ handler = plugin.handlers.get_handler("python") handler._update_env(ext_markdown, plugin.handlers._config) data = handler.collect(module, {}) handler.render(data, {})