././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1756397455.9658778 mkdocstrings_python-1.18.2/CHANGELOG.md0000644000000000000000000020231715054077620014465 0ustar00# 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.18.2](https://github.com/mkdocstrings/python/releases/tag/1.18.2) - 2025-08-28 [Compare with 1.18.1](https://github.com/mkdocstrings/python/compare/1.18.1...1.18.2) ### Bug Fixes - Normalize spaces to underscores when passing object to rendering context using its kind as key ([6f79be0](https://github.com/mkdocstrings/python/commit/6f79be0ea83522021e16e5d401209e58576ef93a) by Timothée Mazzucotelli). [Issue-mkdocstrings-791](https://github.com/mkdocstrings/mkdocstrings/issues/791) ## [1.18.1](https://github.com/mkdocstrings/python/releases/tag/1.18.1) - 2025-08-28 [Compare with 1.18.0](https://github.com/mkdocstrings/python/compare/1.18.0...1.18.1) ### Bug Fixes - Don't show implementation signature of `__init__` method when `overloads_only` is true and it is merged into the class ([9ef620f](https://github.com/mkdocstrings/python/commit/9ef620f2b1ae80b3711a2e84ab12d7d2c4a2dbdd) by Timothée Mazzucotelli). [Issue-308](https://github.com/mkdocstrings/python/issues/308) ## [1.18.0](https://github.com/mkdocstrings/python/releases/tag/1.18.0) - 2025-08-26 [Compare with 1.17.0](https://github.com/mkdocstrings/python/compare/1.17.0...1.18.0) ### Features - Support PEP 695 generics ([dc8c3ad](https://github.com/mkdocstrings/python/commit/dc8c3adb23b37add6601de9e74085f76e5fc9ee5) by Victor Westerhuis). [PR-221](https://github.com/mkdocstrings/python/pull/221), Co-authored-by: Timothée Mazzucotelli ### Bug Fixes - Increase maximum recursion limit in case of deeply nested ASTs (rare occurrence) ([6004ccf](https://github.com/mkdocstrings/python/commit/6004ccf3576c7a20e21c880bb2235b7b426ba382) by Timothée Mazzucotelli). [Issue-griffe-402](https://github.com/mkdocstrings/griffe/issues/402) ## [1.17.0](https://github.com/mkdocstrings/python/releases/tag/1.17.0) - 2025-08-14 [Compare with 1.16.12](https://github.com/mkdocstrings/python/compare/1.16.12...1.17.0) ### Features - Support new Griffe parsing options `warn_missing_types` and `warnings` ([0e3bdb8](https://github.com/mkdocstrings/python/commit/0e3bdb857b5ede3e15aa7a9b8b87b33f68889c9e) by Timothée Mazzucotelli). [Issue-mkdocstrings-437](https://github.com/mkdocstrings/mkdocstrings/issues/437) - Add `skip_local_inventory` option to prevent objects from being registered in the local objects inventory ([e82c24f](https://github.com/mkdocstrings/python/commit/e82c24f17513fba4cff22e90f0a82c00a01a077d) by Bartosz Sławecki). [Issue-296](https://github.com/mkdocstrings/python/issues/296), [Issue-mkdocstrings-671](https://github.com/mkdocstrings/mkdocstrings/issues/671), [PR-297](https://github.com/mkdocstrings/python/pull/297) - Support hiding attribute values ([6cf34b9](https://github.com/mkdocstrings/python/commit/6cf34b9882e20d9147a6481e672ae09989a27796) by Bartosz Sławecki). Issue-292: #292, PR-293: #293 - Support hiding implementation signature (showing overload only) ([d3b35e1](https://github.com/mkdocstrings/python/commit/d3b35e17384901e7280b8b6926f10fb033480358) by Bartosz Sławecki). [Issue-213](https://github.com/mkdocstrings/python/issues/213), [PR-286](https://github.com/mkdocstrings/python/pull/286) ### Code Refactoring - Deprecate `locale` option in favor of mkdocstrings' ([17f71ba](https://github.com/mkdocstrings/python/commit/17f71babf11081869478b21b2bde1a33fc97be41) by Timothée Mazzucotelli). [PR-288](https://github.com/mkdocstrings/python/pull/288) ## [1.16.12](https://github.com/mkdocstrings/python/releases/tag/1.16.12) - 2025-06-03 [Compare with 1.16.11](https://github.com/mkdocstrings/python/compare/1.16.11...1.16.12) ### Bug Fixes - Only replace CSS class in first *highlighting* span ([d57740f](https://github.com/mkdocstrings/python/commit/d57740f874f056fb3ba1c6013ad04227df0f0af8) by Timothée Mazzucotelli). [Issue-281](https://github.com/mkdocstrings/python/issues/281) ## [1.16.11](https://github.com/mkdocstrings/python/releases/tag/1.16.11) - 2025-05-24 [Compare with 1.16.10](https://github.com/mkdocstrings/python/compare/1.16.10...1.16.11) ### Bug Fixes - Fix highlighting for signature with known special names like `__init__` ([7f95686](https://github.com/mkdocstrings/python/commit/7f956868f93a766346455fedb296c26787894d5c) by Timothée Mazzucotelli). [Issue-mkdocstrings-757](https://github.com/mkdocstrings/mkdocstrings/issues/757) - Use default font-size for parameter headings ([0a35b20](https://github.com/mkdocstrings/python/commit/0a35b20a6050a28ba8492d93e5f9940a69462ce3) by Timothée Mazzucotelli). [Issue-mkdocstrings-697](https://github.com/mkdocstrings/mkdocstrings/issues/697) - Prevent uppercasing H5 titles (by Material for MkDocs) ([ba66969](https://github.com/mkdocstrings/python/commit/ba669697daad5067ea5db3fdf8a2d5ba2f966b25) by Timothée Mazzucotelli). [Issue-mkdocstrings-697](https://github.com/mkdocstrings/mkdocstrings/issues/697), [Issue-276](https://github.com/mkdocstrings/python/issues/276) - Use configured heading even when signature is not separated ([096960a](https://github.com/mkdocstrings/python/commit/096960abd79831d6fd45e2a7962dfd2bd49e4edd) by Timothée Mazzucotelli). [Issue-mkdocstrings-767](https://github.com/mkdocstrings/mkdocstrings/issues/767), [PR-278](https://github.com/mkdocstrings/python/pull/278) - Render attribute names without full path in ToC ([d4e618a](https://github.com/mkdocstrings/python/commit/d4e618ab794747b84dced848b1be824639fea2b8) by David Lee). [Issue-271](https://github.com/mkdocstrings/python/issues/271), [PR-272](https://github.com/mkdocstrings/python/pull/272) ## [1.16.10](https://github.com/mkdocstrings/python/releases/tag/1.16.10) - 2025-04-03 [Compare with 1.16.9](https://github.com/mkdocstrings/python/compare/1.16.9...1.16.10) ### Bug Fixes - Fix inventory `base_url` being ignored ([8870eb9](https://github.com/mkdocstrings/python/commit/8870eb9af837666f59f96149c67c849e02f7ee25) by Stefan Mejlgaard). [Issue-268](https://github.com/mkdocstrings/python/issues/268), [PR-269](https://github.com/mkdocstrings/python/pull/269) ## [1.16.9](https://github.com/mkdocstrings/python/releases/tag/1.16.9) - 2025-04-03 [Compare with 1.16.8](https://github.com/mkdocstrings/python/compare/1.16.8...1.16.9) ### Bug Fixes - Use `toc_label` option in a few missing places ([337b46b](https://github.com/mkdocstrings/python/commit/337b46be912ff69e70b398bb252c8217c917db0a) by Timothée Mazzucotelli). [Issue-267](https://github.com/mkdocstrings/python/discussions/267) ## [1.16.8](https://github.com/mkdocstrings/python/releases/tag/1.16.8) - 2025-03-24 [Compare with 1.16.7](https://github.com/mkdocstrings/python/compare/1.16.7...1.16.8) ### Bug Fixes - Prevent infinite recursion by detecting parent-member cycles ([f3917e9](https://github.com/mkdocstrings/python/commit/f3917e9dd50ca7f94d0dd22b6e4e11885b4617e7) by Timothée Mazzucotelli). [Issue-griffe-368](https://github.com/mkdocstrings/griffe/issues/368) ### Code Refactoring - Prepare feature for ordering by `__all__` value ([bfb5b30](https://github.com/mkdocstrings/python/commit/bfb5b303f4ea2187c15bccc688f7eba25e7edfcc) by Timothée Mazzucotelli). [Issue-219](https://github.com/mkdocstrings/python/issues/219) - Sort objects without line numbers last instead of first ([681afb1](https://github.com/mkdocstrings/python/commit/681afb146225d98350a8eb2178aab07aec95fe6b) by Timothée Mazzucotelli). ## [1.16.7](https://github.com/mkdocstrings/python/releases/tag/1.16.7) - 2025-03-20 [Compare with 1.16.6](https://github.com/mkdocstrings/python/compare/1.16.6...1.16.7) ### Code Refactoring - Prepare `public` filtering method feature ([fde2019](https://github.com/mkdocstrings/python/commit/fde20191cab20f39d9e5e729a95cdfa3390b8f1f) by Timothée Mazzucotelli). [Issue-78](https://github.com/mkdocstrings/python/issues/78) ## [1.16.6](https://github.com/mkdocstrings/python/releases/tag/1.16.6) - 2025-03-18 [Compare with 1.16.5](https://github.com/mkdocstrings/python/compare/1.16.5...1.16.6) ### Deprecations Importing from submodules is now deprecated: the public API is fully exposed under the top-level `mkdocstrings_handler.python` module. ### Bug Fixes - Add back default compiled filters (regression) ([2d83900](https://github.com/mkdocstrings/python/commit/2d83900c9e258399c90ecbac350ad03ff5d8f311) by Timothée Mazzucotelli). [Issue-264](https://github.com/mkdocstrings/python/issues/264) ### Code Refactoring - Start logging warnings instead of info messages about deprecated use of templates ([7606f33](https://github.com/mkdocstrings/python/commit/7606f33559ced6962ecf9a1bc9aa76f24d87f515) by Timothée Mazzucotelli). - Move modules into internal folder, expose API in top-level module ([93a68d0](https://github.com/mkdocstrings/python/commit/93a68d0d7afce38c78a8264189cfa812d737666c) by Timothée Mazzucotelli). ## [1.16.5](https://github.com/mkdocstrings/python/releases/tag/1.16.5) - 2025-03-10 [Compare with 1.16.4](https://github.com/mkdocstrings/python/compare/1.16.4...1.16.5) ### Code Refactoring - Prepare backlinks support ([56bf627](https://github.com/mkdocstrings/python/commit/56bf627b9483a12228b769ae4690b84733061ea5) by Timothée Mazzucotelli). [Issue-153](https://github.com/mkdocstrings/python/issues/153), [PR-252](https://github.com/mkdocstrings/python/pull/252) ## [1.16.4](https://github.com/mkdocstrings/python/releases/tag/1.16.4) - 2025-03-10 [Compare with 1.16.3](https://github.com/mkdocstrings/python/compare/1.16.3...1.16.4) ### Bug Fixes - Fix de-duplication of summary sections ([dc46ac9](https://github.com/mkdocstrings/python/commit/dc46ac9b4cfc642decd153dceb62e9f45c5c750e) by Timothée Mazzucotelli). ## [1.16.3](https://github.com/mkdocstrings/python/releases/tag/1.16.3) - 2025-03-08 [Compare with 1.16.2](https://github.com/mkdocstrings/python/compare/1.16.2...1.16.3) ### Build - Depend on mkdocstrings 0.28.3 ([9fa4f16](https://github.com/mkdocstrings/python/commit/9fa4f1636af240bb695661b7172f052cb11e0ec9) by Timothée Mazzucotelli). ### Bug Fixes - De-duplicate summary sections ([a657d07](https://github.com/mkdocstrings/python/commit/a657d07499eb82d22337c169aa86b1cdd85543fa) by Timothée Mazzucotelli). [Issue-134](https://github.com/mkdocstrings/python/issues/134) ### Code Refactoring - Import from top-level `mkdocstrings` module ([da2ba13](https://github.com/mkdocstrings/python/commit/da2ba13b1367ce107416d08f382fb9f2384c015c) by Timothée Mazzucotelli). ## [1.16.2](https://github.com/mkdocstrings/python/releases/tag/1.16.2) - 2025-02-24 [Compare with 1.16.1](https://github.com/mkdocstrings/python/compare/1.16.1...1.16.2) ### Build - Depend on mkdocs-autorefs >= 1.4 and mkdocstrings >= 0.28.2 ([ea1ab49](https://github.com/mkdocstrings/python/commit/ea1ab498be836c94eb695ace05c41357b12f2c95) by Timothée Mazzucotelli). ## [1.16.1](https://github.com/mkdocstrings/python/releases/tag/1.16.1) - 2025-02-18 [Compare with 1.16.0](https://github.com/mkdocstrings/python/compare/1.16.0...1.16.1) ### Bug Fixes - Give precedence to user-provided paths when they are already listed in `sys.path` ([0f497d1](https://github.com/mkdocstrings/python/commit/0f497d185ba1860c61555803bfc4b311a410bd39) by Timothée Mazzucotelli). [Issue-248](https://github.com/mkdocstrings/python/discussions/248) ## [1.16.0](https://github.com/mkdocstrings/python/releases/tag/1.16.0) - 2025-02-17 [Compare with 1.15.1](https://github.com/mkdocstrings/python/compare/1.15.1...1.16.0) ### Features - Add option to show/hide overloads ([4a5ee10](https://github.com/mkdocstrings/python/commit/4a5ee10c65de28b7921a56ef2c222d2f3417edaa) by Pete Stenger). [PR-250](https://github.com/mkdocstrings/python/pull/250) ## [1.15.1](https://github.com/mkdocstrings/python/releases/tag/1.15.1) - 2025-02-17 [Compare with 1.15.0](https://github.com/mkdocstrings/python/compare/1.15.0...1.15.1) ### Bug Fixes - Unwrap `Annotated` regardless of `signature_crossrefs` ([d809f1a](https://github.com/mkdocstrings/python/commit/d809f1a9e6a6f4eaf6fe4a18c2ec0e69e5716a12) by Timothée Mazzucotelli). [Issue-249](https://github.com/mkdocstrings/python/issues/249) ## [1.15.0](https://github.com/mkdocstrings/python/releases/tag/1.15.0) - 2025-02-11 [Compare with 1.14.6](https://github.com/mkdocstrings/python/compare/1.14.6...1.15.0) ### Features - Support cross-referencing constructor parameters in instance attribute values ([f07bf58](https://github.com/mkdocstrings/python/commit/f07bf58a7358dea106032c7da27098e7617eefa0) by Timothée Mazzucotelli). ## [1.14.6](https://github.com/mkdocstrings/python/releases/tag/1.14.6) - 2025-02-07 [Compare with 1.14.5](https://github.com/mkdocstrings/python/compare/1.14.5...1.14.6) ### Bug Fixes - Catch alias resolution errors when getting aliases for an identifier ([0aaa260](https://github.com/mkdocstrings/python/commit/0aaa260139afe2e3ab85d62224c90a389df64978) by Timothée Mazzucotelli). [Issue-358](https://github.com/mkdocstrings/griffe/discussions/358) ### Code Refactoring - Improve translations for Simplified Chinese and Japanese ([753a0df](https://github.com/mkdocstrings/python/commit/753a0df8f91f1cf42fb7e56b7fdd312b2bd652ab) by Zhikang Yan). [PR-244](https://github.com/mkdocstrings/python/pull/244) ## [1.14.5](https://github.com/mkdocstrings/python/releases/tag/1.14.5) - 2025-02-05 [Compare with 1.14.4](https://github.com/mkdocstrings/python/compare/1.14.4...1.14.5) ### Bug Fixes - Remove type from property docstring summary in summary sections ([15f2cd4](https://github.com/mkdocstrings/python/commit/15f2cd48b79a1f062086a47ea0c6bc52d89786d8) by Uchechukwu Orji). [PR-242](https://github.com/mkdocstrings/python/pull/242) ## [1.14.4](https://github.com/mkdocstrings/python/releases/tag/1.14.4) - 2025-02-04 [Compare with 1.14.3](https://github.com/mkdocstrings/python/compare/1.14.3...1.14.4) ### Bug Fixes - Deactivate Pydantic validation on Python 3.9 is `eval-type-backport` is not available (for modern typing syntax support) ([0de0e5e](https://github.com/mkdocstrings/python/commit/0de0e5e57f8f22e039b0d19aad6341ce7ab3da9f) by Timothée Mazzucotelli). [Issue-241](https://github.com/mkdocstrings/python/issues/241) ## [1.14.3](https://github.com/mkdocstrings/python/releases/tag/1.14.3) - 2025-02-04 [Compare with 1.14.2](https://github.com/mkdocstrings/python/compare/1.14.2...1.14.3) ### Bug Fixes - Let dataclass implement `__init__` method, set extra fields in `get_options` ([477b9e4](https://github.com/mkdocstrings/python/commit/477b9e447ef9717c6edcb14bd4c53f9cacc555b8) by Timothée Mazzucotelli). ## [1.14.2](https://github.com/mkdocstrings/python/releases/tag/1.14.2) - 2025-02-03 [Compare with 1.14.1](https://github.com/mkdocstrings/python/compare/1.14.1...1.14.2) ### Bug Fixes - Deactivate Pydantic logic if v1 is installed instead of v2 ([c5ecd70](https://github.com/mkdocstrings/python/commit/c5ecd702b04417fa3d862806d608ea627b2e8ed9) by Timothée Mazzucotelli). [Issue-240](https://github.com/mkdocstrings/python/issues/240) ## [1.14.1](https://github.com/mkdocstrings/python/releases/tag/1.14.1) - 2025-02-03 [Compare with 1.14.0](https://github.com/mkdocstrings/python/compare/1.14.0...1.14.1) ### Bug Fixes - Fix type errors with options during collection and docstring parsing ([15ca6d8](https://github.com/mkdocstrings/python/commit/15ca6d8cbe8187ae2938b3cc3a6134d10c94a3aa) by Timothée Mazzucotelli). ## [1.14.0](https://github.com/mkdocstrings/python/releases/tag/1.14.0) - 2025-02-03 [Compare with 1.13.0](https://github.com/mkdocstrings/python/compare/1.13.0...1.14.0) ### Features - Add `heading` and `toc_label` options ([7cabacf](https://github.com/mkdocstrings/python/commit/7cabacf13735dbc5066793baf5820d61cd342dc8) by Yann Van Crombrugge). [Issue-mkdocstrings-725](https://github.com/mkdocstrings/mkdocstrings/issues/725), [PR-236](https://github.com/mkdocstrings/python/pull/236) - Add `force_inspection` option to force dynamic analysis ([83823be](https://github.com/mkdocstrings/python/commit/83823be2146d6a2ecedc5fe9c0cfd84098d780ca) by Uchechukwu Orji). [Issue-94](https://github.com/mkdocstrings/python/issues/94), [PR-231](https://github.com/mkdocstrings/python/pull/231) ### Code Refactoring - Use dataclasses for configuration/options and automate schema generation ([5ebeda6](https://github.com/mkdocstrings/python/commit/5ebeda6fce1b1bc7cb3f5e27a5a90ac394a3de0c) by Timothée Mazzucotelli). ## [1.13.0](https://github.com/mkdocstrings/python/releases/tag/1.13.0) - 2024-12-26 [Compare with 1.12.2](https://github.com/mkdocstrings/python/compare/1.12.2...1.13.0) ### Features - Allow using Ruff to format signatures and attribute values ([d67215c](https://github.com/mkdocstrings/python/commit/d67215c976938ef1e169f16dd0b6166067ebd7bc) by dm). [PR-216](https://github.com/mkdocstrings/python/pull/216) ### Bug Fixes - Respect `show_signature_annotations` option for attribute signatures in headings ([e93d166](https://github.com/mkdocstrings/python/commit/e93d166a14d0944d30ff2f28f21f2262ac396bff) by Timothée Mazzucotelli). [Issue-griffe-pydantic#9](https://github.com/mkdocstrings/griffe-pydantic/issues/9) - Handle `__init__` overloads when merging into class ([af6fab3](https://github.com/mkdocstrings/python/commit/af6fab31142204872ace716392dcb314b2cb5d0f) by Timothée Mazzucotelli). [Issue-212](https://github.com/mkdocstrings/python/issues/212) - Actually check if a module is public when rendering auto-generated summary table for modules ([3bf55b2](https://github.com/mkdocstrings/python/commit/3bf55b22ce9a841242c55b2efcedbd8f3a99ccc9) by Timothée Mazzucotelli). [Issue-203](https://github.com/mkdocstrings/python/issues/203) - Never render line numbers for signatures and attribute values ([a669f1c](https://github.com/mkdocstrings/python/commit/a669f1caefbd54305cc4610bdd57a529aa1208cf) by Timothée Mazzucotelli). [Issue-192](https://github.com/mkdocstrings/python/issues/192) - Respect highlight's `linenums` config for `pycon` examples in docstrings ([53eb82a](https://github.com/mkdocstrings/python/commit/53eb82a21bbcaa959306e909bf0d4ac468f87580) by Timothée Mazzucotelli). [Related-to-#192](https://github.com/mkdocstrings/python/issues/192) - Fix normalization of extension paths on the annoying operating system and Python 3.13 ([101a6dc](https://github.com/mkdocstrings/python/commit/101a6dc428da59a512da617a0a2453f2b6ef4387) by Timothée Mazzucotelli). - Don't merge parent `__init__` docstring into class docstring if such inherited method wasn't selected through the `inherited_members` configuration option ([6c5b5c3](https://github.com/mkdocstrings/python/commit/6c5b5c341940af9425b3de0672ac400794b3f6e5) by Timothée Mazzucotelli). [Issue-189](https://github.com/mkdocstrings/python/issues/189) ### Code Refactoring - Render `*` and `**` outside of cross-references in signatures ([c4506f0](https://github.com/mkdocstrings/python/commit/c4506f080e0c75cd32d6512c80f5016e82fc12bc) by Timothée Mazzucotelli). [Needed-for-PR-216](https://github.com/mkdocstrings/python/pull/216) ## [1.12.2](https://github.com/mkdocstrings/python/releases/tag/1.12.2) - 2024-10-19 [Compare with 1.12.1](https://github.com/mkdocstrings/python/compare/1.12.1...1.12.2) ### Bug Fixes - Always render cross-references outside of signatures ([73f11dc](https://github.com/mkdocstrings/python/commit/73f11dcc584a672af7e17738cba08a50f119176a) by Timothée Mazzucotelli). [Issue-mkdocstrings#700](https://github.com/mkdocstrings/mkdocstrings/issues/700) ## [1.12.1](https://github.com/mkdocstrings/python/releases/tag/1.12.1) - 2024-10-14 [Compare with 1.12.0](https://github.com/mkdocstrings/python/compare/1.12.0...1.12.1) ### Bug Fixes - Don't escape parameter default values ([9dee4d4](https://github.com/mkdocstrings/python/commit/9dee4d4f8e1258e99c19dc7b2b18d3e9090de79b) by Timothée Mazzucotelli). [Issue-191](https://github.com/mkdocstrings/python/issues/191) ## [1.12.0](https://github.com/mkdocstrings/python/releases/tag/1.12.0) - 2024-10-12 [Compare with 1.11.1](https://github.com/mkdocstrings/python/compare/1.11.1...1.12.0) ### Build - Drop support for Python 3.8 ([6615c91](https://github.com/mkdocstrings/python/commit/6615c91cdc035bc0c2fdd12f3952ff84f5e1c04e) by Timothée Mazzucotelli). ### Features - Auto-summary of members ([7f9757d](https://github.com/mkdocstrings/python/commit/7f9757d1584555edebc56f1aefe6cc8242e6c8bb) by Timothée Mazzucotelli). - Render function overloads ([0f2c25c](https://github.com/mkdocstrings/python/commit/0f2c25c9ed7f6c5c93ff13df214f02edfd3a4cb1) by Timothée Mazzucotelli). - Parameter headings, more automatic cross-references ([0176b83](https://github.com/mkdocstrings/python/commit/0176b83f21ae02d345489c93cca3baf51f8bc58c) by Timothée Mazzucotelli). ### Code Refactoring - Declare default CSS symbol colors under :host as well ([3b9dba2](https://github.com/mkdocstrings/python/commit/3b9dba2709a8668e379c6ce1536cb1714971b3f4) by James McDonnell). [PR-186](https://github.com/mkdocstrings/python/pull/186) ## [1.11.1](https://github.com/mkdocstrings/python/releases/tag/1.11.1) - 2024-09-03 [Compare with 1.11.0](https://github.com/mkdocstrings/python/compare/1.11.0...1.11.1) ### Code Refactoring - Prepare `relative_crossrefs` and `scoped_crossrefs` insiders features ([dd8b014](https://github.com/mkdocstrings/python/commit/dd8b014a8ab3decc31d4b08bc22fe68577e1a02c) by Timothée Mazzucotelli). ## [1.11.0](https://github.com/mkdocstrings/python/releases/tag/1.11.0) - 2024-09-03 [Compare with 1.10.9](https://github.com/mkdocstrings/python/compare/1.10.9...1.11.0) ### Features - Hook into autorefs to provide context around cross-ref errors ([bb4be5b](https://github.com/mkdocstrings/python/commit/bb4be5be1b85be50f46c7889231a2d4a3bd05165) by Timothée Mazzucotelli). ## [1.10.9](https://github.com/mkdocstrings/python/releases/tag/1.10.9) - 2024-08-30 [Compare with 1.10.8](https://github.com/mkdocstrings/python/compare/1.10.8...1.10.9) ### Build - Explicitly depend on mkdocs-autorefs to be able to specify lower bound ([2299ab5](https://github.com/mkdocstrings/python/commit/2299ab55641585d65babe0e116a6465b4736dcd9) by Timothée Mazzucotelli). ### Code Refactoring - Use new autorefs syntax ([68cb72f](https://github.com/mkdocstrings/python/commit/68cb72f62253f54146ece621345b36c90d712913) by Timothée Mazzucotelli). ## [1.10.8](https://github.com/mkdocstrings/python/releases/tag/1.10.8) - 2024-08-14 [Compare with 1.10.7](https://github.com/mkdocstrings/python/compare/1.10.7...1.10.8) ### Build - Depend on Griffe 0.49 ([a87dcad](https://github.com/mkdocstrings/python/commit/a87dcad36065dc3171512e166ec632ee3e5b0a64) by Timothée Mazzucotelli). ## [1.10.7](https://github.com/mkdocstrings/python/releases/tag/1.10.7) - 2024-07-25 [Compare with 1.10.6](https://github.com/mkdocstrings/python/compare/1.10.6...1.10.7) ### Packaging - Include tests and all relevant files for downstream packaging in source distribution ## [1.10.6](https://github.com/mkdocstrings/python/releases/tag/1.10.6) - 2024-07-25 [Compare with 1.10.5](https://github.com/mkdocstrings/python/compare/1.10.5...1.10.6) ### Bug Fixes - Fix condition to display members (check all members, not just non-inherited ones) ([3d838a9](https://github.com/mkdocstrings/python/commit/3d838a96f77fa128cd6f2afa5ed0cb151ab225fd) by Timothée Mazzucotelli). ### Code Refactoring - Update code for Griffe 0.48 (removing deprecation warnings) ([eff10cc](https://github.com/mkdocstrings/python/commit/eff10ccf0fa1b2e73df912048a15c2d6406a2c8b) by Timothée Mazzucotelli). [Issue-173](https://github.com/mkdocstrings/python/issues/173) ## [1.10.5](https://github.com/mkdocstrings/python/releases/tag/1.10.5) - 2024-06-19 [Compare with 1.10.4](https://github.com/mkdocstrings/python/compare/1.10.4...1.10.5) ### Bug Fixes - Mix both previous checks for displaying objects: not imported or public ([587963b](https://github.com/mkdocstrings/python/commit/587963ba53f765c9d7eefbc2fb80bdbb11164850) by Timothée Mazzucotelli). [Issue-294](https://github.com/mkdocstrings/griffe/issues/294) ## [1.10.4](https://github.com/mkdocstrings/python/releases/tag/1.10.4) - 2024-06-18 [Compare with 1.10.3](https://github.com/mkdocstrings/python/compare/1.10.3...1.10.4) ### Code Refactoring - Only filter out imported objects instead of non-public ones after applying filters ([e2f4b35](https://github.com/mkdocstrings/python/commit/e2f4b35d29eca6f68afbd2e728ef7542a2abc992) by Timothée Mazzucotelli). [Issue-mkdocstrings/griffe-294](https://github.com/mkdocstrings/griffe/issues/294) - Update code for Griffe 0.46 to avoid deprecation warnings ([321b407](https://github.com/mkdocstrings/python/commit/321b407eb95195c44f3cf34d780784e0d6751998) by Timothée Mazzucotelli). - Change `load_external_modules` default value to `None` to support new default mode in Griffe ([ae5896c](https://github.com/mkdocstrings/python/commit/ae5896c1604e9089162d0d63ec97a510a6bcef89) by Timothée Mazzucotelli). ## [1.10.3](https://github.com/mkdocstrings/python/releases/tag/1.10.3) - 2024-05-22 [Compare with 1.10.2](https://github.com/mkdocstrings/python/compare/1.10.2...1.10.3) ### Bug Fixes - Don't crash when rendering the source of an object whose lineno is none ([64df00b](https://github.com/mkdocstrings/python/commit/64df00b9b757e9642d65cf425d32f5a2e0d75f38) by Timothée Mazzucotelli). [Issue-163](https://github.com/mkdocstrings/python/issues/163) ## [1.10.2](https://github.com/mkdocstrings/python/releases/tag/1.10.2) - 2024-05-16 [Compare with 1.10.1](https://github.com/mkdocstrings/python/compare/1.10.1...1.10.2) ### Bug Fixes - Actually make use of custom .html.jinja templates ([5668abb](https://github.com/mkdocstrings/python/commit/5668abba15b13b86fe67f70f6b4004b7b1feeb4f) by Timothée Mazzucotelli). ## [1.10.1](https://github.com/mkdocstrings/python/releases/tag/1.10.1) - 2024-05-14 [Compare with 1.10.0](https://github.com/mkdocstrings/python/compare/1.10.0...1.10.1) ### Build - Depend on mkdocstrings 0.25 which adds support for parameter `once` when logging messages ([2bc156b](https://github.com/mkdocstrings/python/commit/2bc156bd6f231ae13066651f4490d1e9c2ce3ca2) by Timothée Mazzucotelli). ### Code Refactoring - Set handler's name ([a71ab12](https://github.com/mkdocstrings/python/commit/a71ab12c8e52efe76e5c0a5e54065926a47cc0d2) by Timothée Mazzucotelli). - Update `*.html` top-level templates to extend the `*.html.jinja` base templates ([a8c540e](https://github.com/mkdocstrings/python/commit/a8c540e95693e8500da884c32ad159b3bbaaa7ba) by Timothée Mazzucotelli). [Issue-151](https://github.com/mkdocstrings/python/issues/151) - Update `*.html` base templates to extend their `*.html.jinja` counterpart, while overriding the `logs` block to issue a logging message (info) stating that extending `*.html` templates is deprecated ([e6f1b9c](https://github.com/mkdocstrings/python/commit/e6f1b9caf13754eca9dbb2f112727bef50876ed7) by Timothée Mazzucotelli). [Issue-151](https://github.com/mkdocstrings/python/issues/151) - Add `*.html.jinja` top-level (overridable) templates, extending their base counterpart ([7c14924](https://github.com/mkdocstrings/python/commit/7c14924c406d7b5f4f1c22d03019d4c566018d2d) by Timothée Mazzucotelli). [Issue-151](https://github.com/mkdocstrings/python/issues/151) - Add `*.html.jinja` base templates, which are copies of `*.html` templates, with an additional `logs` block, and using the updated `get_template` filter ([eced9a5](https://github.com/mkdocstrings/python/commit/eced9a54fc8a559b686cb1b1180a0d2e04ba452d) by Timothée Mazzucotelli). [Issue-151](https://github.com/mkdocstrings/python/issues/151) - Update `get_template` filter to support both `*.html` and `*.html.jinja` templates, logging a message (info) when `*.html` templates are overridden by users ([3546fd7](https://github.com/mkdocstrings/python/commit/3546fd70b2d4e45f77b166b2e67c333acc8af0d2) by Timothée Mazzucotelli). [Issue-151](https://github.com/mkdocstrings/python/issues/151) - Log a warning when base templates are overridden ([26e3d66](https://github.com/mkdocstrings/python/commit/26e3d66f5334a5aaff75bda030afe6dfa1cc94d7) by Timothée Mazzucotelli). [Issue-151](https://github.com/mkdocstrings/python/issues/151) ## [1.10.0](https://github.com/mkdocstrings/python/releases/tag/1.10.0) - 2024-04-19 [Compare with 1.9.2](https://github.com/mkdocstrings/python/compare/1.9.2...1.10.0) ### Features - Add CSS classes `doc-section-title` and `doc-section-item` in docstring sections ([d6e1d68](https://github.com/mkdocstrings/python/commit/d6e1d68c099e61c3bd6d93e583708335d84158f5) by Timothée Mazzucotelli). [Issue-17](https://github.com/mkdocstrings/python/issues/17) ### Bug Fixes - Render enumeration instance name instead of just "value", allowing proper cross-reference ([11d81d8](https://github.com/mkdocstrings/python/commit/11d81d8e056b7c074eb3a1c47606867156a338fa) by Timothée Mazzucotelli). [Issue-124](https://github.com/mkdocstrings/python/issues/124) ## [1.9.2](https://github.com/mkdocstrings/python/releases/tag/1.9.2) - 2024-04-02 [Compare with 1.9.1](https://github.com/mkdocstrings/python/compare/1.9.1...1.9.2) ### Dependencies - Remove cap on Python-Markdown 3.6 now that ToC labels are fixed by mkdocstrings ([0c1e2c1](https://github.com/mkdocstrings/python/commit/0c1e2c15b2497d99974cbb9bd68f25056bb8451b) by Timothée Mazzucotelli). ## [1.9.1](https://github.com/mkdocstrings/python/releases/tag/1.9.1) - 2024-04-02 [Compare with 1.9.0](https://github.com/mkdocstrings/python/compare/1.9.0...1.9.1) ### Bug Fixes - Don't try loading packages from relative paths ([bd73497](https://github.com/mkdocstrings/python/commit/bd7349714059afb1295e743dbc82380fa797a032) by Timothée Mazzucotelli). [Issue-145](https://github.com/mkdocstrings/python/issues/145) ### Code Refactoring - Allow first name in a separate signature to be highlighted as a function name ([f798a1e](https://github.com/mkdocstrings/python/commit/f798a1e19dbac548420dcbe1172e9a49232b615b) by Timothée Mazzucotelli). - Maintain original Pygments color for cross-refs in signatures ([7c8b885](https://github.com/mkdocstrings/python/commit/7c8b885fa2b704e719016acb35791723ea3a496a) by Timothée Mazzucotelli). ## [1.9.0](https://github.com/mkdocstrings/python/releases/tag/1.9.0) - 2024-03-13 [Compare with 1.8.0](https://github.com/mkdocstrings/python/compare/1.8.0...1.9.0) ### Dependencies - Add upper bound on Python-Markdown 3.6 to temporarily prevent breaking changes ([cd93ee3](https://github.com/mkdocstrings/python/commit/cd93ee31418a2752667d43bb5a05d22284522c24) by Timothée Mazzucotelli). ### Features - Add `show_labels` option to show/hide labels ([eaf9b82](https://github.com/mkdocstrings/python/commit/eaf9b8240069f7369f401fe048892043c8b173d3) by Viicos). [Issue #120](https://github.com/mkdocstrings/python/issues/120), [PR #130](https://github.com/mkdocstrings/python/pull/130) - Add option to search for stubs packages ([0c6aa32](https://github.com/mkdocstrings/python/commit/0c6aa323c9e57b8348765a5daa11c79d0c5edb07) by Romain). [PR #128](https://github.com/mkdocstrings/python/pull/128), PR griffe#221: : https://github.com/mkdocstrings/griffe/pull/221 ### Code Refactoring - Mark all Jinja blocks as scoped ([548bdad](https://github.com/mkdocstrings/python/commit/548bdaddd66ffc99b3b9a5a62228a2ff4ff0dd00) by Timothée Mazzucotelli). ## [1.8.0](https://github.com/mkdocstrings/python/releases/tag/1.8.0) - 2024-01-08 [Compare with 1.7.5](https://github.com/mkdocstrings/python/compare/1.7.5...1.8.0) ### Features - Release Insiders features of the $500/month funding goal ([bd30106](https://github.com/mkdocstrings/python/commit/bd301061fe9c647f9b91c2c9b4baa784c304eca7) by Timothée Mazzucotelli). The features and projects related to *mkdocstrings-python* are: - [Cross-references for type annotations in signatures](https://mkdocstrings.github.io/python/usage/configuration/signatures/#signature_crossrefs) - [Symbol types in headings and table of contents](https://mkdocstrings.github.io/python/usage/configuration/headings/#show_symbol_type_toc) - [`griffe-inherited-docstrings`](https://mkdocstrings.github.io/griffe-inherited-docstrings/), a Griffe extension for inheriting docstrings - [`griffe2md`](https://mkdocstrings.github.io/griffe2md/), a tool to output API docs to Markdown using Griffe See the complete list of features and projects here: https://pawamoy.github.io/insiders/#500-plasmavac-user-guide. ## [1.7.5](https://github.com/mkdocstrings/python/releases/tag/1.7.5) - 2023-11-21 [Compare with 1.7.4](https://github.com/mkdocstrings/python/compare/1.7.4...1.7.5) ### Bug Fixes - Add missing translations (fallback theme) for ReadTheDocs ([2fb6513](https://github.com/mkdocstrings/python/commit/2fb651304d0a80fa9d6a8c77c16b3004bda22972) by Timothée Mazzucotelli). [Issue #115](https://github.com/mkdocstrings/python/issues/115) ## [1.7.4](https://github.com/mkdocstrings/python/releases/tag/1.7.4) - 2023-11-12 [Compare with 1.7.3](https://github.com/mkdocstrings/python/compare/1.7.3...1.7.4) ### Bug Fixes - Make extension paths relative to config file ([5035e92](https://github.com/mkdocstrings/python/commit/5035e9269fe11664fd25e438ac8f746721b3de0a) by Waylan Limberg). [PR #112](https://github.com/mkdocstrings/python/pull/112), Co-authored-by: Timothée Mazzucotelli ### Code Refactoring - Prepare for Griffe 0.37 ([b5bb8a9](https://github.com/mkdocstrings/python/commit/b5bb8a982e7a2ec97c73335e453d0033bf4987b6) by Timothée Mazzucotelli). ## [1.7.3](https://github.com/mkdocstrings/python/releases/tag/1.7.3) - 2023-10-09 [Compare with 1.7.2](https://github.com/mkdocstrings/python/compare/1.7.2...1.7.3) ### Bug Fixes - Don't deepcopy the local config ([1300d2c](https://github.com/mkdocstrings/python/commit/1300d2c77dd49f5dea459ad844d72edcc856c4cd) by Timothée Mazzucotelli). ## [1.7.2](https://github.com/mkdocstrings/python/releases/tag/1.7.2) - 2023-10-05 [Compare with 1.7.1](https://github.com/mkdocstrings/python/compare/1.7.1...1.7.2) ### Bug Fixes - Prevent alias resolution error when source-ordering members ([67df10c](https://github.com/mkdocstrings/python/commit/67df10cbb86225e1e3efc251325cbff883a1ef3c) by Timothée Mazzucotelli). [Issue griffe#213](https://github.com/mkdocstrings/griffe/issues/213) ### Code Refactoring - Use package relative filepath if filepath is not relative ([aa5a3f7](https://github.com/mkdocstrings/python/commit/aa5a3f7b0928498ba9da10ed1211d1e55b7f6c4b) by Timothée Mazzucotelli). [Discussion mkdocstrings#622](https://github.com/mkdocstrings/mkdocstrings/discussions/622) ## [1.7.1](https://github.com/mkdocstrings/python/releases/tag/1.7.1) - 2023-09-28 [Compare with 1.7.0](https://github.com/mkdocstrings/python/compare/1.7.0...1.7.1) ### Bug Fixes - Stop propagation of annotation to next parameter in signature template ([3a760ac](https://github.com/mkdocstrings/python/commit/3a760acacfabaef5abc658ee579e1c205e674994) by Timothée Mazzucotelli). [Issue #110](https://github.com/mkdocstrings/python/issues/110) ### Code Refactoring - Look into inherited members for `__init__` methods when merging docstrings ([b97d51f](https://github.com/mkdocstrings/python/commit/b97d51f67c2ee3d1edfe6975274ead50fcb3fa8f) by Timothée Mazzucotelli). [Issue #106](https://github.com/mkdocstrings/python/issues/106) ## [1.7.0](https://github.com/mkdocstrings/python/releases/tag/1.7.0) - 2023-09-14 [Compare with 1.6.3](https://github.com/mkdocstrings/python/compare/1.6.3...1.7.0) ### Features - Add option to unwrap `Annotated` types ([53db04b](https://github.com/mkdocstrings/python/commit/53db04b6256db960aebc2a9f91129b82ca222e41) by Timothée Mazzucotelli). ## [1.6.3](https://github.com/mkdocstrings/python/releases/tag/1.6.3) - 2023-09-11 [Compare with 1.6.2](https://github.com/mkdocstrings/python/compare/1.6.2...1.6.3) ### Bug Fixes - Make `load_external_modules` a global-only option ([266f41f](https://github.com/mkdocstrings/python/commit/266f41f2033e034060001bc2bed376b4f3a8d7b8) by Timothée Mazzucotelli). [Issue #87](https://github.com/mkdocstrings/python/issues/87) - Never fail when trying to format code with Black ([df24bbc](https://github.com/mkdocstrings/python/commit/df24bbc640886e1da2d00a3b58c1aa7736cb1eeb) by Timothée Mazzucotelli). ### Code Refactoring - Wrap docstring section elements (list style) in code tags to prevent spell checker errors ([1ae8dd8](https://github.com/mkdocstrings/python/commit/1ae8dd89cddd67c09d7d30c59b9013516cea2924) by Timothée Mazzucotelli). ## [1.6.2](https://github.com/mkdocstrings/python/releases/tag/1.6.2) - 2023-09-05 [Compare with 1.6.1](https://github.com/mkdocstrings/python/compare/1.6.1...1.6.2) ### Bug Fixes - Don't render cross-ref spans when they're not enabled ([eed51ee](https://github.com/mkdocstrings/python/commit/eed51ee14bd973a08395f95377f9bd4cd38febfc) by Timothée Mazzucotelli). ## [1.6.1](https://github.com/mkdocstrings/python/releases/tag/1.6.1) - 2023-09-04 [Compare with 1.6.0](https://github.com/mkdocstrings/python/compare/1.6.0...1.6.1) ### Bug Fixes - Fix spacing for rendered named items in Yields, Receives and Returns sections (list style) ([e12688e](https://github.com/mkdocstrings/python/commit/e12688ecb7d868047f794300eb2638d052563e68) by Timothée Mazzucotelli). - Fix rendering Receives sections as lists ([9ff7e68](https://github.com/mkdocstrings/python/commit/9ff7e68b58e2ab0829c73e4e62254325a4f766ac) by Timothée Mazzucotelli). ## [1.6.0](https://github.com/mkdocstrings/python/releases/tag/1.6.0) - 2023-08-27 [Compare with 1.5.2](https://github.com/mkdocstrings/python/compare/1.5.2...1.6.0) ### Features - Add `doc-signature` CSS class to separate signature code blocks ([b6c648f](https://github.com/mkdocstrings/python/commit/b6c648f554f2e0dce609afc2a2c1a3b27a4fbeba) by Timothée Mazzucotelli). ### Code Refactoring - Add a `format_attribute` filter, preparing for cross-refs in attribute signatures ([8f0ade2](https://github.com/mkdocstrings/python/commit/8f0ade249638ee2f2d446f083c70b6c30799875a) by Timothée Mazzucotelli). ## [1.5.2](https://github.com/mkdocstrings/python/releases/tag/1.5.2) - 2023-08-25 [Compare with 1.5.1](https://github.com/mkdocstrings/python/compare/1.5.1...1.5.2) ### Bug Fixes - Regression in children template: fix condition for when members are specified ([beeebff](https://github.com/mkdocstrings/python/commit/beeebffa36288d1f71d122f78ecd9064b41a75d0) by Timothée Mazzucotelli). [Issue #100](https://github.com/mkdocstrings/python/issues/100) - Prevent whitespace removal before highlight filter ([c6f36c0](https://github.com/mkdocstrings/python/commit/c6f36c0c9e5141800f8c5c988c9b67720fccccb8) by Timothée Mazzucotelli). ### Code Refactoring - Never show full object path in ToC entry ([9aa758b](https://github.com/mkdocstrings/python/commit/9aa758bcc42dfcf7c416d87b8f7cd407b7fdf148) by Timothée Mazzucotelli). - Sync templates with insiders, remove useless lines ([38b317f](https://github.com/mkdocstrings/python/commit/38b317f4fc74b583a4788721a5559c51a5a47d86) by Timothée Mazzucotelli). ## [1.5.1](https://github.com/mkdocstrings/python/releases/tag/1.5.1) - 2023-08-24 [Compare with 1.5.0](https://github.com/mkdocstrings/python/compare/1.5.0...1.5.1) ### Code Refactoring - Never show full path in separate signature since it would appear in the heading already ([9e02049](https://github.com/mkdocstrings/python/commit/9e0204930cf4dc973ba8eb41c471fc0132e1631f) by Timothée Mazzucotelli). - Improve guessing whether an object is public ([35eb811](https://github.com/mkdocstrings/python/commit/35eb81162582d794f170cd7e8c68f10ecfd8ff9d) by Timothée Mazzucotelli). - Always sort modules alphabetically as source order wouldn't make sense ([70c81ce](https://github.com/mkdocstrings/python/commit/70c81cebb62366cbfc6124bc84d1563db176afb6) by Timothée Mazzucotelli). - Return anchors as a tuple, not a set, to preserve order ([736a2b5](https://github.com/mkdocstrings/python/commit/736a2b5e729d25bb184db8d42f2ad01025a5bc58) by Timothée Mazzucotelli). [Related-to #mkdocstrings/crystal#6](https://github.com/mkdocstrings/crystal/pull/6) ## [1.5.0](https://github.com/mkdocstrings/python/releases/tag/1.5.0) - 2023-08-20 [Compare with 1.4.0](https://github.com/mkdocstrings/python/compare/1.4.0...1.5.0) ### Features - Add support for new Griffe docstring sections: modules, classes, and functions (methods) ([d5337af](https://github.com/mkdocstrings/python/commit/d5337afdf68fc492b34f749aa69d1da33b49f9c2) by Timothée Mazzucotelli). ## [1.4.0](https://github.com/mkdocstrings/python/releases/tag/1.4.0) - 2023-08-18 [Compare with 1.3.0](https://github.com/mkdocstrings/python/compare/1.3.0...1.4.0) ### Features - Support new Griffe expressions (in v0.33) ([9b8e1b1](https://github.com/mkdocstrings/python/commit/9b8e1b1604b978cf2d89b7abf826cf4407f92394) by Timothée Mazzucotelli). ### Code Refactoring - Deprecate `crossref` and `multi_crossref` filters ([4fe3d20](https://github.com/mkdocstrings/python/commit/4fe3d2051047061780e20683da6513a7c8d91829) by Timothée Mazzucotelli). ## [1.3.0](https://github.com/mkdocstrings/python/releases/tag/1.3.0) - 2023-08-06 [Compare with 1.2.1](https://github.com/mkdocstrings/python/compare/1.2.1...1.3.0) ### Dependencies - Set upper bound on Griffe (0.33) ([ad8c2a3](https://github.com/mkdocstrings/python/commit/ad8c2a3ac8daf0b0c06579b6ba667e05feffa247) by Timothée Mazzucotelli). See https://github.com/mkdocstrings/griffe/discussions/195. ### Features - Show parameter default values within the "list" section style too ([55f08f3](https://github.com/mkdocstrings/python/commit/55f08f3e2cece815dd79d35c82515ba8003ec64c) by Antoine Dechaume). [PR #92](https://github.com/mkdocstrings/python/pull/92), Co-authored-by: Timothée Mazzucotelli ## [1.2.1](https://github.com/mkdocstrings/python/releases/tag/1.2.1) - 2023-07-20 [Compare with 1.2.0](https://github.com/mkdocstrings/python/compare/1.2.0...1.2.1) ### Bug Fixes - Fix members ordering when members are specified with a boolean ([c69f9c3](https://github.com/mkdocstrings/python/commit/c69f9c3b3ddde915619eded6620f7ddada977b00) by Timothée Mazzucotelli). [Issue #89](https://github.com/mkdocstrings/python/issues/89) ## [1.2.0](https://github.com/mkdocstrings/python/releases/tag/1.2.0) - 2023-07-14 [Compare with 1.1.2](https://github.com/mkdocstrings/python/compare/1.1.2...1.2.0) ### Features - Add Jinja blocks to module, class, function and attribute templates ([299fe48](https://github.com/mkdocstrings/python/commit/299fe483cc03ba76df29b843f88467f89db6dc72) by Timothée Mazzucotelli). - Setup infrastructure for I18N, add translations for simplified chinese and japanese ([b053b29](https://github.com/mkdocstrings/python/commit/b053b2900ef5c0069b68ad19bda9aaa98141a525) by Nyuan Zhang). [PR #77](https://github.com/mkdocstrings/python/pull/77) - Support inheritance ([ae42356](https://github.com/mkdocstrings/python/commit/ae4235689155a4b4f0c1e74b0014a466c6b1181f) by Timothée Mazzucotelli). [Issue mkdocstrings#157](https://github.com/mkdocstrings/mkdocstrings/issues/157), [Discussion mkdocstrings#536](https://github.com/mkdocstrings/mkdocstrings/discussions/536) ### Bug Fixes - Don't show `None` as return annotation of class signatures ([3d8724e](https://github.com/mkdocstrings/python/commit/3d8724ed1f4d040d7a3d9d02784cf0d1f80445b2) by Timothée Mazzucotelli). [Issue #85](https://github.com/mkdocstrings/python/issues/85) - Show labels in deterministic order ([02619a8](https://github.com/mkdocstrings/python/commit/02619a85ee4aab25f3241d983bdfff0534dd3f81) by Oleh Prypin). ## [1.1.2](https://github.com/mkdocstrings/python/releases/tag/1.1.2) - 2023-06-04 [Compare with 1.1.1](https://github.com/mkdocstrings/python/compare/1.1.1...1.1.2) ### Code Refactoring - Keep headings style consistent (CSS) ([92032e5](https://github.com/mkdocstrings/python/commit/92032e561861c3fc4e3fb0c6882bb076d0e6614d) by Timothée Mazzucotelli). ## [1.1.1](https://github.com/mkdocstrings/python/releases/tag/1.1.1) - 2023-06-04 [Compare with 1.1.0](https://github.com/mkdocstrings/python/compare/1.1.0...1.1.1) ### Bug Fixes - Fix mkdocs and readthedocs themes support ([14f18b2](https://github.com/mkdocstrings/python/commit/14f18b219f67f9b6d154d4a52051d8d7d7c49348) by Timothée Mazzucotelli). ### Code Refactoring - Improve display of paragraphs in docstring sections ([439f5e6](https://github.com/mkdocstrings/python/commit/439f5e6984fe94c28324ca57fbd1a52ef8f55b62) by Timothée Mazzucotelli). ## [1.1.0](https://github.com/mkdocstrings/python/releases/tag/1.1.0) - 2023-05-25 [Compare with 1.0.0](https://github.com/mkdocstrings/python/compare/1.0.0...1.1.0) ### Features - Support custom templates through objects' extra data ([8ff2b06](https://github.com/mkdocstrings/python/commit/8ff2b06295e848b9c84867802eb845adf061dc10) by Timothée Mazzucotelli). [PR #70](https://github.com/mkdocstrings/python/pull/70) ## [1.0.0](https://github.com/mkdocstrings/python/releases/tag/1.0.0) - 2023-05-11 [Compare with 0.10.1](https://github.com/mkdocstrings/python/compare/0.10.1...1.0.0) ### Breaking changes - The signature of the [`format_signature` filter][mkdocstrings_handlers.python.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). ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.2910438 mkdocstrings_python-1.18.2/CODE_OF_CONDUCT.md0000644000000000000000000001253615051047736015457 0ustar00# Contributor Covenant Code of Conduct ## Our Pledge We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. ## Our Standards Examples of behavior that contributes to a positive environment for our community include: * Demonstrating empathy and kindness toward other people * Being respectful of differing opinions, viewpoints, and experiences * Giving and gracefully accepting constructive feedback * Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience * Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: * The use of sexualized language or imagery, and sexual attention or advances of any kind * Trolling, insulting or derogatory comments, and personal or political attacks * Public or private harassment * Publishing others' private information, such as a physical or email address, without their explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Responsibilities Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. ## Scope This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at dev@pawamoy.fr. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. ## Enforcement Guidelines Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: ### 1. Correction **Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. **Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. ### 2. Warning **Community Impact**: A violation through a single incident or series of actions. **Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. ### 3. Temporary Ban **Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. **Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. ### 4. Permanent Ban **Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. **Consequence**: A permanent ban from any sort of public interaction within the community. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC]. For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations]. [homepage]: https://www.contributor-covenant.org [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html [Mozilla CoC]: https://github.com/mozilla/diversity [FAQ]: https://www.contributor-covenant.org/faq [translations]: https://www.contributor-covenant.org/translations ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.2913349 mkdocstrings_python-1.18.2/CONTRIBUTING.md0000644000000000000000000001006615051047736015105 0ustar00# Contributing Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. ## Environment setup Nothing easier! Fork and clone the repository, then: ```bash cd python make setup ``` > NOTE: If it fails for some reason, you'll need to install [uv](https://github.com/astral-sh/uv) manually. > > You can install it with: > > ```bash > curl -LsSf https://astral.sh/uv/install.sh | sh > ``` > > Now you can try running `make setup` again, or simply `uv sync`. You now have the dependencies installed. Run `make help` to see all the available actions! ## Tasks The entry-point to run commands and tasks is the `make` Python script, located in the `scripts` directory. Try running `make` to show the available commands and tasks. The *commands* do not need the Python dependencies to be installed, while the *tasks* do. The cross-platform tasks are written in Python, thanks to [duty](https://github.com/pawamoy/duty). If you work in VSCode, we provide [an action to configure VSCode](https://pawamoy.github.io/copier-uv/work/#vscode-setup) for the project. ## Development As usual: 1. create a new branch: `git switch -c feature-or-bugfix-name` 1. edit the code and/or the documentation **Before committing:** 1. run `make format` to auto-format the code 1. run `make check` to check everything (fix any warning) 1. run `make test` to run the tests (fix any issue) 1. if you updated the documentation or the project dependencies: 1. run `make docs` 1. go to http://localhost:8000 and check that everything looks good 1. follow our [commit message convention](#commit-message-convention) If you are unsure about how to fix or ignore a warning, just let the continuous integration fail, and we will help you during review. Don't bother updating the changelog, we will take care of this. ## Commit message convention Commit messages must follow our convention based on the [Angular style](https://gist.github.com/stephenparish/9941e89d80e2bc58a153#format-of-the-commit-message) or the [Karma convention](https://karma-runner.github.io/4.0/dev/git-commit-msg.html): ``` [(scope)]: Subject [Body] ``` **Subject and body must be valid Markdown.** Subject must have proper casing (uppercase for first letter if it makes sense), but no dot at the end, and no punctuation in general. Scope and body are optional. Type can be: - `build`: About packaging, building wheels, etc. - `chore`: About packaging or repo/files management. - `ci`: About Continuous Integration. - `deps`: Dependencies update. - `docs`: About documentation. - `feat`: New feature. - `fix`: Bug fix. - `perf`: About performance. - `refactor`: Changes that are not features or bug fixes. - `style`: A change in code style/format. - `tests`: About tests. If you write a body, please add trailers at the end (for example issues and PR references, or co-authors), without relying on GitHub's flavored Markdown: ``` Body. Issue #10: https://github.com/namespace/project/issues/10 Related to PR namespace/other-project#15: https://github.com/namespace/other-project/pull/15 ``` These "trailers" must appear at the end of the body, without any blank lines between them. The trailer title can contain any character except colons `:`. We expect a full URI for each trailer, not just GitHub autolinks (for example, full GitHub URLs for commits and issues, not the hash or the #issue-number). We do not enforce a line length on commit messages summary and body, but please avoid very long summaries, and very long lines in the body, unless they are part of code blocks that must not be wrapped. ## Pull requests guidelines Link to any related issue in the Pull Request message. During the review, we recommend using fixups: ```bash # SHA is the SHA of the commit you want to fix git commit --fixup=SHA ``` Once all the changes are approved, you can squash your commits: ```bash git rebase -i --autosquash main ``` And force-push: ```bash git push -f ``` If this seems all too complicated, you can push or force-push each new commit, and we will squash them ourselves if needed, before merging. ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1738158934.2235713 mkdocstrings_python-1.18.2/LICENSE0000644000000000000000000000136214746431526013664 0ustar00ISC 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. ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1748006213.7312815 mkdocstrings_python-1.18.2/README.md0000644000000000000000000000747015014072506014130 0ustar00

mkdocstrings-python

A Python handler for mkdocstrings.

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

The Python handler uses [Griffe](https://mkdocstrings.github.io/griffe) to collect documentation from Python source code. The word "griffe" can sometimes be used instead of "signature" in French. Griffe is able to visit the Abstract Syntax Tree (AST) of the source code to extract useful information. It is also able to execute the code (by importing it) and introspect objects in memory when source code is not available. Finally, it can parse docstrings following different styles. ## Installation You can install this handler as a *mkdocstrings* extra: ```toml title="pyproject.toml" # PEP 621 dependencies declaration # adapt to your dependencies manager [project] dependencies = [ "mkdocstrings[python]>=0.18", ] ``` You can also explicitly depend on the handler: ```toml title="pyproject.toml" # PEP 621 dependencies declaration # adapt to your dependencies manager [project] dependencies = [ "mkdocstrings-python", ] ``` ## Preview ![mkdocstrings_python_gif](https://user-images.githubusercontent.com/3999221/77157838-7184db80-6aa2-11ea-9f9a-fe77405202de.gif) ## Features - **Data collection from source code**: collection of the object-tree and the docstrings is done thanks to [Griffe](https://github.com/mkdocstrings/griffe). - **Support for type annotations:** Griffe collects your type annotations and *mkdocstrings* uses them to display parameter types or return types. It is even able to automatically add cross-references to other objects from your API, from the standard library or third-party libraries! See [how to load inventories](https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories) to enable it. - **Recursive documentation of Python objects:** just use the module dotted-path as an identifier, and you get the full module docs. You don't need to inject documentation for each class, function, etc. - **Support for documented attributes:** attributes (variables) followed by a docstring (triple-quoted string) will be recognized by Griffe in modules, classes and even in `__init__` methods. - **Multiple docstring-styles support:** common support for Google-style, Numpydoc-style, and Sphinx-style docstrings. See [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/) on docstrings support. - **Admonition support in Google docstrings:** blocks like `Note:` or `Warning:` will be transformed to their [admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) equivalent. *We do not support nested admonitions in docstrings!* - **Every object has a TOC entry:** we render a heading for each object, meaning *MkDocs* picks them into the Table of Contents, which is nicely displayed by the Material theme. Thanks to *mkdocstrings* cross-reference ability, you can reference other objects within your docstrings, with the classic Markdown syntax: `[this object][package.module.object]` or directly with `[package.module.object][]` - **Source code display:** *mkdocstrings* can add a collapsible div containing the highlighted source code of the Python object. ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1738159061.5645165 mkdocstrings_python-1.18.2/config/black.toml0000644000000000000000000000007214746431726016074 0ustar00[tool.black] line-length = 120 exclude = "tests/fixtures" ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1747738968.724504 mkdocstrings_python-1.18.2/config/coverage.ini0000644000000000000000000000065215013060531016377 0ustar00[coverage:run] branch = true parallel = true source = src/mkdocstrings_handlers tests/ [coverage:paths] equivalent = src/ .venv/lib/*/site-packages/ .venvs/*/lib/*/site-packages/ [coverage:report] include_namespace_packages = true precision = 2 omit = src/*/__init__.py src/*/__main__.py tests/__init__.py exclude_lines = pragma: no cover if TYPE_CHECKING [coverage:json] output = htmlcov/coverage.json ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1738159062.587831 mkdocstrings_python-1.18.2/config/git-changelog.toml0000644000000000000000000000034014746431727017527 0ustar00bump = "auto" convention = "angular" in-place = true output = "CHANGELOG.md" parse-refs = false parse-trailers = true sections = ["build", "deps", "feat", "fix", "refactor"] template = "keepachangelog" versioning = "pep440" ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1738159063.0244896 mkdocstrings_python-1.18.2/config/mypy.ini0000644000000000000000000000025214746431727015623 0ustar00[mypy] ignore_missing_imports = true exclude = tests/fixtures/ warn_unused_ignores = true show_error_codes = true namespace_packages = true explicit_package_bases = true ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.2913349 mkdocstrings_python-1.18.2/config/pytest.ini0000644000000000000000000000064515051047736016154 0ustar00[pytest] python_files = test_*.py addopts = --cov --cov-config config/coverage.ini testpaths = tests # action:message_regex:warning_class:module_regex:line filterwarnings = error # TODO: Remove once pytest-xdist 4 is released. ignore:.*rsyncdir:DeprecationWarning:xdist # TODO: Remove once mkdocstrings stops setting fallback function. ignore:.*fallback anchor function:DeprecationWarning:mkdocstrings ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.2919145 mkdocstrings_python-1.18.2/config/ruff.toml0000644000000000000000000000444015051047736015757 0ustar00target-version = "py39" line-length = 120 [lint] exclude = [ "tests/fixtures/*.py", ] select = [ "A", "ANN", "ARG", "B", "BLE", "C", "C4", "COM", "D", "DTZ", "E", "ERA", "EXE", "F", "FBT", "G", "I", "ICN", "INP", "ISC", "N", "PGH", "PIE", "PL", "PLC", "PLE", "PLR", "PLW", "PT", "PYI", "Q", "RUF", "RSE", "RET", "S", "SIM", "SLF", "T", "T10", "T20", "TCH", "TID", "TRY", "UP", "W", "YTT", ] ignore = [ "A001", # Variable is shadowing a Python builtin "ANN101", # Missing type annotation for self "ANN102", # Missing type annotation for cls "ANN204", # Missing return type annotation for special method __str__ "ANN401", # Dynamically typed expressions (typing.Any) are disallowed "ARG005", # Unused lambda argument "C901", # Too complex "D105", # Missing docstring in magic method "D417", # Missing argument description in the docstring "E501", # Line too long "ERA001", # Commented out code "G004", # Logging statement uses f-string "PLR0911", # Too many return statements "PLR0912", # Too many branches "PLR0913", # Too many arguments to function call "PLR0915", # Too many statements "SLF001", # Private member accessed "TRY003", # Avoid specifying long messages outside the exception class ] [lint.per-file-ignores] "src/**/cli.py" = [ "T201", # Print statement ] "src/*/debug.py" = [ "T201", # Print statement ] "!src/*/*.py" = [ "D100", # Missing docstring in public module ] "!src/**.py" = [ "D101", # Missing docstring in public class "D103", # Missing docstring in public function ] "scripts/*.py" = [ "INP001", # File is part of an implicit namespace package "T201", # Print statement ] "tests/**.py" = [ "ARG005", # Unused lambda argument "FBT001", # Boolean positional arg in function definition "PLR2004", # Magic value used in comparison "S101", # Use of assert detected ] [lint.flake8-quotes] docstring-quotes = "double" [lint.flake8-tidy-imports] ban-relative-imports = "all" [lint.isort] known-first-party = ["mkdocstrings_handlers.python"] [lint.pydocstyle] convention = "google" [format] exclude = [ "tests/fixtures/*.py", ] docstring-code-format = true docstring-code-line-length = 80 ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1755598814.302124 mkdocstrings_python-1.18.2/config/vscode/launch.json0000644000000000000000000000266215051047736017554 0ustar00{ "version": "0.2.0", "configurations": [ { "name": "python (current file)", "type": "debugpy", "request": "launch", "program": "${file}", "console": "integratedTerminal", "justMyCode": false, "args": "${command:pickArgs}" }, { "name": "run", "type": "debugpy", "request": "launch", "module": "python", "console": "integratedTerminal", "justMyCode": false, "args": "${command:pickArgs}" }, { "name": "docs", "type": "debugpy", "request": "launch", "module": "mkdocs", "justMyCode": false, "args": [ "serve", "-v" ] }, { "name": "test", "type": "debugpy", "request": "launch", "module": "pytest", "justMyCode": false, "args": [ "-c=config/pytest.ini", "-vvv", "--no-cov", "--dist=no", "tests", "-k=${input:tests_selection}" ] } ], "inputs": [ { "id": "tests_selection", "type": "promptString", "description": "Tests selection", "default": "" } ] }././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1738159060.5512018 mkdocstrings_python-1.18.2/config/vscode/settings.json0000644000000000000000000000170414746431725020143 0ustar00{ "files.watcherExclude": { "**/.venv*/**": true, "**/.venvs*/**": true, "**/venv*/**": true }, "mypy-type-checker.args": [ "--config-file=config/mypy.ini" ], "python.testing.unittestEnabled": false, "python.testing.pytestEnabled": true, "python.testing.pytestArgs": [ "--config-file=config/pytest.ini" ], "ruff.enable": true, "ruff.format.args": [ "--config=config/ruff.toml" ], "ruff.lint.args": [ "--config=config/ruff.toml" ], "yaml.schemas": { "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml" }, "yaml.customTags": [ "!ENV scalar", "!ENV sequence", "!relative scalar", "tag:yaml.org,2002:python/name:materialx.emoji.to_svg", "tag:yaml.org,2002:python/name:materialx.emoji.twemoji", "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format" ] }././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1738159059.9878788 mkdocstrings_python-1.18.2/config/vscode/tasks.json0000644000000000000000000000460514746431724017432 0ustar00{ "version": "2.0.0", "tasks": [ { "label": "changelog", "type": "process", "command": "scripts/make", "args": ["changelog"] }, { "label": "check", "type": "process", "command": "scripts/make", "args": ["check"] }, { "label": "check-quality", "type": "process", "command": "scripts/make", "args": ["check-quality"] }, { "label": "check-types", "type": "process", "command": "scripts/make", "args": ["check-types"] }, { "label": "check-docs", "type": "process", "command": "scripts/make", "args": ["check-docs"] }, { "label": "check-api", "type": "process", "command": "scripts/make", "args": ["check-api"] }, { "label": "clean", "type": "process", "command": "scripts/make", "args": ["clean"] }, { "label": "docs", "type": "process", "command": "scripts/make", "args": ["docs"] }, { "label": "docs-deploy", "type": "process", "command": "scripts/make", "args": ["docs-deploy"] }, { "label": "format", "type": "process", "command": "scripts/make", "args": ["format"] }, { "label": "release", "type": "process", "command": "scripts/make", "args": ["release", "${input:version}"] }, { "label": "setup", "type": "process", "command": "scripts/make", "args": ["setup"] }, { "label": "test", "type": "process", "command": "scripts/make", "args": ["test", "coverage"], "group": "test" }, { "label": "vscode", "type": "process", "command": "scripts/make", "args": ["vscode"] } ], "inputs": [ { "id": "version", "type": "promptString", "description": "Version" } ] }././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1755598814.302124 mkdocstrings_python-1.18.2/docs/.glossary.md0000644000000000000000000000157015051047736016047 0ustar00[__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 [Ruff]: https://docs.astral.sh/ruff *[ToC]: Table of Contents ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1755598814.302124 mkdocstrings_python-1.18.2/docs/.overrides/main.html0000644000000000000000000000110015051047736017463 0ustar00{% extends "base.html" %} {% block announce %} Fund this project through sponsorship {% include ".icons/octicons/heart-fill-16.svg" %} — Follow @pawamoy on {% include ".icons/fontawesome/brands/mastodon.svg" %} Fosstodon for updates {% endblock %} ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1755598814.303124 mkdocstrings_python-1.18.2/docs/.overrides/partials/comments.html0000644000000000000000000000411215051047736022211 0ustar00 ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1755598814.303124 mkdocstrings_python-1.18.2/docs/.overrides/partials/path-item.html0000644000000000000000000000121115051047736022251 0ustar00{# Fix breadcrumbs for when mkdocs-section-index is used. #} {# See https://github.com/squidfunk/mkdocs-material/issues/7614. #} {% macro render_content(nav_item) %} {{ nav_item.title }} {% endmacro %} {% macro render(nav_item, ref=nav_item) %} {% if nav_item.is_page %}
  • {{ render_content(ref) }}
    • {% elif nav_item.children %} {{ render(nav_item.children | first, ref) }} {% endif %} {% endmacro %} ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.3161237 mkdocstrings_python-1.18.2/docs/changelog.md0000644000000000000000000000006015051047736016046 0ustar00--- title: Changelog --- --8<-- "CHANGELOG.md" ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.3172398 mkdocstrings_python-1.18.2/docs/code_of_conduct.md0000644000000000000000000000007415051047736017241 0ustar00--- title: Code of Conduct --- --8<-- "CODE_OF_CONDUCT.md" ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.3176725 mkdocstrings_python-1.18.2/docs/contributing.md0000644000000000000000000000006615051047736016634 0ustar00--- title: Contributing --- --8<-- "CONTRIBUTING.md" ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.3181086 mkdocstrings_python-1.18.2/docs/credits.md0000644000000000000000000000013515051047736015557 0ustar00--- title: Credits hide: - toc --- ```python exec="yes" --8<-- "scripts/gen_credits.py" ``` ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1738159066.817753 mkdocstrings_python-1.18.2/docs/css/insiders.css0000644000000000000000000000373114746431733016733 0ustar00@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; }././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.3331234 mkdocstrings_python-1.18.2/docs/css/material.css0000644000000000000000000000267615051047736016714 0ustar00/* 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); } ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.3331234 mkdocstrings_python-1.18.2/docs/css/mkdocstrings.css0000644000000000000000000000461515051047736017620 0ustar00/* Indentation. */ div.doc-contents:not(.first) { padding-left: 25px; border-left: .05rem solid var(--md-typeset-table-color); } /* Mark external links as such. */ a.external::after, a.autorefs-external::after { /* https://primer.style/octicons/arrow-up-right-24 */ mask-image: url('data:image/svg+xml,'); -webkit-mask-image: url('data:image/svg+xml,'); content: ' '; display: inline-block; vertical-align: middle; position: relative; height: 1em; width: 1em; background-color: currentColor; } a.external:hover::after, a.autorefs-external:hover::after { background-color: var(--md-accent-fg-color); } /* Tree-like output for backlinks. */ .doc-backlink-list { --tree-clr: var(--md-default-fg-color); --tree-font-size: 1rem; --tree-item-height: 1; --tree-offset: 1rem; --tree-thickness: 1px; --tree-style: solid; display: grid; list-style: none !important; } .doc-backlink-list li > span:first-child { text-indent: .3rem; } .doc-backlink-list li { padding-inline-start: var(--tree-offset); border-left: var(--tree-thickness) var(--tree-style) var(--tree-clr); position: relative; margin-left: 0 !important; &:last-child { border-color: transparent; } &::before{ content: ''; position: absolute; top: calc(var(--tree-item-height) / 2 * -1 * var(--tree-font-size) + var(--tree-thickness)); left: calc(var(--tree-thickness) * -1); width: calc(var(--tree-offset) + var(--tree-thickness) * 2); height: calc(var(--tree-item-height) * var(--tree-font-size)); border-left: var(--tree-thickness) var(--tree-style) var(--tree-clr); border-bottom: var(--tree-thickness) var(--tree-style) var(--tree-clr); } &::after{ content: ''; position: absolute; border-radius: 50%; background-color: var(--tree-clr); top: calc(var(--tree-item-height) / 2 * 1rem); left: var(--tree-offset) ; translate: calc(var(--tree-thickness) * -1) calc(var(--tree-thickness) * -1); } } ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.3341234 mkdocstrings_python-1.18.2/docs/index.md0000644000000000000000000000007515051047736015234 0ustar00--- title: Overview hide: - feedback --- --8<-- "README.md" ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.3551228 mkdocstrings_python-1.18.2/docs/insiders/changelog.md0000644000000000000000000000606015051047736017674 0ustar00# Changelog ## mkdocstrings-python Insiders ### 1.12.0 March 22, 2025 { id="1.12.0" } - [Ordering method: `__all__`][option-members_order] ### 1.11.0 March 20, 2025 { id="1.11.0" } - [Filtering method: `public`][option-filters-public] ### 1.10.0 March 10, 2025 { id="1.10.0" } - [Backlinks][backlinks] ### 1.9.0 September 03, 2024 { id="1.9.0" } - [Relative cross-references][relative_crossrefs] - [Scoped cross-references][scoped_crossrefs] ### 1.8.3 June 19, 2024 { id="1.8.3" } - Update code for Griffe 0.46+ to avoid deprecation warnings ### 1.8.2 May 09, 2024 { id="1.8.2" } - Don't render cross-refs for default values when signatures aren't separated ### 1.8.1 April 19, 2024 { id="1.8.1" } - Render enumeration instance name instead of just "value", allowing proper cross-reference ### 1.8.0 March 24, 2024 { id="1.8.0" } - [Annotations modernization][modernize_annotations] ### 1.7.0 March 24, 2024 { id="1.7.0" } - [Class inheritance diagrams with Mermaid][show_inheritance_diagram] ### 1.6.0 January 30, 2024 { id="1.6.0" } - Render cross-references to parameters documentation in signatures and attribute values. - Add [`parameter_headings`][parameter_headings] option to render headings for parameters (enabling permalinks and ToC/inventory entries). - Render cross-references for default parameter values in signatures. ### 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.do_format_signature] has changed. The templates that must be updated: `class.html`, `expression.html`, `function.html` and `signature.html`. ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.3562713 mkdocstrings_python-1.18.2/docs/insiders/goals.yml0000644000000000000000000000366315051047736017261 0ustar00goals: 500: name: PlasmaVac User Guide features: - name: Cross-references for type annotations in signatures ref: /usage/configuration/signatures/#signature_crossrefs since: 2023/05/10 - name: Symbol types in headings and table of contents ref: /usage/configuration/headings/#show_symbol_type_toc since: 2023/06/04 1000: name: GraviFridge Fluid Renewal features: - name: Auto-summary of object members ref: /usage/configuration/members/#summary since: 2023/08/20 - name: Automatic rendering of function signature overloads since: 2023/09/05 - name: Parameter headings ref: /usage/configuration/headings/#parameter_headings since: 2024/01/30 - name: Automatic cross-references to parameters ref: /usage/configuration/headings/#parameter_headings since: 2024/01/30 - name: Automatic cross-references for default parameter values in signatures since: 2024/01/30 1500: name: HyperLamp Navigation Tips features: - name: Class inheritance diagrams with Mermaid ref: /usage/configuration/general/#show_inheritance_diagram since: 2024/03/24 - name: Annotations modernization ref: /usage/configuration/signatures/#modernize_annotations since: 2024/03/24 2000: name: FusionDrive Ejection Configuration features: - name: Relative cross-references ref: /usage/configuration/docstrings/#relative_crossrefs since: 2024/09/03 - name: Scoped cross-references ref: /usage/configuration/docstrings/#scoped_crossrefs since: 2024/09/03 - name: Backlinks ref: /usage/configuration/general/#backlinks since: 2025/03/10 - name: "Filtering method: `public`" ref: /usage/configuration/members/#option-filters-public since: 2025/03/20 - name: "Ordering method: `__all__`" ref: /usage/configuration/members/#option-members_order since: 2025/03/22././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.3731227 mkdocstrings_python-1.18.2/docs/insiders/index.md0000644000000000000000000002507315051047736017061 0ustar00--- title: Insiders --- # Insiders *mkdocstrings-python* follows the **sponsorware** release strategy, which means that new features are first exclusively released to sponsors as part of [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 granted access to this private repository. [^1]: In general, every new feature is first exclusively released to sponsors, but sometimes upstream dependencies enhance existing features that must be supported by *mkdocstrings-python*. Every feature is tied to a [funding goal][funding] in monthly subscriptions. When a funding goal is hit, the features that are tied to it are merged back into *mkdocstrings-python* and released for general availability, making them available to all users. Bugfixes are always released in tandem. Sponsorships start as low as [**$10 a month**][sponsors].[^2] [^2]: Note that $10 a month is the minimum amount to become eligible for Insiders. While GitHub Sponsors also allows to sponsor lower amounts or one-time amounts, those can't be granted access to Insiders due to technical reasons. Such contributions are still very much welcome as they help ensuring the project's sustainability. ## What sponsorships achieve Sponsorships make this project sustainable, as they buy the maintainers of this project time – a very scarce resource – which is spent on the development of new features, bug fixing, stability improvement, issue triage and general support. The biggest bottleneck in Open Source is time.[^3] [^3]: Making an Open Source project sustainable is exceptionally hard: maintainers burn out, projects are abandoned. That's not great and very unpredictable. The sponsorware model ensures that if you decide to use *mkdocstrings-python*, you can be sure that bugs are fixed quickly and new features are added regularly. If you're unsure if you should sponsor this project, check out the list of [completed funding goals][goals completed] to learn whether you're already using features that were developed with the help of sponsorships. You're most likely using at least a handful of them, [thanks to our awesome sponsors][sponsors]! ## What's in it for me? ```python exec="1" session="insiders" data_source = [ "docs/insiders/goals.yml", ("griffe-inherited-docstrings", "https://mkdocstrings.github.io/griffe-inherited-docstrings/", "insiders/goals.yml"), ("griffe-pydantic", "https://mkdocstrings.github.io/griffe-pydantic/", "insiders/goals.yml"), ("griffe-warnings-deprecated", "https://mkdocstrings.github.io/griffe-warnings-deprecated/", "insiders/goals.yml"), ] ``` ```python exec="1" session="insiders" idprefix="" --8<-- "scripts/insiders.py" if unreleased_features: print( "The moment you [become a sponsor](#how-to-become-a-sponsor), you'll get **immediate " f"access to {len(unreleased_features)} additional features** that you can start using right away, and " "which are currently exclusively available to sponsors:\n" ) for feature in unreleased_features: feature.render(badge=True) print( "\n\nThese are just the features related to this project. " "[See the complete feature list on the author's main Insiders page](https://pawamoy.github.io/insiders/#whats-in-it-for-me)." ) else: print( "The moment you [become a sponsor](#how-to-become-a-sponsor), you'll get immediate " "access to all released features that you can start using right away, and " "which are exclusively available to sponsors. At this moment, there are no " "Insiders features for this project, but checkout the [next funding goals](#goals) " "to see what's coming, as well as **[the feature list for all Insiders projects](https://pawamoy.github.io/insiders/#whats-in-it-for-me).**" ) ``` Additionally, your sponsorship will give more weight to your upvotes on issues, helping us prioritize work items in our backlog. For more information on how we prioritize work, see this page: [Backlog management][backlog]. ## 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. Sponsorships lower than $10 a month are also very much appreciated, and useful. They won't grant you access to Insiders, but they will be counted towards reaching sponsorship goals. Every sponsorship helps us implementing new features and releasing them to the public. **Important:** By default, when you're sponsoring **[@pawamoy][github sponsor profile]** through a GitHub organization, all the publicly visible members of the organization will be invited to join our private repositories. If you wish to only grant access to a subset of users, please send a short email to insiders@pawamoy.fr with the name of your organization and the GitHub accounts of the users that should be granted access. **Tip:** to ensure that access is not tied to a particular individual GitHub account, you can 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 granted access to our private repositories, the bot account can create private forks of our private repositories into your own organization, which all members of your organization will have access to. You can cancel your sponsorship anytime.[^5] [^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][github sponsor profile]{ .md-button .md-button--primary }
    If you sponsor publicly, you're automatically added here with a link to your profile and avatar to show your support for *mkdocstrings-python*. Alternatively, if you wish to keep your sponsorship private, you'll be a silent +1. You can select visibility during checkout and change it afterwards. ## Funding ### Goals The following section lists all funding goals. Each goal contains a list of features prefixed with a checkmark symbol, denoting whether a feature is :octicons-check-circle-fill-24:{ style="color: #00e676" } already available or :octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned, but not yet implemented. When the funding goal is hit, the features are released for general availability. ```python exec="1" session="insiders" idprefix="" for goal in goals.values(): if not goal.complete: goal.render() ``` ### Goals completed This section lists all funding goals that were previously completed, which means that those features were part of Insiders, but are now generally available and can be used by all users. ```python exec="1" session="insiders" idprefix="" for goal in goals.values(): if goal.complete: goal.render() ``` ## Frequently asked questions ### Compatibility > We're building an open source project and want to allow outside collaborators to use *mkdocstrings-python* locally without having access to Insiders. Is this still possible? Yes. Insiders is compatible with *mkdocstrings-python*. Almost all new features and configuration options are either backward-compatible or implemented behind feature flags. Most Insiders features enhance the overall experience, though while these features add value for the users of your project, they shouldn't be necessary for previewing when making changes to content. ### Payment > We don't want to pay for sponsorship every month. Are there any other options? Yes. You can sponsor on a yearly basis by [switching your GitHub account to a yearly billing cycle][billing cycle]. If for some reason you cannot do that, you could also create a dedicated GitHub account with a yearly billing cycle, which you only use for sponsoring (some sponsors already do that). If you have any problems or further questions, please reach out to insiders@pawamoy.fr. ### Terms > Are we allowed to use Insiders under the same terms and conditions as *mkdocstrings-python*? Yes. Whether you're an individual or a company, you may use *mkdocstrings-python Insiders* precisely under the same terms as *mkdocstrings-python*, which are given by the [ISC license][license]. However, we kindly ask you to respect our **fair use policy**: - Please **don't distribute the source code** of Insiders. You may freely use it for public, private or commercial projects, privately fork or mirror it, but please don't make the source code public, as it would counteract the sponsorware strategy. - If you cancel your subscription, your access to the private repository is revoked, and you 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]. [backlog]: https://pawamoy.github.io/backlog/ [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 ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.3851223 mkdocstrings_python-1.18.2/docs/insiders/installation.md0000644000000000000000000000557215051047736020455 0ustar00--- 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. ## Installation ### with the `insiders` tool [`insiders`][insiders-tool] 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.). **We kindly ask that you do not upload the distributions to public registries, as it is against our [Terms of use][].** ### with pip (ssh/https) *mkdocstrings-python Insiders* can be installed with `pip` [using SSH][install-pip-ssh]: ```bash pip install git+ssh://git@github.com/pawamoy-insiders/mkdocstrings-python.git ``` 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][github-pat] 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][github-pat-new] > 3. Enter a name and select the [`repo`][scopes] scope > 4. Generate the token and store it in a safe place > > Note that the personal access token must be kept secret at all times, as it allows the owner to access your private repositories. ### with Git Of course, you can use *mkdocstrings-python Insiders* directly using Git: ``` git clone git@github.com:pawamoy-insiders/mkdocstrings-python ``` When cloning with Git, the package must be installed: ``` pip install -e mkdocstrings-python ``` ## Upgrading When upgrading Insiders, you should always check the version of *mkdocstrings-python* which makes up the first part of the version qualifier. For example, a version like `8.x.x.4.x.x` means that Insiders `4.x.x` is currently based on `8.x.x`. If the major version increased, it's a good idea to consult the [changelog][] and go through the steps to ensure your configuration is up to date and all necessary changes have been made. [become an eligible sponsor]: ./index.md#how-to-become-a-sponsor [changelog]: ./changelog.md [github-pat]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token [github-pat-new]: https://github.com/settings/tokens/new [insiders-tool]: https://pawamoy.github.io/insiders-project/ [install-pip-ssh]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh [scopes]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes [terms of use]: ./index.md#terms ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1738159070.1876912 mkdocstrings_python-1.18.2/docs/js/feedback.js0000644000000000000000000000077514746431736016317 0ustar00const feedback = document.forms.feedback; feedback.hidden = false; feedback.addEventListener("submit", function(ev) { ev.preventDefault(); const commentElement = document.getElementById("feedback"); commentElement.style.display = "block"; feedback.firstElementChild.disabled = true; const data = ev.submitter.getAttribute("data-md-value"); const note = feedback.querySelector(".md-feedback__note [data-md-value='" + data + "']"); if (note) { note.hidden = false; } }) ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1738159069.6043687 mkdocstrings_python-1.18.2/docs/js/insiders.js0000644000000000000000000000547314746431736016413 0ustar00function humanReadableAmount(amount) { const strAmount = String(amount); if (strAmount.length >= 4) { return `${strAmount.slice(0, strAmount.length - 3)},${strAmount.slice(-3)}`; } return strAmount; } function getJSON(url, callback) { var xhr = new XMLHttpRequest(); xhr.open('GET', url, true); xhr.responseType = 'json'; xhr.onload = function () { var status = xhr.status; if (status === 200) { callback(null, xhr.response); } else { callback(status, xhr.response); } }; xhr.send(); } function updatePremiumSponsors(dataURL, rank) { let capRank = rank.charAt(0).toUpperCase() + rank.slice(1); getJSON(dataURL + `/sponsors${capRank}.json`, function (err, sponsors) { const sponsorsDiv = document.getElementById(`${rank}-sponsors`); if (sponsors.length > 0) { let html = ''; html += `${capRank} sponsors

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

    ' sponsorsDiv.innerHTML = html; } }); } function updateInsidersPage(author_username) { const sponsorURL = `https://github.com/sponsors/${author_username}` const dataURL = `https://raw.githubusercontent.com/${author_username}/sponsors/main`; getJSON(dataURL + '/numbers.json', function (err, numbers) { document.getElementById('sponsors-count').innerHTML = numbers.count; Array.from(document.getElementsByClassName('sponsors-total')).forEach(function (element) { element.innerHTML = '$ ' + humanReadableAmount(numbers.total); }); getJSON(dataURL + '/sponsors.json', function (err, sponsors) { const sponsorsElem = document.getElementById('sponsors'); const privateSponsors = numbers.count - sponsors.length; sponsors.forEach(function (sponsor) { sponsorsElem.innerHTML += ` `; }); if (privateSponsors > 0) { sponsorsElem.innerHTML += ` +${privateSponsors} `; } }); }); updatePremiumSponsors(dataURL, "gold"); updatePremiumSponsors(dataURL, "silver"); updatePremiumSponsors(dataURL, "bronze"); } ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.3861222 mkdocstrings_python-1.18.2/docs/license.md0000644000000000000000000000011515051047736015542 0ustar00--- title: License hide: - feedback --- # License ``` --8<-- "LICENSE" ``` ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1728749266.2419033 mkdocstrings_python-1.18.2/docs/logo.png0000644000000000000000000016271414702517322015255 0ustar00PNG  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`././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.3861222 mkdocstrings_python-1.18.2/docs/reference/api.md0000644000000000000000000000017715051047736016637 0ustar00--- title: API reference hide: - navigation --- # ::: mkdocstrings_handlers.python options: show_submodules: true ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1756208693.049422 mkdocstrings_python-1.18.2/docs/snippets/package/__init__.py0000644000000000000000000000067515053317065021157 0ustar00from importlib import metadata 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" current_version: str = get_version(dist="mkdocstrings-python") """Current package version.""" ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1756216889.073097 mkdocstrings_python-1.18.2/docs/snippets/package/generics.py0000644000000000000000000000205015053337071021203 0ustar00"""Some module showing generics. Type Aliases: SomeType: Some type alias. """ type SomeType[Z] = int | list[Z] """Some type alias. Type parameters: Z: Some type parameter. """ class MagicBag[T: (str, bytes) = str](list[T]): """A magic bag of items. Type parameters: T: Some type. """ def __init__[U: (int, bool)](self, *args: T, flag1: U | None = None, flag2: U | None = None) -> None: """Initialize bag. Type parameters: U: Some flag type. Parameters: flag1: Some flag. flag2: Some flag. """ super().__init__(args) self.flag1 = flag1 self.flag2 = flag2 def mutate[K](self, item: T, into: K) -> K: """Shake the bag to mutate an item into something else (and eject it). Type parameters: K: Some other type. Parameters: item: The item to mutate. into: Mutate the item into something like this. Returns: The mutated item. """ ... ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1738159070.8143463 mkdocstrings_python-1.18.2/docs/snippets/package/modern.py0000644000000000000000000000013214746431737020703 0ustar00from typing import Optional, Union, List example: Optional[Union[int, List[int]]] = None ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1756216889.074097 mkdocstrings_python-1.18.2/docs/usage/configuration/docstrings.md0000644000000000000000000011506515053337071022261 0ustar00# Docstrings options [](){#option-docstring_style} ## `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 ``` WARNING: **The style is applied to the specified object only, not its members.** Local `docstring_style` options (in `:::` instructions) will only be applied to the specified object, and not its members. Instead of changing the style when rendering, we strongly recommend to *set the right style as early as possible*, for example by using the [auto-style](https://mkdocstrings.github.io/griffe/reference/docstrings/#auto-style) (sponsors only), or with a custom Griffe extension /// 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}!" ``` //// /// [](){#option-docstring_options} ## `docstring_options` - **:octicons-package-24: Type [`dict`][] :material-equal: `{}`{ title="default value" }** The options for the docstring parser. - [Google-style options](https://mkdocstrings.github.io/griffe/docstrings/#parser-options){ .external } - [Numpydoc-style options](https://mkdocstrings.github.io/griffe/docstrings/#parser-options_1){ .external } The Sphinx style does not offer any option. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: docstring_options: ignore_init_summary: false trim_doctest_flags: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: docstring_options: ignore_init_summary: true trim_doctest_flags: false ``` ```python class PrintOK: """Class docstring.""" def __init__(self): """Initialize the instance. Examples: >>> PrintOK() # doctest: +NORMALIZE_WHITESPACE ok """ print("ok") ``` /// admonition | Preview type: preview //// tab | Ignore init summary, trim doctest flags

    PrintOK

    Class docstring.

    __init__

    Examples:

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

    PrintOK

    Class docstring.

    __init__

    Initialize the instance.

    Examples:

    ```pycon >>> PrintOK() # doctest: +NORMALIZE_WHITESPACE ok ``` //// /// [](){#option-docstring_section_style} ## `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 //// /// [](){#option-merge_init_into_class} ## `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` //// /// [](){#option-relative_crossrefs} ## `relative_crossrefs` [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.9.0](../../insiders/changelog.md#1.9.0) - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Whether to enable the relative-crossref syntax. The relative-crossref syntax lets you reference the current object or its parent by prefixing a crossref identifier with dots. For example, to cross-reference the current object's `name` member, you can write `[link to name attribute][.name]`. The "current object" is the object containing the docstring being rendered. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: relative_crossrefs: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: relative_crossrefs: true ``` /// admonition | Examples type: preview ```python title="pkg/module.py" """Summary. - Link to [`module`][.]. - Link to [`module_attribute`][.module_attribute]. - Link to [`Class`][.Class]. - Link to [`class_attribute`][.Class.class_attribute]. - Link to [`instance_attribute`][.Class.instance_attribute]. - Link to [`method`][.Class.method]. """ module_attribute = 0 """Summary. - Link to [`module`][..]. - Link to [`module_attribute`][.]. - Link to [`Class`][..Class]. - Link to [`class_attribute`][..Class.class_attribute]. - Link to [`instance_attribute`][..Class.instance_attribute]. - Link to [`method`][..Class.method]. """ class Class: """Summary. - Link to [`module`][..]. - Link to [`module_attribute`][..module_attribute]. - Link to [`Class`][.]. - Link to [`class_attribute`][.class_attribute]. - Link to [`instance_attribute`][.instance_attribute]. - Link to [`method`][.method]. """ class_attribute = 0 """Summary. - Link to [`module`][...]. - Link to [`module_attribute`][...module_attribute]. - Link to [`Class`][..]. - Link to [`class_attribute`][.]. - Link to [`instance_attribute`][..instance_attribute]. - Link to [`method`][..method]. """ def __init__(self): """Summary. - Link to [`module`][...]. - Link to [`module_attribute`][...module_attribute]. - Link to [`Class`][..]. - Link to [`class_attribute`][..class_attribute]. - Link to [`instance_attribute`][..instance_attribute]. - Link to [`method`][..method]. """ self.instance_attribute = 0 """Summary. - Link to [`module`][...]. - Link to [`module_attribute`][...module_attribute]. - Link to [`Class`][..]. - Link to [`class_attribute`][..class_attribute]. - Link to [`instance_attribute`][.]. - Link to [`method`][..method]. """ def method(self): """Summary. - Link to [`module`][...]. - Link to [`module_attribute`][...module_attribute]. - Link to [`Class`][..]. - Link to [`class_attribute`][..class_attribute]. - Link to [`instance_attribute`][..instance_attribute]. - Link to [`method`][.]. """ ``` /// INFO: **There is an alternative, third-party Python handler that handles relative references: [mkdocstrings-python-xref](https://github.com/analog-garage/mkdocstrings-python-xref).** [](){#option-scoped_crossrefs} ## `scoped_crossrefs` [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.9.0](../../insiders/changelog.md#1.9.0) - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Whether to enable scoped cross-references. With scoped cross-references, you can write identifiers as if you wanted to access them from the current object's scope. The scoping rules do not exactly match Python's: you can reference members and siblings too, without prefixing with `self.` or `cls.`. The following order is applied when resolving a name in a given scope: 1. member of the current object 2. parent class 3. repeat 1-2 within parent's scope In practice, it means that the name is first looked up in members, then it is compared against the parent name (only if it's a class), then it is looked up in siblings. It continues climbing up the object tree until there's no parent, in which case it raises a name resolution error. Cross-referencing an imported object will directly link to this object if the objects inventory of the project it comes from was [loaded][inventories]. You won't be able to cross-reference it within your own documentation with scoped references, if you happen to be rendering this external object too. In that case, you can use an absolute reference or a [relative][relative_crossrefs] one instead. Another limitation is that you won't be able to reference an external package if its name can be resolved in the current object's scope. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: scoped_crossrefs: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: scoped_crossrefs: true ``` /// admonition | Examples type: preview ```python title="pkg/module.py" """Summary. - Link to [`module_attribute`][module_attribute]. - Link to [`Class`][Class]. - Link to [`class_attribute`][Class.class_attribute]. - Link to [`instance_attribute`][Class.instance_attribute]. - Link to [`method`][Class.method]. """ module_attribute = 0 """Summary. - Link to [`Class`][Class]. - Link to [`class_attribute`][Class.class_attribute]. - Link to [`instance_attribute`][Class.instance_attribute]. - Link to [`method`][Class.method]. """ class Class: """Summary. - Link to [`module_attribute`][module_attribute]. - Link to [`class_attribute`][class_attribute]. - Link to [`instance_attribute`][instance_attribute]. - Link to [`method`][method]. """ class_attribute = 0 """Summary. - Link to [`module_attribute`][module_attribute]. - Link to [`Class`][Class]. - Link to [`instance_attribute`][instance_attribute]. - Link to [`method`][method]. """ def __init__(self): """Summary. - Link to [`module_attribute`][module_attribute]. - Link to [`Class`][Class]. - Link to [`class_attribute`][class_attribute]. - Link to [`instance_attribute`][instance_attribute]. - Link to [`method`][method]. """ self.instance_attribute = 0 """Summary. - Link to [`module_attribute`][module_attribute]. - Link to [`Class`][Class]. - Link to [`class_attribute`][class_attribute]. - Link to [`method`][method]. """ def method(self): """Summary. - Link to [`module_attribute`][module_attribute]. - Link to [`Class`][Class]. - Link to [`class_attribute`][class_attribute]. - Link to [`instance_attribute`][instance_attribute]. """ ``` /// [](){#option-show_if_no_docstring} ## `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.

    //// /// [](){#option-show_docstring_attributes} ## `show_docstring_attributes` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Attributes" section 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.

    //// /// [](){#option-show_docstring_functions} ## `show_docstring_functions` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Functions" or "Methods" section 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.

    //// /// [](){#option-show_docstring_classes} ## `show_docstring_classes` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Classes" section 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.

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

    module

    Summary.

    Type Aliases:

    **Name** | **Description** ------------ | ---------------- `TypeAlias` | Some type alias.

    TypeAlias

    Summary.

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

    module

    Summary.

    TypeAlias

    Summary.

    //// /// [](){#option-show_docstring_modules} ## `show_docstring_modules` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Modules" section 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.

    //// /// [](){#option-show_docstring_description} ## `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. //// /// [](){#option-show_docstring_examples} ## `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.

    //// /// [](){#option-show_docstring_other_parameters} ## `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.

    //// /// [](){#option-show_docstring_parameters} ## `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.

    //// /// [](){#option-show_docstring_raises} ## `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.

    //// /// [](){#option-show_docstring_receives} ## `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.

    //// /// [](){#option-show_docstring_returns} ## `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.

    //// /// [](){#option-show_docstring_type_parameters} ## `show_docstring_type_parameters` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Type Parameters" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_type_parameters: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_type_parameters: false ``` ```python class AClass[X: (int, str) = str]: """Represents something. Type Parameters: X: Something. """ ``` /// admonition | Preview type: preview //// tab | With parameters

    AClass

    Represents something.

    Type Parameters:

    **Name** | **Bound or Constraints** | **Description** | **Default** ---------- | ------------------------ | --------------- | ----------- `whatever` | `(int, str)` | Something. | `str` //// //// tab | Without parameters

    AClass

    Represents something.

    //// /// [](){#option-show_docstring_warns} ## `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.

    //// /// [](){#option-show_docstring_yields} ## `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.

    //// /// ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1755598814.395122 mkdocstrings_python-1.18.2/docs/usage/configuration/general.md0000644000000000000000000004505615051047736021525 0ustar00# General options [](){#option-allow_inspection} ## `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. See also [`force_inspection`](#force_inspection). WARNING: **Packages are loaded only once.** When mkdocstrings-python collects data from a Python package (thanks to [Griffe](https://mkdocstrings.github.io/griffe/)), it collects *the entire package* and *caches it*. Next time an object from the same package is rendered, the package is retrieved from the cache and not collected again. The `allow_inspection` option will therefore only have an effect the first time a package is collected, and will do nothing for objects rendered afterwards. ```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.

    //// /// [](){#option-backlinks} ## `backlinks` [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.10.0](../../insiders/changelog.md#1.10.0) - **:octicons-package-24: Type Literal["flat", "tree", False] :material-equal: `False`{ title="default value" }** The `backlinks` option enables rendering of backlinks within your API documentation. When an arbitrary section of your documentation links to an API symbol, this link will be collected as a backlink, and rendered below your API symbol. In short, the API symbol will link back to the section that links to it. Such backlinks will help your users navigate the documentation, as they will immediately which functions return a specific symbol, or where a specific symbol is accepted as parameter, etc.. Each backlink is a list of breadcrumbs that represent the navigation, from the root page down to the given section. The available styles for rendering backlinks are **`flat`** and **`tree`**. - **`flat`** will render backlinks as a single-layer list. This can lead to repetition of breadcrumbs. - **`tree`** will combine backlinks into a tree, to remove repetition of breadcrumbs. WARNING: **Global-only option.** For now, the option only works when set globally in `mkdocs.yml`. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: backlinks: tree ``` /// admonition | Preview type: preview //// tab | Flat ![backlinks-flat](https://github.com/user-attachments/assets/f7a15b01-f194-4c55-8281-50adbb4a74af) //// //// tab | Tree ![backlinks-tree](https://github.com/user-attachments/assets/3457db21-45e1-4e03-bd8c-2e9e75dc778b) //// /// [](){#option-extensions} ## `extensions` - **:octicons-package-24: Type list[str | dict[str, dict[str, Any]]] :material-equal: `[]`{ title="default value" }** The `extensions` option lets you enable [Griffe extensions](https://mkdocstrings.github.io/griffe/extensions/), which enhance or modify the data collected from Python sources (or compiled modules). Elements in the list can be strings or dictionaries. Strings denote the path to an extension module, like `griffe_typingdoc`, or to an extension class directly, like `griffe_typingdoc.TypingDocExtension`. When using a module path, all extensions within that module will be loaded and enabled. Strings can also be the path to a Python module, and a class name separated with `:`, like `scripts/griffe_extensions.py` or `scripts/griffe_extensions.py:MyExtension`. Dictionaries have a single key, which is the module/class path (as a dot-separated qualifier or file path and colon-separated class name, like above), and its value is another dictionary specifying options that will be passed when to class constructors when instantiating extensions. WARNING: **Packages are loaded only once.** When mkdocstrings-python collects data from a Python package (thanks to [Griffe](https://mkdocstrings.github.io/griffe/)), it collects *the entire package* and *caches it*. Next time an object from the same package is rendered, the package is retrieved from the cache and not collected again. Only the extensions specified the first time the package is loaded will be used. You cannot use a different set of extensions for specific objects rendered afterwards, and you cannot deactivate extensions for objects rendered afterwards either. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: extensions: - griffe_sphinx - griffe_pydantic: {schema: true} - scripts/exts.py:DynamicDocstrings: paths: [mypkg.mymod.myobj] ``` ```md title="or in docs/some_page.md (local configuration)" ::: your_package.your_module.your_func options: extensions: - griffe_typingdoc ``` [](){#option-extra} ## `extra` - **:octicons-package-24: Type [`dict`][] :material-equal: `{}`{ title="default value" }** The `extra` option lets you inject additional variables into the Jinja context used when rendering templates. You can then use this extra context in your [overridden templates][templates]. Local `extra` options will be merged into the global `extra` option: ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: extra: hello: world ``` ```md title="in docs/some_page.md (local configuration)" ::: your_package.your_module.your_func options: extra: foo: bar ``` ...will inject both `hello` and `foo` into the Jinja context when rendering `your_package.your_module.your_func`. > WARNING: Previously, extra options were supported directly under the `options` key. > > ```yaml > plugins: > - mkdocstrings: > handlers: > python: > options: > hello: world > ``` > > Now that we introduced optional validation of options and automatic JSON schema generation thanks to Pydantic, we require extra options to be put under `options.extra`. Extra options directly under `options` are still supported, but deprecated, and will emit deprecation warnings. Support will be removed in a future version of mkdocstrings-python. [](){#option-find_stubs_package} ## `find_stubs_package` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** When looking for documentation specified in [autodoc instructions][autodoc syntax] (`::: identifier`), also look for the stubs package as defined in [PEP 561](https://peps.python.org/pep-0561/) if it exists. This is useful when most of your documentation is separately provided by such a package and not inline in your main package. WARNING: **Packages are loaded only once.** When mkdocstrings-python collects data from a Python package (thanks to [Griffe](https://mkdocstrings.github.io/griffe/)), it collects *the entire package* and *caches it*. Next time an object from the same package is rendered, the package is retrieved from the cache and not collected again. The `find_stubs_package` option will therefore only have an effect the first time a package is collected, and will do nothing for objects rendered afterwards. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: find_stubs_package: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: your_package.your_module.your_func options: find_stubs_package: true ``` ```python title="your_package/your_module.py" def your_func(a, b): # Function code ... # rest of your code ``` ```python title="your_package-stubs/your_module.pyi" def your_func(a: int, b: str): """ """ ... # rest of your code ``` /// admonition | Preview type: preview //// tab | With find_stubs_package

    your_func

    Function docstring

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

    your_func

    //// /// [](){#option-force_inspection} ## `force_inspection` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Whether to force inspecting modules (importing them) even if their source code is available. This option is useful when you know that dynamic analysis (inspection) yields better results than static analysis. Do not use this blindly: the recommended approach is to write a Griffe extension that will improve extracted API data. See [How to selectively inspect objects](https://mkdocstrings.github.io/griffe/guide/users/how-to/selectively-inspect/). See also [`allow_inspection`](#allow_inspection). ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: force_inspection: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.object options: force_inspection: true ``` WARNING: **Packages are loaded only once.** When mkdocstrings-python collects data from a Python package (thanks to [Griffe](https://mkdocstrings.github.io/griffe/)), it collects *the entire package* and *caches it*. Next time an object from the same package is rendered, the package is retrieved from the cache and not collected again. The `force_inspection` option will therefore only have an effect the first time a package is collected, and will do nothing for objects rendered afterwards. [](){#option-preload_modules} ## `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.

    //// /// [](){#option-show_bases} ## `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.

    //// /// [](){#option-show_inheritance_diagram} ## `show_inheritance_diagram` [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.7.0](../../insiders/changelog.md#1.7.0) - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Show the inheritance diagram of a class using [Mermaid](https://mermaid.js.org/). With this option enabled, an inheritance diagram (as a flowchart) will be displayed after a class signature. Each node will act as a cross-reference and will bring you to the relevant class' documentation when clicking on it. It should work out of the box with [Material for MkDocs][]. For other themes, you must include Mermaid's Javascript code manually: ```yaml title="mkdocs.yml" extra_javascript: - https://unpkg.com/mermaid@10.9.0/dist/mermaid.min.js ``` ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_inheritance_diagram: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.object options: show_inheritance_diagram: false ``` /// admonition | Preview type: preview With the following classes: ```python class SuperAbstract: """Super abstract class.""" class Mixin1: """Mixin 1.""" class Abstract(SuperAbstract, Mixin1): """Abstract class.""" class Mixin2A: """Mixin 2A.""" class Mixin2B(Mixin2A): """Mixin 2B.""" class Concrete(Abstract, Mixin2B): """Concrete class.""" class SuperConcrete(Concrete): """Super concrete class.""" ``` The diagram for `SuperConcrete` will look like this: ```mermaid flowchart TD SuperConcrete[SuperConcrete] Concrete[Concrete] Abstract[Abstract] SuperAbstract[SuperAbstract] Mixin1[Mixin1] Mixin2B[Mixin2B] Mixin2A[Mixin2A] Concrete --> SuperConcrete Abstract --> Concrete SuperAbstract --> Abstract Mixin1 --> Abstract Mixin2B --> Concrete Mixin2A --> Mixin2B ``` *Nodes are not clickable in this example because these classes do not exist in our documentation.* /// [](){#option-show_source} ## `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.

    //// /// [](){#option-skip_local_inventory} ## `skip_local_inventory` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Whether to skip registering symbols in the objects inventory. With this option enabled, re-rendering docstrings for objects from external inventories is possible with their cross-references pointing to the original external inventory, not local. Similarly, it becomes possible to render the same symbol several times in the same documentation, with only one canonical location being used for cross-references (preventing confusion in mkdocs-autorefs). ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: skip_local_inventory: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: skip_local_inventory: true ``` /// admonition | Preview type: preview //// tab | Without `skip_local_inventory` ```md exec="on" ::: bisect.bisect_left options: heading_level: 3 skip_local_inventory: false show_docstring_description: false ``` Notice how [`bisect.bisect_left`][] now points to the section above. //// //// tab | With `skip_local_inventory` ```md exec="on" ::: bisect.bisect_right inventories: - https://docs.python.org/3/objects.inv options: heading_level: 3 skip_local_inventory: true show_docstring_description: false ``` Notice how [`bisect.bisect_right`][] points to the original Python documentation. //// /// ././@PaxHeader0000000000000000000000000000003200000000000010210 xustar0026 mtime=1756388868.16401 mkdocstrings_python-1.18.2/docs/usage/configuration/headings.md0000644000000000000000000006072715054057004021664 0ustar00# Headings options [](){#option-heading} ## `heading` - **:octicons-package-24: Type [`str`][] :material-equal: `""`{ title="default value" }** A custom string to use as the heading of the root object (i.e. the object specified directly after the identifier `:::`). This will override the default heading generated by the plugin. See also the [`toc_label` option][option-toc_label]. WARNING: **Not advised to be used as a global configuration option.** This option is not advised to be used as a global configuration option, as it will override the default heading for all objects. It is recommended to use it only in specific cases where you want to override the heading for a specific object. ```md title="in docs/some_page.md (local configuration)" ::: path.to.module options: heading: "My fancy module" ``` [](){#option-heading_level} ## `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.

    //// /// [](){#option-parameter_headings} ## `parameter_headings` [:octicons-tag-24: Insiders 1.6.0](../../insiders/changelog.md#1.6.0) - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Whether to render headings for function/method parameters. With this option enabled, each function/method parameter (including parameters of `__init__` methods merged in their parent class with the [`merge_init_into_class`][] option) gets a permalink, an entry in the Table of Contents, and an entry in the generated objects inventory (unless [`skip_local_inventory`][] is enabled). The permalink and inventory entry allow cross-references from internal and external pages. The identifier used in the permalink and inventory is of the following form: `path.to.function(param_name)`. To manually cross-reference a parameter, you can therefore use this Markdown syntax: ```md - Class parameter: [`param`][package.module.Class(param)] - Method parameter: [`param`][package.module.Class.method(param)] - Function parameter: [`param`][package.module.function(param)] - Variadic positional parameters: [`*args`][package.module.function(*args)] - Variadic keyword parameters: [`**kwargs`][package.module.function(**kwargs)] ``` Enabling this option along with [`signature_crossrefs`][] will automatically render cross-references to parameters in class/function/method signatures and attributes values. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: parameter_headings: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: parameter_headings: true ``` /// admonition | Preview: Cross-references type: preview ```md exec="on" ::: package.get_version options: heading_level: 3 parameter_headings: true docstring_section_style: list ::: package.current_version options: heading_level: 3 line_length: 100 ``` /// /// admonition | Preview: Parameter sections type: preview //// tab | Table style ```md exec="on" ::: package.get_version options: heading_level: 3 show_root_heading: false show_root_toc_entry: false parameter_headings: true docstring_section_style: table show_docstring_returns: false show_docstring_description: false ``` //// //// tab | List style ```md exec="on" ::: package.get_version options: heading_level: 3 show_root_heading: false show_root_toc_entry: false parameter_headings: true docstring_section_style: list show_docstring_returns: false show_docstring_description: false ``` //// //// tab | Spacy style ```md exec="on" ::: package.get_version options: heading_level: 3 show_root_heading: false show_root_toc_entry: false parameter_headings: true docstring_section_style: spacy show_docstring_returns: false show_docstring_description: false ``` //// /// /// admonition | Preview: Table of contents (with symbol types) type: preview get_version
    dist To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types). /// [](){#option-show_root_heading} ## `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.

    //// /// [](){#option-show_root_toc_entry} ## `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" } //// /// [](){#option-show_root_full_path} ## `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.

    //// /// [](){#option-show_root_members_full_path} ## `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.

    //// /// [](){#option-show_object_full_path} ## `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.

    //// /// [](){#option-show_category_heading} ## `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 objects.** 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.

    //// /// [](){#option-show_symbol_type_heading} ## `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.

    //// /// [](){#option-show_symbol_type_toc} ## `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
    //// /// [](){#option-toc_label} ## `toc_label` - **:octicons-package-24: Type [`str`][] :material-equal: `""`{ title="default value" }** A custom string to use as the label in the Table of Contents for the root object (i.e. the one specified directly after the identifier `:::`). This will override the default label generated by the plugin. See also the [`heading` option][option-heading]. WARNING: **Not advised to be used as a global configuration option.** This option is not advised to be used as a global configuration option, as it will override the default label for all objects. It is recommended to use it only in specific cases where you want to override the label for a specific object. NOTE: **Use with/without `heading`.** If you use this option without specifying a custom `heading`, the default heading will be used in the page, but the label in the Table of Contents will be the one you specified. By providing both an option for `heading` and `toc_label`, we leave the customization entirely up to you. ```md title="in docs/some_page.md (local configuration)" ::: path.to.module options: heading: "My fancy module" toc_label: "My fancy module" ``` [](){#option-type_parameter_headings} ## `type_parameter_headings` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Whether to render headings for generic class, function/method and type alias type parameters. With this option enabled, each type parameter of a generic object (including type parameters of `__init__` methods merged in their parent class with the [`merge_init_into_class`][] option) gets a permalink, an entry in the Table of Contents, and an entry in the generated objects inventory. The permalink and inventory entry allow cross-references from internal and external pages. Enabling this option along with [`signature_crossrefs`][] will automatically render cross-references to type parameters in class/function/method/type alias signatures. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: type_parameter_headings: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: type_parameter_headings: true ``` /// admonition | Preview: Cross-references type: preview ```md exec="on" ::: package.generics options: show_root_heading: false heading_level: 3 docstring_section_style: list show_bases: true summary: false separate_signature: true show_signature_type_parameters: true show_inheritance_diagram: false type_parameter_headings: true ``` /// /// admonition | Preview: Type parameter sections type: preview //// tab | Table style ```md exec="on" ::: package.generics.MagicBag options: members: false heading_level: 3 show_root_heading: false show_root_toc_entry: false parameter_headings: true docstring_section_style: table show_docstring_description: false show_docstring_parameters: false show_docstring_returns: false show_inheritance_diagram: false ``` //// //// tab | List style ```md exec="on" ::: package.generics.MagicBag options: members: false heading_level: 3 show_root_heading: false show_root_toc_entry: false parameter_headings: true docstring_section_style: list show_docstring_description: false show_docstring_parameters: false show_docstring_returns: false show_inheritance_diagram: false ``` //// //// tab | Spacy style ```md exec="on" ::: package.generics.MagicBag options: members: false heading_level: 3 show_root_heading: false show_root_toc_entry: false parameter_headings: true docstring_section_style: spacy show_docstring_description: false show_docstring_parameters: false show_docstring_returns: false show_inheritance_diagram: false ``` //// /// /// admonition | Preview: Table of contents (with symbol types) type: preview mutate
    U To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types). /// ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1756216889.074097 mkdocstrings_python-1.18.2/docs/usage/configuration/members.md0000644000000000000000000004557015053337071021537 0ustar00# Members options [](){#option-members} ## `members` - **:octicons-package-24: Type list[str] | bool | None :material-equal: `None`{ title="default value" }** An explicit list of members to render. Only members declared in this list will be rendered. A member without a docstring will still be rendered, even if [`show_if_no_docstring`][] is set to false. The members will be rendered in the specified order, regardless of the value of [`members_order`][]. **Note that members will still be grouped by category, according to the [`group_by_category`][] option.** Passing a falsy value (`no`, `false` in YAML) or an empty list (`[]`) will tell the Python handler not to render any member. Passing a truthy value (`yes`, `true` in YAML) will tell the Python handler to render every member. Any given value, except for an explicit `None` (`null` in YAML) will tell the handler to ignore [`filters`][] for the object's members. Filters will still be applied to the next layers of members (grand-children). ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: members: - hello # (1) ``` 1. :warning: Most of the time it won't make sense to use this option at the global level. ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: members: - ThisClass - this_function ``` ```python title="package/module.py" """Module docstring.""" def this_function(): """Function docstring.""" class ThisClass: """Class docstring.""" def method(self): """Method docstring.""" this_attribute = 0 """Attribute docstring.""" ``` /// admonition | Preview type: preview //// tab | With `members: true`

    Module docstring.

    this_function

    Function docstring.

    ThisClass

    Class docstring.

    method

    Method docstring.

    this_attribute

    Attribute docstring.

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

    Module docstring.

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

    Module docstring.

    ThisClass

    Class docstring.

    method

    Method docstring.

    //// /// INFO: **The default behavior (with unspecified `members` or `members: null`) is to use [`filters`][].** [](){#option-inherited_members} ## `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.

    //// /// [](){#option-members_order} ## `members_order` - **:octicons-package-24: Type `str | list[str]` :material-equal: `"alphabetical"`{ title="default value" }** The members ordering to use. Possible values: - `__all__` ([:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.12.0](../../insiders/changelog.md#1.12.0)): Order according to `__all__` attributes. Since classes do not define `__all__` attributes, you can specify a second ordering method by using a list. - `alphabetical`: Order by the members names. - `source`: Order members as they appear in the source file. The order applies for all members, recursively. The order will be ignored for members that are explicitely sorted using the [`members`][] option. **Note that members will still be grouped by category, according to the [`group_by_category`][] option.** ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: members_order: alphabetical ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: members_order: source ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: members_order: [__all__, 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.

    //// /// [](){#option-filters} ## `filters` - **:octicons-package-24: Type list[str] | Literal["public"] | None :material-equal: `["!^_[^_]"]`{ title="default value" }** A list of filters, or `"public"`. **Filtering methods** [](){#option-filters-public} [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.11.0](../../insiders/changelog.md#1.11.0) The `public` filtering method will include only public objects: those added to the `__all__` attribute of modules, or not starting with a single underscore. Special methods and attributes ("dunder" methods/attributes, starting and ending with two underscores), like `__init__`, `__call__`, `__mult__`, etc., are always considered public. **List of filters** 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: public ``` ```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) /// [](){#option-group_by_category} ## `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.

    //// /// [](){#option-show_submodules} ## `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.

    //// /// [](){#option-summary} ## `summary` [: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`, `type_aliases`, 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).
    //// /// [](){#option-show_labels} ## `show_labels` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to show labels of the members. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_labels: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: show_labels: false ``` ```python title="package/module.py" class SomeClass: some_attr: int ``` /// admonition | Preview type: preview //// tab | With labels some_attr: int instance-attribute //// //// tab | Without labels some_attr: int //// /// ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1756216889.074097 mkdocstrings_python-1.18.2/docs/usage/configuration/signatures.md0000644000000000000000000004374615053337071022274 0ustar00# Signatures options [](){#option-annotations_path} ## `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. //// /// [](){#option-line_length} ## `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 a formatter and the specified line length. The handler will automatically try to format using : 1. [Black] 2. [Ruff] If a formatter is not found, 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")
    //// /// [](){#option-modernize_annotations} ## `modernize_annotations` [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.8.0](../../insiders/changelog.md#1.8.0) — **This feature also requires [Griffe Insiders](https://mkdocstrings.github.io/griffe/insiders/) to be installed.** - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Modernize annotations with latest features and PEPs of the Python language. The Python language keeps evolving, and often library developers must continue to support a few minor versions of Python. Therefore they cannot use some features that were introduced in the latest versions. Yet this doesn't mean they can't enjoy latest features in their docs: Griffe allows to "modernize" expressions, for example by replacing `typing.Union` with [PEP 604][pep-604] type unions `|`. Thanks to this, mkdocstrings' Python handler can automatically transform type annotations into their modern equivalent. This improves consistency in your docs, and shows users how to use your code with the latest features of the language. [pep-604]: https://peps.python.org/pep-0604/ Modernizations applied: - `typing.Dict[A, B]` becomes `dict[A, B]` - `typing.List[A]` becomes `list[A]` - `typing.Set[A]` becomes `set[A]` - `typing.Tuple[A]` becomes `tuple[A]` - `typing.Union[A, B]` becomes `A | B` - `typing.Optional[A]` becomes `A | None` ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: modernize_annotations: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.object options: modernize_annotations: false ``` /// admonition | Preview type: preview ```python --8<-- "docs/snippets/package/modern.py" ``` //// tab | Unchanged annotations ```md exec="on" ::: package.modern.example options: modernize_annotations: false show_symbol_type_heading: false show_labels: false ``` //// //// tab | Modernized annotations ```md exec="on" ::: package.modern.example options: modernize_annotations: true show_symbol_type_heading: false show_labels: false ``` //// /// [](){#option-overloads_only} ## `overloads_only` Whether to hide the implementation signature if the overloads are shown with [`show_overloads`][]. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: overloads_only: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: overloads_only: true ``` /// admonition | Preview type: preview //// tab | With overloads only

    function

    ```python @overload function(param1: int): ... @overload function(param1: str): ... ``` Function docstring. //// //// tab | Without overloads only

    function

    ```python @overload function(param1: int): ... @overload function(param1: str): ... function(param1: str | int) ``` Function docstring. //// /// [](){#option-show_signature} ## `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.

    //// /// [](){#option-show_signature_annotations} ## `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.

    //// /// [](){#option-show_signature_type_parameters} ## `show_signature_type_parameters` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** Show the type parameters in generic classes, methods, functions and type aliases signatures. Since the heading can become quite long when type parameters 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 show_signature_type_parameters: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: separate_signature: true show_signature_annotations: true show_signature_type_parameters: false ``` /// admonition | Preview type: preview //// tab | With signature type parameters

    function

    ```python function[T, *R](param: T) -> tuple[*R] ```

    Function docstring.

    //// //// tab | Without signature type parameters

    function

    ```python function(param: T) -> tuple[*R] ```

    Function docstring.

    //// /// [](){#option-separate_signature} ## `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 a formatter and the specified [line length][line_length]. The handler will automatically try to format using : 1. [Black] 2. [Ruff] If a formatter is not found, 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.

    //// /// [](){#option-show_attribute_values} ## `show_attribute_values` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Show initial values of attributes in classes. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_attribute_values: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.object options: show_attribute_values: true ``` ```python title="package/module.py" class SomeClass: def __init__(self): self.some_attr = 1 ``` /// admonition | Preview type: preview //// tab | With attribute values visible

    SomeClass

    some_attr = 1

    //// //// tab | With attribute values hidden

    SomeClass

    some_attr

    //// /// [](){#option-show_overloads} ## `show_overloads` Whether to render function / method overloads. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_overloads: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_overloads: false ``` /// admonition | Preview type: preview //// tab | With overloads

    function

    ```python @overload function(param1: int): ... @overload function(param1: str): ... function(param1: str | int) ``` Function docstring. //// //// tab | Without overloads

    function

    ```python function(param1: str | int) ``` Function docstring. //// /// [](){#option-signature_crossrefs} ## `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.

    //// /// [](){#option-unwrap_annotated} ## `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 ``` ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1756216889.074097 mkdocstrings_python-1.18.2/docs/usage/customization.md0000644000000000000000000003670215053337071020143 0ustar00# Customization It is possible to customize the output of the generated documentation with CSS and/or by overriding templates. ## CSS classes Our templates add [CSS](https://www.w3schools.com/Css/) classes to many HTML elements to make it possible for users to customize the resulting look and feel. To add CSS rules and style mkdocstrings' output, put them in a CSS file in your docs folder, for example in `docs/css/mkdocstrings.css`, and reference this file in [MkDocs' `extra_css` configuration option](https://www.mkdocs.org/user-guide/configuration/#extra_css): ```yaml title="mkdocs.yml" extra_css: - css/mkdocstrings.css ``` Example: ```css title="docs/css/mkdocstrings.css" .doc-section-title { font-weight: bold; } ``` The following CSS classes are used in the generated HTML: - `doc`: on all the following elements - `doc-children`: on `div`s containing the children of an object - `doc-object`: on `div`s containing an object - `doc-attribute`: on `div`s containing an attribute - `doc-class`: on `div`s containing a class - `doc-function`: on `div`s containing a function - `doc-module`: on `div`s containing a module - `doc-type_alias`: on `div`s containing a type alias - `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, type_alias) - `doc-contents`: on `div`s wrapping the docstring then the children (if any) - `first`: same, but only on the root object's contents `div` - `doc-labels`: on `span`s wrapping the object's labels - `doc-label`: on `small` elements containing a label - `doc-label-LABEL`: same, where `LABEL` is replaced by the actual label - `doc-section-title`: on section titles (depend on the [selected style for section rendering][docstring_style]) - `doc-section-item`: on section items (depend on the [selected style for section rendering][docstring_style]) - `doc-md-description`: on `div`s containing HTML descriptions converted from Markdown docstrings - `doc-symbol`: on `code` tags of symbol types - `doc-symbol-heading`: on symbol types in headings - `doc-symbol-toc`: on symbol types in the ToC - `doc-symbol-KIND`: specific to the kind of object (`module`, `class`, `function`, `method`, `attribute`, `type_alias`) /// 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-parameter-fg-color: #df50af; --doc-symbol-type_parameter-fg-color: #df50af; --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-type_alias-fg-color: #d1b619; --doc-symbol-module-fg-color: #ff0060; --doc-symbol-parameter-bg-color: #df50af1a; --doc-symbol-type_parameter-bg-color: #df50af1a; --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-type_alias-bg-color: #d1b6191a; --doc-symbol-module-bg-color: #ff00601a; } [data-md-color-scheme="slate"] { --doc-symbol-parameter-fg-color: #ffa8cc; --doc-symbol-type_parameter-fg-color: #ffa8cc; --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-type_alias-fg-color: #46c2cb; --doc-symbol-module-fg-color: #f2f7a1; --doc-symbol-parameter-bg-color: #ffa8cc1a; --doc-symbol-type_parameter-bg-color: #ffa8cc1a; --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-type_alias-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-parameter-fg-color: #df50af; --doc-symbol-type_parameter-fg-color: #df50af; --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-type_alias-fg-color: #d1b619; --doc-symbol-module-fg-color: #ff0060; --doc-symbol-parameter-bg-color: #df50af1a; --doc-symbol-type_parameter-bg-color: #df50af1a; --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-type_alias-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-parameter::after { content: "P"; } .doc-symbol-type_parameter::after { content: "P"; } .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-type_alias::after { content: "T"; } .doc-symbol-module::after { content: "M"; } ``` /// admonition | Preview type: preview
    • Parameter:
    • Type Parameter:
    • Attribute:
    • Function:
    • Method:
    • Class:
    • Type Alias:
    • 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/main/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.Module] instance. #### `type_alias.html` - `heading`: The class heading. - `labels`: The class labels. - `signature`: The class signature. - `contents`: The class contents: bases, docstring, source and children blocks. - `docstring`: The class docstring. Available context: - `config`: The handler configuration (dictionary). - `type_alias`: The [TypeAlias][griffe.TypeAlias] 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.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.Function] instance. #### `attribute.html` - `heading`: The attribute heading. - `labels`: The attribute labels. - `signature`: The attribute signature. - `contents`: The attribute contents: docstring block. - `docstring`: The attribute docstring. Available context: - `config`: The handler configuration (dictionary). - `attribute`: The [Attribute][griffe.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/type_aliases.html`, `docstring/type_parameters.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.DocstringSection] instance (see `DocstringSection*` subclasses). ### Syntax highlight in signatures You can customize the colors in syntax highlighted signatures. If you are using the [Material for MkDocs] theme, here are some customization examples: ```css /* Fancier color for operators such as * and |. */ .doc-signature .o { color: var(--md-code-hl-special-color); } /* Fancier color for constants such as None, True, and False. */ .doc-signature .kc { color: var(--md-code-hl-constant-color); } /* Fancier color for built-in types (only useful when cross-references are used). */ .doc-signature .n > a[href^="https://docs.python.org/"][href*="/functions.html#"], .doc-signature .n > a[href^="https://docs.python.org/"][href*="/stdtypes.html#"] { color: var(--md-code-hl-constant-color); } ``` For other themes, use their own CSS variables, or use plain colors such as `violet` or `#2987f2`. ## Style recommendations [](){#recommended-style-material} ### Material Here are some CSS rules for the [Material for MkDocs] theme: ```css --8<-- "docs/css/mkdocstrings.css" ``` [](){#recommended-style-readthedocs} ### ReadTheDocs Here are some CSS rules for the built-in ReadTheDocs theme: ```css /* Indentation. */ div.doc-contents:not(.first) { padding-left: 25px; border-left: .05rem solid rgba(200, 200, 200, 0.2); } ``` ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1755598814.395122 mkdocstrings_python-1.18.2/docs/usage/docstrings/google.md0000644000000000000000000000150015051047736020656 0ustar00# 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/). ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1738159072.2576532 mkdocstrings_python-1.18.2/docs/usage/docstrings/numpy.md0000644000000000000000000000100114746431740020550 0ustar00# 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/). ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1738159071.7509959 mkdocstrings_python-1.18.2/docs/usage/docstrings/sphinx.md0000644000000000000000000000041114746431740020715 0ustar00# 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/). ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1738159077.0142326 mkdocstrings_python-1.18.2/docs/usage/extensions.md0000644000000000000000000000121014746431745017427 0ustar00# 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" ``` ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1755598814.405122 mkdocstrings_python-1.18.2/docs/usage/index.md0000644000000000000000000002356115051047736016345 0ustar00# 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. [](){#setting-inventories} #### `inventories` This option is used to load Sphinx-compatible objects inventories from other documentation sites. For example, you can load the standard library objects inventory like this: ```yaml title="mkdocs.yml" plugins: - mkdocstrings: handlers: python: inventories: - https://docs.python.org/3/objects.inv ``` When loading 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 load 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 inventory options, which allows to select the inventory domains to load. 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: inventories: - url: https://docs.python-requests.org/en/master/objects.inv domains: [std, py] ``` [](){#setting-load_external_modules} #### `load_external_modules` This option allows resolving aliases (imports) to any external module. Modules are considered external when they are not part of the package your are injecting documentation for. Setting this option to `True` will tell the handler to resolve aliases recursively when they are made public through the [`__all__`][__all__] variable. By default, the handler will only resolve aliases when they point at a private sibling of the source package, for example aliases going from `ast` to `_ast`. Set `load_external_modules` to `False` to prevent even that. WARNING: **Use with caution** This can load a *lot* of modules through [Griffe], slowing down your build or triggering errors that Griffe does not yet handle. **We recommend using the [`preload_modules`][] option instead**, which acts as an include-list rather than as include-all. Example: ```yaml title="mkdocs.yml" plugins: - mkdocstrings: handlers: python: load_external_modules: true ``` [__all__]: https://docs.python.org/3/tutorial/modules.html#importing-from-a-package [](){#setting-locale} #### ~~`locale`~~ **Deprecated.** Use mkdocstrings' own `locale` setting. ~~The locale to use when translating template strings.~~ [](){#setting-paths} #### `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). [](){#setting-options} ### 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 ## 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 ``` /// ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1756216889.074097 mkdocstrings_python-1.18.2/duties.py0000644000000000000000000002116415053337071014520 0ustar00"""Development tasks.""" from __future__ import annotations import os import re import sys from contextlib import contextmanager from functools import wraps from importlib.metadata import version as pkgversion from pathlib import Path from typing import TYPE_CHECKING, Any, Callable from duty import duty, tools if TYPE_CHECKING: from collections.abc import Iterator from duty.context import Context PY_SRC_PATHS = (Path(_) for _ in ("src", "tests", "duties.py", "scripts")) PY_SRC_LIST = tuple(str(_) for _ in PY_SRC_PATHS) PY_SRC = " ".join(PY_SRC_LIST) CI = os.environ.get("CI", "0") in {"1", "true", "yes", ""} WINDOWS = os.name == "nt" PTY = not WINDOWS and not CI MULTIRUN = os.environ.get("MULTIRUN", "0") == "1" def pyprefix(title: str) -> str: if MULTIRUN: prefix = f"(python{sys.version_info.major}.{sys.version_info.minor})" return f"{prefix:14}{title}" return title def not_from_insiders(func: Callable) -> Callable: @wraps(func) def wrapper(ctx: Context, *args: Any, **kwargs: Any) -> None: origin = ctx.run("git config --get remote.origin.url", silent=True) if "pawamoy-insiders/griffe" in origin: ctx.run( lambda: False, title="Not running this task from insiders repository (do that from public repo instead!)", ) return func(ctx, *args, **kwargs) return wrapper @contextmanager def material_insiders() -> Iterator[bool]: if "+insiders" in pkgversion("mkdocs-material"): os.environ["MATERIAL_INSIDERS"] = "true" try: yield True finally: os.environ.pop("MATERIAL_INSIDERS") else: yield False def _get_changelog_version() -> str: changelog_version_re = re.compile(r"^## \[(\d+\.\d+\.\d+)\].*$") with Path(__file__).parent.joinpath("CHANGELOG.md").open("r", encoding="utf8") as file: return next(filter(bool, map(changelog_version_re.match, file))).group(1) # type: ignore[union-attr] @duty def changelog(ctx: Context, bump: str = "") -> None: """Update the changelog in-place with latest commits. Parameters: bump: Bump option passed to git-changelog. """ ctx.run(tools.git_changelog(bump=bump or None), title="Updating changelog") ctx.run(tools.yore.check(bump=bump or _get_changelog_version()), title="Checking legacy code") @duty(pre=["check-quality", "check-types", "check-docs", "check-api"]) def check(ctx: Context) -> None: """Check it all!""" @duty def check_quality(ctx: Context) -> None: """Check the code quality.""" ctx.run( tools.ruff.check(*PY_SRC_LIST, config="config/ruff.toml"), title=pyprefix("Checking code quality"), ) @duty(skip_if=sys.version_info < (3, 13), skip_reason=pyprefix("Skipped: docs require modern generics syntax")) def check_docs(ctx: Context) -> None: """Check if the documentation builds correctly.""" Path("htmlcov").mkdir(parents=True, exist_ok=True) Path("htmlcov/index.html").touch(exist_ok=True) with material_insiders(): ctx.run( tools.mkdocs.build(strict=True, verbose=True), title=pyprefix("Building documentation"), ) @duty def check_types(ctx: Context) -> None: """Check that the code is correctly typed.""" os.environ["MYPYPATH"] = "src" os.environ["FORCE_COLOR"] = "1" ctx.run( tools.mypy(*PY_SRC_LIST, config_file="config/mypy.ini"), title=pyprefix("Type-checking"), # TODO: Update when Pydantic supports 3.14. nofail=sys.version_info >= (3, 14), ) @duty def check_api(ctx: Context, *cli_args: str) -> None: """Check for API breaking changes.""" ctx.run( tools.griffe.check("mkdocstrings_handlers.python", search=["src"], color=True).add_args(*cli_args), title="Checking for API breaking changes", nofail=True, ) @duty(skip_if=sys.version_info < (3, 13), skip_reason=pyprefix("Skipped: docs require modern generics syntax")) def docs(ctx: Context, *cli_args: str, host: str = "127.0.0.1", port: int = 8000) -> None: """Serve the documentation (localhost:8000). Parameters: host: The host to serve the docs from. port: The port to serve the docs on. """ with material_insiders(): ctx.run( tools.mkdocs.serve(dev_addr=f"{host}:{port}").add_args(*cli_args), title="Serving documentation", capture=False, ) @duty(skip_if=sys.version_info < (3, 13), skip_reason=pyprefix("Skipped: docs require modern generics syntax")) def docs_deploy(ctx: Context, *, force: bool = False) -> None: """Deploy the documentation to GitHub pages. Parameters: force: Whether to force deployment, even from non-Insiders version. """ 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, allow_overrides=False) if "pawamoy-insiders/mkdocstrings-python" in origin: ctx.run( "git remote add upstream git@github.com:mkdocstrings/python", silent=True, nofail=True, allow_overrides=False, ) ctx.run( tools.mkdocs.gh_deploy(remote_name="upstream", force=True), title="Deploying documentation", ) elif force: ctx.run( tools.mkdocs.gh_deploy(force=True), title="Deploying documentation", ) else: ctx.run( lambda: False, title="Not deploying docs from public repository (do that from insiders instead!)", nofail=True, ) @duty def format(ctx: Context) -> None: """Run formatting tools on the code.""" ctx.run( tools.ruff.check(*PY_SRC_LIST, config="config/ruff.toml", fix_only=True, exit_zero=True), title="Auto-fixing code", ) ctx.run(tools.ruff.format(*PY_SRC_LIST, config="config/ruff.toml"), title="Formatting code") @duty def build(ctx: Context) -> None: """Build source and wheel distributions.""" ctx.run( tools.build(), title="Building source and wheel distributions", pty=PTY, ) @duty @not_from_insiders def publish(ctx: Context) -> None: """Publish source and wheel distributions to PyPI.""" if not Path("dist").exists(): ctx.run("false", title="No distribution files found") dists = [str(dist) for dist in Path("dist").iterdir()] ctx.run( tools.twine.upload(*dists, skip_existing=True), title="Publishing source and wheel distributions to PyPI", pty=PTY, ) @duty(post=["build", "publish", "docs-deploy"]) @not_from_insiders def release(ctx: Context, version: str = "") -> None: """Release a new Python package. Parameters: version: The new version number to use. """ if not (version := (version or input("> Version to release: ")).strip()): ctx.run("false", title="A version must be provided") ctx.run("git add pyproject.toml CHANGELOG.md", title="Staging files", pty=PTY) ctx.run(["git", "commit", "-m", f"chore: Prepare release {version}"], title="Committing changes", pty=PTY) ctx.run(f"git tag {version}", title="Tagging commit", pty=PTY) ctx.run("git push", title="Pushing commits", pty=False) ctx.run("git push --tags", title="Pushing tags", pty=False) @duty(silent=True, aliases=["cov"]) def coverage(ctx: Context) -> None: """Report coverage as text and HTML.""" ctx.run(tools.coverage.combine(), nofail=True) ctx.run(tools.coverage.report(rcfile="config/coverage.ini"), capture=False) ctx.run(tools.coverage.html(rcfile="config/coverage.ini")) @duty def test(ctx: Context, *cli_args: str, match: str = "", snapshot: str = "report") -> None: # noqa: PT028 """Run the test suite. Parameters: match: A pytest expression to filter selected tests. snapshot: Whether to "create", "fix", "trim", or "update" snapshots. """ py_version = f"{sys.version_info.major}{sys.version_info.minor}" os.environ["COVERAGE_FILE"] = f".coverage.{py_version}" args = list(cli_args) if snapshot == "disable" or not snapshot: args = ["-n", "auto", "--inline-snapshot=disable"] else: args = [f"--inline-snapshot={snapshot}"] ctx.run( tools.pytest( "tests", config_file="config/pytest.ini", select=match, color="yes", ).add_args(*args), title=pyprefix("Running tests"), ) ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1756216889.074097 mkdocstrings_python-1.18.2/mkdocs.yml0000644000000000000000000001514415053337071014655 0ustar00site_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 hooks: - scripts/mkdocs_hooks.py 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 - API reference: reference/api.md - 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.instant.preview - navigation.path - 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 extra_javascript: - js/feedback.js markdown_extensions: - abbr - attr_list - admonition - callouts: strip_period: no - footnotes - md_in_html - pymdownx.blocks.admonition - pymdownx.blocks.details - pymdownx.blocks.tab: alternate_style: true slugify: !!python/object/apply:pymdownx.slugs.slugify kwds: case: lower - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.highlight: pygments_lang_class: true - pymdownx.magiclink - pymdownx.snippets: auto_append: [docs/.glossary.md] base_path: [!relative $config_dir] check_paths: true - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true slugify: !!python/object/apply:pymdownx.slugs.slugify kwds: case: lower - pymdownx.tasklist: custom_checkbox: true - toc: permalink: "¤" plugins: - search - autorefs - markdown-exec - section-index # - coverage - mkdocstrings: handlers: python: paths: [src, docs/snippets] inventories: - https://docs.python.org/3/objects.inv - https://mkdocstrings.github.io/objects.inv - https://mkdocstrings.github.io/autorefs/objects.inv - https://mkdocstrings.github.io/griffe/objects.inv - https://python-markdown.github.io/objects.inv options: backlinks: tree docstring_options: ignore_init_summary: true docstring_section_style: list extensions: [scripts/griffe_extensions.py] filters: public heading_level: 1 inherited_members: true line_length: 88 merge_init_into_class: true parameter_headings: true type_parameter_headings: true preload_modules: [mkdocstrings] relative_crossrefs: true scoped_crossrefs: true separate_signature: true show_bases: false show_inheritance_diagram: true show_root_heading: true show_root_full_path: false show_signature_annotations: true show_signature_type_parameters: true show_source: false show_symbol_type_heading: true show_symbol_type_toc: true signature_crossrefs: true summary: true unwrap_annotated: true - llmstxt: full_output: llms-full.txt sections: Usage: - index.md API: - reference/api.md - git-revision-date-localized: enabled: !ENV [DEPLOY, false] enable_creation_date: true type: timeago - minify: minify_html: !ENV [DEPLOY, false] - redirects: redirect_maps: reference/mkdocstrings_handlers/python/index.md: reference/api.md reference/mkdocstrings_handlers/python/config.md: reference/api.md#mkdocstrings_handlers.python.config reference/mkdocstrings_handlers/python/debug.md: reference/api.md#mkdocstrings_handlers.python.debug reference/mkdocstrings_handlers/python/handler.md: reference/api.md#mkdocstrings_handlers.python.handler reference/mkdocstrings_handlers/python/rendering.md: reference/api.md#mkdocstrings_handlers.python.rendering - 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/ analytics: feedback: title: Was this page helpful? ratings: - icon: material/emoticon-happy-outline name: This page was helpful data: 1 note: Thanks for your feedback! - icon: material/emoticon-sad-outline name: This page could be improved data: 0 note: Let us know how we can improve this page. ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1756397474.1152039 mkdocstrings_python-1.18.2/pyproject.toml0000644000000000000000000000617315054077642015576 0ustar00[build-system] requires = [ "pdm-backend", ] build-backend = "pdm.backend" [project] name = "mkdocstrings-python" description = "A Python handler for mkdocstrings." authors = [ { name = "Timothée Mazzucotelli", email = "dev@pawamoy.fr" }, ] license = "ISC" license-files = [ "LICENSE", ] readme = "README.md" requires-python = ">=3.9" keywords = [] dynamic = [] classifiers = [ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "Programming Language :: Python", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Programming Language :: Python :: 3.14", "Topic :: Documentation", "Topic :: Software Development", "Topic :: Software Development :: Documentation", "Topic :: Utilities", "Typing :: Typed", ] dependencies = [ "mkdocstrings>=0.30", "mkdocs-autorefs>=1.4", "griffe>=1.13", "typing-extensions>=4.0; python_version < '3.11'", ] version = "1.18.2" [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 = "call" getter = "scripts.get_version:get_version" [tool.pdm.build] package-dir = "src" includes = [ "src/mkdocstrings_handlers", ] editable-backend = "editables" excludes = [ "**/.pytest_cache", "**/.mypy_cache", ] source-includes = [ "config", "docs", "scripts", "share", "tests", "duties.py", "mkdocs.yml", "*.md", "LICENSE", ] [tool.pdm.build.wheel-data] data = [ { path = "share/**/*", relative-to = "." }, ] [tool.inline-snapshot] storage-dir = "tests/snapshots" format-command = "ruff format --config config/ruff.toml --stdin-filename {filename}" [tool.uv] default-groups = [ "maintain", "ci", "docs", ] [dependency-groups] maintain = [ "build>=1.2", "git-changelog>=2.5", "twine>=5.1", "yore>=0.3.3", ] ci = [ "black>=25.1", "duty>=1.6", "ruff>=0.4", "pytest>=8.2", "pytest-cov>=5.0", "pytest-randomly>=3.15", "pytest-xdist>=3.6", "beautifulsoup4>=4.12.3", "inline-snapshot>=0.25", "mypy>=1.10", "types-markdown>=3.6", "types-pyyaml>=6.0", ] docs = [ "markdown-callouts>=0.4", "markdown-exec>=1.8", "mkdocs>=1.6", "mkdocs-coverage>=1.0", "mkdocs-git-revision-date-localized-plugin>=1.2", "mkdocs-llmstxt>=0.2", "mkdocs-material>=9.5", "mkdocs-minify-plugin>=0.8", "mkdocs-redirects>=1.2", "mkdocs-section-index>=0.3", "mkdocstrings>=0.29", "pydantic>=2.10", "tomli>=2.0; python_version < '3.11'", ] ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.4328852 mkdocstrings_python-1.18.2/scripts/gen_credits.py0000644000000000000000000001500015051047736017174 0ustar00# Script to generate the project's credits. from __future__ import annotations import os import sys from collections import defaultdict from collections.abc import Iterable from importlib.metadata import distributions from itertools import chain from pathlib import Path from textwrap import dedent from typing import Union from jinja2 import StrictUndefined from jinja2.sandbox import SandboxedEnvironment from packaging.requirements import Requirement # YORE: EOL 3.10: Replace block with line 2. if sys.version_info >= (3, 11): import tomllib else: import tomli as tomllib project_dir = Path(os.getenv("MKDOCS_CONFIG_DIR", ".")) with project_dir.joinpath("pyproject.toml").open("rb") as pyproject_file: pyproject = tomllib.load(pyproject_file) project = pyproject["project"] project_name = project["name"] devdeps = [dep for group in pyproject["dependency-groups"].values() for dep in group if not dep.startswith("-e")] PackageMetadata = dict[str, Union[str, Iterable[str]]] Metadata = dict[str, PackageMetadata] def _merge_fields(metadata: dict) -> PackageMetadata: fields = defaultdict(list) for header, value in metadata.items(): fields[header.lower()].append(value.strip()) return { field: value if len(value) > 1 or field in ("classifier", "requires-dist") else value[0] for field, value in fields.items() } def _norm_name(name: str) -> str: return name.replace("_", "-").replace(".", "-").lower() def _requirements(deps: list[str]) -> dict[str, Requirement]: return {_norm_name((req := Requirement(dep)).name): req for dep in deps} def _extra_marker(req: Requirement) -> str | None: if not req.marker: return None try: return next(marker[2].value for marker in req.marker._markers if getattr(marker[0], "value", None) == "extra") except StopIteration: return None def _get_metadata() -> Metadata: metadata = {} for pkg in distributions(): name = _norm_name(pkg.name) # type: ignore[attr-defined,unused-ignore] metadata[name] = _merge_fields(pkg.metadata) # type: ignore[arg-type] metadata[name]["spec"] = set() metadata[name]["extras"] = set() metadata[name].setdefault("summary", "") _set_license(metadata[name]) return metadata def _set_license(metadata: PackageMetadata) -> None: license_field = metadata.get("license-expression", metadata.get("license", "")) license_name = license_field if isinstance(license_field, str) else " + ".join(license_field) check_classifiers = license_name in ("UNKNOWN", "Dual License", "") or license_name.count("\n") if check_classifiers: license_names = [] for classifier in metadata["classifier"]: if classifier.startswith("License ::"): license_names.append(classifier.rsplit("::", 1)[1].strip()) license_name = " + ".join(license_names) metadata["license"] = license_name or "?" def _get_deps(base_deps: dict[str, Requirement], metadata: Metadata) -> Metadata: deps = {} for dep_name, dep_req in base_deps.items(): if dep_name not in metadata or dep_name == "mkdocstrings-python": continue metadata[dep_name]["spec"] |= {str(spec) for spec in dep_req.specifier} # type: ignore[operator] metadata[dep_name]["extras"] |= dep_req.extras # type: ignore[operator] deps[dep_name] = metadata[dep_name] again = True while again: again = False for pkg_name in metadata: if pkg_name in deps: for pkg_dependency in metadata[pkg_name].get("requires-dist", []): requirement = Requirement(pkg_dependency) dep_name = _norm_name(requirement.name) extra_marker = _extra_marker(requirement) if ( dep_name in metadata and dep_name not in deps and dep_name != project["name"] and (not extra_marker or extra_marker in deps[pkg_name]["extras"]) ): metadata[dep_name]["spec"] |= {str(spec) for spec in requirement.specifier} # type: ignore[operator] deps[dep_name] = metadata[dep_name] again = True return deps def _render_credits() -> str: metadata = _get_metadata() dev_dependencies = _get_deps(_requirements(devdeps), metadata) prod_dependencies = _get_deps( _requirements( chain( # type: ignore[arg-type] project.get("dependencies", []), chain(*project.get("optional-dependencies", {}).values()), ), ), metadata, ) template_data = { "project_name": project_name, "prod_dependencies": sorted(prod_dependencies.values(), key=lambda dep: str(dep["name"]).lower()), "dev_dependencies": sorted(dev_dependencies.values(), key=lambda dep: str(dep["name"]).lower()), "more_credits": "http://pawamoy.github.io/credits/", } template_text = dedent( """ # Credits These projects were used to build *{{ project_name }}*. **Thank you!** [Python](https://www.python.org/) | [uv](https://github.com/astral-sh/uv) | [copier-uv](https://github.com/pawamoy/copier-uv) {% macro dep_line(dep) -%} [{{ dep.name }}](https://pypi.org/project/{{ dep.name }}/) | {{ dep.summary }} | {{ ("`" ~ dep.spec|sort(reverse=True)|join(", ") ~ "`") if dep.spec else "" }} | `{{ dep.version }}` | {{ dep.license }} {%- endmacro %} {% if prod_dependencies -%} ### Runtime dependencies Project | Summary | Version (accepted) | Version (last resolved) | License ------- | ------- | ------------------ | ----------------------- | ------- {% for dep in prod_dependencies -%} {{ dep_line(dep) }} {% endfor %} {% endif -%} {% if dev_dependencies -%} ### Development dependencies Project | Summary | Version (accepted) | Version (last resolved) | License ------- | ------- | ------------------ | ----------------------- | ------- {% for dep in dev_dependencies -%} {{ dep_line(dep) }} {% endfor %} {% endif -%} {% if more_credits %}**[More credits from the author]({{ more_credits }})**{% endif %} """, ) jinja_env = SandboxedEnvironment(undefined=StrictUndefined) return jinja_env.from_string(template_text).render(**template_data) print(_render_credits()) ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.4332573 mkdocstrings_python-1.18.2/scripts/get_version.py0000644000000000000000000000200615051047736017234 0ustar00# Get current project version from Git tags or changelog. import re from contextlib import suppress from pathlib import Path from pdm.backend.hooks.version import SCMVersion, Version, default_version_formatter, get_version_from_scm _root = Path(__file__).parent.parent _changelog = _root / "CHANGELOG.md" _changelog_version_re = re.compile(r"^## \[(\d+\.\d+\.\d+)\].*$") _default_scm_version = SCMVersion(Version("0.0.0"), None, False, None, None) # noqa: FBT003 def get_version() -> str: scm_version = get_version_from_scm(_root) or _default_scm_version if scm_version.version <= Version("0.1"): # Missing Git tags? with suppress(OSError, StopIteration): # noqa: SIM117 with _changelog.open("r", encoding="utf8") as file: match = next(filter(None, map(_changelog_version_re.match, file))) scm_version = scm_version._replace(version=Version(match.group(1))) return default_version_formatter(scm_version) if __name__ == "__main__": print(get_version()) ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.4332573 mkdocstrings_python-1.18.2/scripts/griffe_extensions.py0000644000000000000000000000264015051047736020435 0ustar00# Custom extensions for Griffe. from __future__ import annotations import ast from typing import Any import griffe _logger = griffe.get_logger("griffe_extensions") class CustomFields(griffe.Extension): """Support our custom dataclass fields.""" def on_attribute_instance( self, *, attr: griffe.Attribute, agent: griffe.Visitor | griffe.Inspector, **kwargs: Any, # noqa: ARG002 ) -> None: """Fetch descriptions from `Field` annotations.""" if attr.docstring: return try: field: griffe.ExprCall = attr.annotation.slice.elements[1] # type: ignore[union-attr] except AttributeError: return if field.canonical_path == "mkdocstrings_handlers.python._internal.config._Field": description = next( attr.value for attr in field.arguments if isinstance(attr, griffe.ExprKeyword) and attr.name == "description" ) if not isinstance(description, str): _logger.warning(f"Field description of {attr.path} is not a static string") description = str(description) attr.docstring = griffe.Docstring( ast.literal_eval(description), parent=attr, parser=agent.docstring_parser, parser_options=agent.docstring_options, ) ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.4681208 mkdocstrings_python-1.18.2/scripts/insiders.py0000644000000000000000000001363415051047736016541 0ustar00# 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 TYPE_CHECKING, cast from urllib.error import HTTPError from urllib.parse import urljoin from urllib.request import urlopen import yaml if TYPE_CHECKING: from collections.abc import Iterable logger = logging.getLogger(f"mkdocs.logs.{__name__}") def human_readable_amount(amount: int) -> str: 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: name: str url: str @dataclass class 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: name: str amount: int features: list[Feature] complete: bool = False @property def human_readable_amount(self) -> str: # noqa: D102 return human_readable_amount(self.amount) def render(self, rel_base: str = "..") -> None: # noqa: D102 print(f"#### $ {self.human_readable_amount} — {self.name}\n") if self.features: for feature in self.features: feature.render(rel_base) print("") else: print("There are no features in this goal for this project. ") print( "[See the features in this goal **for all Insiders projects.**]" f"(https://pawamoy.github.io/insiders/#{self.amount}-{self.name.lower().replace(' ', '-')})", ) def load_goals(data: str, funding: int = 0, project: Project | None = None) -> dict[int, Goal]: 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]: if isinstance(source, str): return _load_goals_from_disk(source, funding) goals = {} for src in source: source_goals = _load_goals(src, funding) for amount, goal in source_goals.items(): if amount not in goals: goals[amount] = goal else: goals[amount].features.extend(goal.features) return {amount: goals[amount] for amount in sorted(goals)} def feature_list(goals: Iterable[Goal]) -> list[Feature]: return list(chain.from_iterable(goal.features for goal in goals)) def load_json(url: str) -> str | list | dict: 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, ) ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1748006213.7502813 mkdocstrings_python-1.18.2/scripts/make0000755000000000000000000000000015014072506016450 2make.pyustar00././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.4691925 mkdocstrings_python-1.18.2/scripts/make.py0000755000000000000000000001416515051047736015641 0ustar00#!/usr/bin/env python3 from __future__ import annotations import os import shutil import subprocess import sys from contextlib import contextmanager from pathlib import Path from textwrap import dedent from typing import TYPE_CHECKING, Any if TYPE_CHECKING: from collections.abc import Iterator PYTHON_VERSIONS = os.getenv("PYTHON_VERSIONS", "3.9 3.10 3.11 3.12 3.13").split() def shell(cmd: str, *, capture_output: bool = False, **kwargs: Any) -> str | None: """Run a shell command.""" if capture_output: return subprocess.check_output(cmd, shell=True, text=True, **kwargs) # noqa: S602 subprocess.run(cmd, shell=True, check=True, stderr=subprocess.STDOUT, **kwargs) # noqa: S602 return None @contextmanager def environ(**kwargs: str) -> Iterator[None]: """Temporarily set environment variables.""" original = dict(os.environ) os.environ.update(kwargs) try: yield finally: os.environ.clear() os.environ.update(original) def uv_install(venv: Path) -> None: """Install dependencies using uv.""" with environ(UV_PROJECT_ENVIRONMENT=str(venv), PYO3_USE_ABI3_FORWARD_COMPATIBILITY="1"): if "CI" in os.environ: shell("uv sync --no-editable") else: shell("uv sync") def setup() -> None: """Setup the project.""" if not shutil.which("uv"): raise ValueError("make: setup: uv must be installed, see https://github.com/astral-sh/uv") print("Installing dependencies (default environment)") default_venv = Path(".venv") if not default_venv.exists(): shell("uv venv") uv_install(default_venv) if PYTHON_VERSIONS: for version in PYTHON_VERSIONS: print(f"\nInstalling dependencies (python{version})") venv_path = Path(f".venvs/{version}") if not venv_path.exists(): shell(f"uv venv --python {version} {venv_path}") with environ(UV_PROJECT_ENVIRONMENT=str(venv_path.resolve())): uv_install(venv_path) def run(version: str, cmd: str, *args: str, **kwargs: Any) -> None: """Run a command in a virtual environment.""" kwargs = {"check": True, **kwargs} uv_run = ["uv", "run", "--no-sync"] if version == "default": with environ(UV_PROJECT_ENVIRONMENT=".venv"): subprocess.run([*uv_run, cmd, *args], **kwargs) # noqa: S603, PLW1510 else: with environ(UV_PROJECT_ENVIRONMENT=f".venvs/{version}", MULTIRUN="1"): subprocess.run([*uv_run, cmd, *args], **kwargs) # noqa: S603, PLW1510 def multirun(cmd: str, *args: str, **kwargs: Any) -> None: """Run a command for all configured Python versions.""" if PYTHON_VERSIONS: for version in PYTHON_VERSIONS: run(version, cmd, *args, **kwargs) else: run("default", cmd, *args, **kwargs) def allrun(cmd: str, *args: str, **kwargs: Any) -> None: """Run a command in all virtual environments.""" run("default", cmd, *args, **kwargs) if PYTHON_VERSIONS: multirun(cmd, *args, **kwargs) def clean() -> None: """Delete build artifacts and cache files.""" paths_to_clean = ["build", "dist", "htmlcov", "site", ".coverage*", ".pdm-build"] for path in paths_to_clean: shutil.rmtree(path, ignore_errors=True) cache_dirs = {".cache", ".pytest_cache", ".mypy_cache", ".ruff_cache", "__pycache__"} for dirpath in Path(".").rglob("*/"): if dirpath.parts[0] not in (".venv", ".venvs") and dirpath.name in cache_dirs: shutil.rmtree(dirpath, ignore_errors=True) def vscode() -> None: """Configure VSCode to work on this project.""" shutil.copytree("config/vscode", ".vscode", dirs_exist_ok=True) def main() -> int: """Main entry point.""" args = list(sys.argv[1:]) if not args or args[0] == "help": if len(args) > 1: run("default", "duty", "--help", args[1]) else: print( dedent( """ Available commands help Print this help. Add task name to print help. setup Setup all virtual environments (install dependencies). run Run a command in the default virtual environment. multirun Run a command for all configured Python versions. allrun Run a command in all virtual environments. 3.x Run a command in the virtual environment for Python 3.x. clean Delete build artifacts and cache files. vscode Configure VSCode to work on this project. """, ), flush=True, ) if os.path.exists(".venv"): print("\nAvailable tasks", flush=True) run("default", "duty", "--list") return 0 while args: cmd = args.pop(0) if cmd == "run": run("default", *args) return 0 if cmd == "multirun": multirun(*args) return 0 if cmd == "allrun": allrun(*args) return 0 if cmd.startswith("3."): run(cmd, *args) return 0 opts = [] while args and (args[0].startswith("-") or "=" in args[0]): opts.append(args.pop(0)) if cmd == "clean": clean() elif cmd == "setup": setup() elif cmd == "vscode": vscode() elif cmd == "check": multirun("duty", "check-quality", "check-types", "check-docs") run("default", "duty", "check-api") elif cmd in {"check-quality", "check-docs", "check-types", "test"}: multirun("duty", cmd, *opts) else: run("default", "duty", cmd, *opts) return 0 if __name__ == "__main__": try: sys.exit(main()) except subprocess.CalledProcessError as process: if process.output: print(process.output, file=sys.stderr) sys.exit(process.returncode) ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.4691925 mkdocstrings_python-1.18.2/scripts/mkdocs_hooks.py0000644000000000000000000000317715051047736017405 0ustar00# Generate a JSON schema of the Python handler configuration. import json from dataclasses import dataclass, fields from os.path import join from typing import Any from mkdocs.config.defaults import MkDocsConfig from mkdocs.plugins import get_plugin_logger from mkdocstrings_handlers.python import PythonInputConfig, PythonInputOptions # TODO: Update when Pydantic supports Python 3.14 (sources and duties as well). try: from pydantic import TypeAdapter except ImportError: TypeAdapter = None # type: ignore[assignment,misc] _logger = get_plugin_logger(__name__) def on_post_build(config: MkDocsConfig, **kwargs: Any) -> None: # noqa: ARG001 """Write `schema.json` to the site directory.""" if TypeAdapter is None: _logger.info("Pydantic is not installed, skipping JSON schema generation") return @dataclass class PythonHandlerSchema: python: PythonInputConfig adapter = TypeAdapter(PythonHandlerSchema) schema = adapter.json_schema() schema["$schema"] = "https://json-schema.org/draft-07/schema" with open(join(config.site_dir, "schema.json"), "w") as file: json.dump(schema, file, indent=2) _logger.debug("Generated JSON schema") autorefs = config["plugins"]["autorefs"] for field in fields(PythonInputConfig): if f"setting-{field.name}" not in autorefs._primary_url_map: _logger.warning(f"Handler setting `{field.name}` is not documented") for field in fields(PythonInputOptions): if f"option-{field.name}" not in autorefs._primary_url_map: _logger.warning(f"Configuration option `{field.name}` is not documented") ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1756396403.6410487 mkdocstrings_python-1.18.2/src/mkdocstrings_handlers/python/__init__.py0000644000000000000000000000330615054075564023466 0ustar00"""Python handler for mkdocstrings.""" from mkdocstrings_handlers.python._internal.config import ( AutoStyleOptions, GoogleStyleOptions, Inventory, NumpyStyleOptions, PerStyleOptions, PythonConfig, PythonInputConfig, PythonInputOptions, PythonOptions, SphinxStyleOptions, SummaryOption, ) from mkdocstrings_handlers.python._internal.handler import PythonHandler, get_handler from mkdocstrings_handlers.python._internal.rendering import ( AutorefsHook, Order, Tree, do_as_attributes_section, do_as_classes_section, do_as_functions_section, do_as_modules_section, do_as_type_aliases_section, do_backlink_tree, do_crossref, do_filter_objects, do_format_attribute, do_format_code, do_format_signature, do_format_type_alias, do_get_template, do_multi_crossref, do_order_members, do_split_path, do_stash_crossref, ) __all__ = [ "AutoStyleOptions", "AutorefsHook", "GoogleStyleOptions", "Inventory", "NumpyStyleOptions", "Order", "PerStyleOptions", "PythonConfig", "PythonHandler", "PythonInputConfig", "PythonInputOptions", "PythonOptions", "SphinxStyleOptions", "SummaryOption", "Tree", "do_as_attributes_section", "do_as_classes_section", "do_as_functions_section", "do_as_modules_section", "do_as_type_aliases_section", "do_backlink_tree", "do_crossref", "do_filter_objects", "do_format_attribute", "do_format_code", "do_format_signature", "do_format_type_alias", "do_get_template", "do_multi_crossref", "do_order_members", "do_split_path", "do_stash_crossref", "get_handler", ] ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.4811206 mkdocstrings_python-1.18.2/src/mkdocstrings_handlers/python/_internal/__init__.py0000644000000000000000000000000015051047736025422 0ustar00././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1756216889.074097 mkdocstrings_python-1.18.2/src/mkdocstrings_handlers/python/_internal/config.py0000644000000000000000000011066615053337071025150 0ustar00# Configuration and options dataclasses. from __future__ import annotations import re import sys from dataclasses import field, fields from typing import TYPE_CHECKING, Annotated, Any, Literal from mkdocstrings import get_logger from mkdocstrings_handlers.python._internal.rendering import Order # noqa: TC001 # YORE: EOL 3.10: Replace block with line 2. if sys.version_info >= (3, 11): from typing import Self else: from typing_extensions import Self _logger = get_logger(__name__) _DEFAULT_FILTERS = ["!^_[^_]"] try: # When Pydantic is available, use it to validate options (done automatically). # Users can therefore opt into validation by installing Pydantic in development/CI. # When building the docs to deploy them, Pydantic is not required anymore. # When building our own docs, Pydantic is always installed (see `docs` group in `pyproject.toml`) # to allow automatic generation of a JSON Schema. The JSON Schema is then referenced by mkdocstrings, # which is itself referenced by mkdocs-material's schema system. For example in VSCode: # # "yaml.schemas": { # "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml" # } import pydantic if getattr(pydantic, "__version__", "1.").startswith("1."): raise ImportError # noqa: TRY301 # YORE: EOL 3.9: Remove block. if sys.version_info < (3, 10): try: import eval_type_backport # noqa: F401 except ImportError: _logger.debug( "Pydantic needs the `eval-type-backport` package to be installed " "for modern type syntax to work on Python 3.9. " "Deactivating Pydantic validation for Python handler options.", ) raise from inspect import cleandoc from pydantic import Field as BaseField from pydantic.dataclasses import dataclass _base_url = "https://mkdocstrings.github.io/python/usage" def _Field( # noqa: N802 *args: Any, description: str, group: Literal["general", "headings", "members", "docstrings", "signatures"] | None = None, parent: str | None = None, **kwargs: Any, ) -> None: def _add_markdown_description(schema: dict[str, Any]) -> None: url = f"{_base_url}/{f'configuration/{group}/' if group else ''}#{parent or schema['title']}" schema["markdownDescription"] = f"[DOCUMENTATION]({url})\n\n{schema['description']}" return BaseField( *args, description=cleandoc(description), field_title_generator=lambda name, _: name, json_schema_extra=_add_markdown_description, **kwargs, ) except ImportError: from dataclasses import dataclass # type: ignore[no-redef] def _Field(*args: Any, **kwargs: Any) -> None: # type: ignore[misc] # noqa: N802 pass if TYPE_CHECKING: from collections.abc import MutableMapping # YORE: EOL 3.9: Remove block. _dataclass_options = {"frozen": True} if sys.version_info >= (3, 10): _dataclass_options["kw_only"] = True # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. @dataclass(**_dataclass_options) # type: ignore[call-overload] class GoogleStyleOptions: """Google style docstring options.""" ignore_init_summary: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="Whether to ignore the summary in `__init__` methods' docstrings.", ), ] = False returns_multiple_items: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="""Whether to parse multiple items in `Yields` and `Returns` sections. When true, each item's continuation lines must be indented. When false (single item), no further indentation is required. """, ), ] = True returns_named_value: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="""Whether to parse `Yields` and `Returns` section items as name and description, rather than type and description. When true, type must be wrapped in parentheses: `(int): Description.`. Names are optional: `name (int): Description.`. When false, parentheses are optional but the items cannot be named: `int: Description`. """, ), ] = True returns_type_in_property_summary: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="Whether to parse the return type of properties at the beginning of their summary: `str: Summary of the property`.", ), ] = False receives_multiple_items: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="""Whether to parse multiple items in `Receives` sections. When true, each item's continuation lines must be indented. When false (single item), no further indentation is required. """, ), ] = True receives_named_value: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="""Whether to parse `Receives` section items as name and description, rather than type and description. When true, type must be wrapped in parentheses: `(int): Description.`. Names are optional: `name (int): Description.`. When false, parentheses are optional but the items cannot be named: `int: Description`. """, ), ] = True trim_doctest_flags: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="Whether to remove doctest flags from Python example blocks.", ), ] = True warn_unknown_params: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="Warn about documented parameters not appearing in the signature.", ), ] = True warn_missing_types: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="Warn about missing type/annotation for parameters, return values, etc.", ), ] = True warnings: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="Generally enable/disable warnings when parsing docstrings.", ), ] = True # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. @dataclass(**_dataclass_options) # type: ignore[call-overload] class NumpyStyleOptions: """Numpy style docstring options.""" ignore_init_summary: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="Whether to ignore the summary in `__init__` methods' docstrings.", ), ] = False trim_doctest_flags: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="Whether to remove doctest flags from Python example blocks.", ), ] = True warn_unknown_params: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="Warn about documented parameters not appearing in the signature.", ), ] = True warn_missing_types: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="Warn about missing type/annotation for parameters, return values, etc.", ), ] = True warnings: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="Generally enable/disable warnings when parsing docstrings.", ), ] = True # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. @dataclass(**_dataclass_options) # type: ignore[call-overload] class SphinxStyleOptions: """Sphinx style docstring options.""" warn_unknown_params: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="Warn about documented parameters not appearing in the signature.", ), ] = True warn_missing_types: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="Warn about missing type/annotation for return values.", ), ] = True warnings: Annotated[ bool, _Field( group="docstrings", parent="docstring_options", description="Generally enable/disable warnings when parsing docstrings.", ), ] = True # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. @dataclass(**_dataclass_options) # type: ignore[call-overload] class PerStyleOptions: """Per style options.""" google: Annotated[ GoogleStyleOptions, _Field( group="docstrings", parent="docstring_options", description="Google-style options.", ), ] = field(default_factory=GoogleStyleOptions) numpy: Annotated[ NumpyStyleOptions, _Field( group="docstrings", parent="docstring_options", description="Numpydoc-style options.", ), ] = field(default_factory=NumpyStyleOptions) sphinx: Annotated[ SphinxStyleOptions, _Field( group="docstrings", parent="docstring_options", description="Sphinx-style options.", ), ] = field(default_factory=SphinxStyleOptions) @classmethod def from_data(cls, **data: Any) -> Self: """Create an instance from a dictionary.""" if "google" in data: data["google"] = GoogleStyleOptions(**data["google"]) if "numpy" in data: data["numpy"] = NumpyStyleOptions(**data["numpy"]) if "sphinx" in data: data["sphinx"] = SphinxStyleOptions(**data["sphinx"]) return cls(**data) # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. @dataclass(**_dataclass_options) # type: ignore[call-overload] class AutoStyleOptions: """Auto style docstring options.""" method: Annotated[ Literal["heuristics", "max_sections"], _Field( group="docstrings", parent="docstring_options", description="The method to use to determine the docstring style.", ), ] = "heuristics" style_order: Annotated[ list[str], _Field( group="docstrings", parent="docstring_options", description="The order of the docstring styles to try.", ), ] = field(default_factory=lambda: ["sphinx", "google", "numpy"]) default: Annotated[ str | None, _Field( group="docstrings", parent="docstring_options", description="The default docstring style to use if no other style is detected.", ), ] = None per_style_options: Annotated[ PerStyleOptions, _Field( group="docstrings", parent="docstring_options", description="Per-style options.", ), ] = field(default_factory=PerStyleOptions) @classmethod def from_data(cls, **data: Any) -> Self: """Create an instance from a dictionary.""" if "per_style_options" in data: data["per_style_options"] = PerStyleOptions.from_data(**data["per_style_options"]) return cls(**data) # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. @dataclass(**_dataclass_options) # type: ignore[call-overload] class SummaryOption: """Summary option.""" attributes: Annotated[ bool, _Field( group="members", parent="summary", description="Whether to render summaries of attributes.", ), ] = False functions: Annotated[ bool, _Field( group="members", parent="summary", description="Whether to render summaries of functions (methods).", ), ] = False classes: Annotated[ bool, _Field( group="members", parent="summary", description="Whether to render summaries of classes.", ), ] = False modules: Annotated[ bool, _Field( group="members", parent="summary", description="Whether to render summaries of modules.", ), ] = False type_aliases: Annotated[ bool, _Field( group="members", parent="summary", description="Whether to render summaries of type aliases.", ), ] = False # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. @dataclass(**_dataclass_options) # type: ignore[call-overload] class PythonInputOptions: """Accepted input options.""" allow_inspection: Annotated[ bool, _Field( group="general", description="Whether to allow inspecting modules when visiting them is not possible.", ), ] = True force_inspection: Annotated[ bool, _Field( group="general", description="Whether to force using dynamic analysis when loading data.", ), ] = False annotations_path: Annotated[ Literal["brief", "source", "full"], _Field( group="signatures", description="The verbosity for annotations path: `brief` (recommended), `source` (as written in the source), or `full`.", ), ] = "brief" backlinks: Annotated[ Literal["flat", "tree", False], _Field( group="general", description="Whether to render backlinks, and how.", ), ] = False docstring_options: Annotated[ GoogleStyleOptions | NumpyStyleOptions | SphinxStyleOptions | AutoStyleOptions | None, _Field( group="docstrings", description="""The options for the docstring parser. See [docstring parsers](https://mkdocstrings.github.io/griffe/reference/docstrings/) and their options in Griffe docs. """, ), ] = None docstring_section_style: Annotated[ Literal["table", "list", "spacy"], _Field( group="docstrings", description="The style used to render docstring sections.", ), ] = "table" docstring_style: Annotated[ Literal["auto", "google", "numpy", "sphinx"] | None, _Field( group="docstrings", description="The docstring style to use: `auto`, `google`, `numpy`, `sphinx`, or `None`.", ), ] = "google" extensions: Annotated[ list[str | dict[str, Any]], _Field( group="general", description="A list of Griffe extensions to load.", ), ] = field(default_factory=list) filters: Annotated[ list[str] | Literal["public"], _Field( group="members", description="""A list of filters, or `"public"`. **List of filters** 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). **Filtering methods** [:octicons-heart-fill-24:{ .pulse } Sponsors only](../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.11.0](../insiders/changelog.md#1.11.0) The `public` method will include only public objects: those added to `__all__` or not starting with an underscore (except for special methods/attributes). """, ), ] = field(default_factory=lambda: _DEFAULT_FILTERS.copy()) find_stubs_package: Annotated[ bool, _Field( group="general", description="Whether to load stubs package (package-stubs) when extracting docstrings.", ), ] = False group_by_category: Annotated[ bool, _Field( group="members", description="Group the object's children by categories: attributes, classes, functions, and modules.", ), ] = True heading: Annotated[ str, _Field( group="headings", description="A custom string to override the autogenerated heading of the root object.", ), ] = "" heading_level: Annotated[ int, _Field( group="headings", description="The initial heading level to use.", ), ] = 2 inherited_members: Annotated[ bool | list[str], _Field( group="members", description="""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. """, ), ] = False line_length: Annotated[ int, _Field( group="signatures", description="Maximum line length when formatting code/signatures.", ), ] = 60 members: Annotated[ list[str] | bool | None, _Field( group="members", description="""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. """, ), ] = None members_order: Annotated[ Order | list[Order], _Field( group="members", description="""The members ordering to use. - `__all__`: order members according to `__all__` module attributes, if declared; - `alphabetical`: order members alphabetically; - `source`: order members as they appear in the source file. Since `__all__` is a module-only attribute, it can't be used to sort class members, therefore the `members_order` option accepts a list of ordering methods, indicating ordering preferences. """, ), ] = "alphabetical" merge_init_into_class: Annotated[ bool, _Field( group="docstrings", description="Whether to merge the `__init__` method into the class' signature and docstring.", ), ] = False modernize_annotations: Annotated[ bool, _Field( group="signatures", description="Whether to modernize annotations, for example `Optional[str]` into `str | None`.", ), ] = False overloads_only: Annotated[ bool, _Field( group="signatures", description="Whether to hide the implementation signature if the overloads are shown.", ), ] = False parameter_headings: Annotated[ bool, _Field( group="headings", description="Whether to render headings for parameters (therefore showing parameters in the ToC).", ), ] = False preload_modules: Annotated[ list[str], _Field( group="general", description="""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. """, ), ] = field(default_factory=list) relative_crossrefs: Annotated[ bool, _Field( group="docstrings", description="Whether to enable the relative crossref syntax.", ), ] = False scoped_crossrefs: Annotated[ bool, _Field( group="docstrings", description="Whether to enable the scoped crossref ability.", ), ] = False show_overloads: Annotated[ bool, _Field( group="signatures", description="Show the overloads of a function or method.", ), ] = True separate_signature: Annotated[ bool, _Field( group="signatures", description="""Whether to put the whole signature in a code block below the heading. If Black or Ruff are installed, the signature is also formatted using them. """, ), ] = False show_attribute_values: Annotated[ bool, _Field( group="signatures", description="Show initial values of attributes in classes.", ), ] = True show_bases: Annotated[ bool, _Field( group="general", description="Show the base classes of a class.", ), ] = True show_category_heading: Annotated[ bool, _Field( group="headings", description="When grouped by categories, show a heading for each category.", ), ] = False show_docstring_attributes: Annotated[ bool, _Field( group="docstrings", description="Whether to display the 'Attributes' section in the object's docstring.", ), ] = True show_docstring_classes: Annotated[ bool, _Field( group="docstrings", description="Whether to display the 'Classes' section in the object's docstring.", ), ] = True show_docstring_description: Annotated[ bool, _Field( group="docstrings", description="Whether to display the textual block (including admonitions) in the object's docstring.", ), ] = True show_docstring_examples: Annotated[ bool, _Field( group="docstrings", description="Whether to display the 'Examples' section in the object's docstring.", ), ] = True show_docstring_functions: Annotated[ bool, _Field( group="docstrings", description="Whether to display the 'Functions' or 'Methods' sections in the object's docstring.", ), ] = True show_docstring_modules: Annotated[ bool, _Field( group="docstrings", description="Whether to display the 'Modules' section in the object's docstring.", ), ] = True show_docstring_other_parameters: Annotated[ bool, _Field( group="docstrings", description="Whether to display the 'Other Parameters' section in the object's docstring.", ), ] = True show_docstring_parameters: Annotated[ bool, _Field( group="docstrings", description="Whether to display the 'Parameters' section in the object's docstring.", ), ] = True show_docstring_raises: Annotated[ bool, _Field( group="docstrings", description="Whether to display the 'Raises' section in the object's docstring.", ), ] = True show_docstring_receives: Annotated[ bool, _Field( group="docstrings", description="Whether to display the 'Receives' section in the object's docstring.", ), ] = True show_docstring_returns: Annotated[ bool, _Field( group="docstrings", description="Whether to display the 'Returns' section in the object's docstring.", ), ] = True show_docstring_type_aliases: Annotated[ bool, _Field( group="docstrings", description="Whether to display the 'Type Aliases' section in the object's docstring.", ), ] = True show_docstring_type_parameters: Annotated[ bool, _Field( group="docstrings", description="Whether to display the 'Type Parameters' section in the object's docstring.", ), ] = True show_docstring_warns: Annotated[ bool, _Field( group="docstrings", description="Whether to display the 'Warns' section in the object's docstring.", ), ] = True show_docstring_yields: Annotated[ bool, _Field( group="docstrings", description="Whether to display the 'Yields' section in the object's docstring.", ), ] = True show_if_no_docstring: Annotated[ bool, _Field( group="docstrings", description="Show the object heading even if it has no docstring or children with docstrings.", ), ] = False show_inheritance_diagram: Annotated[ bool, _Field( group="docstrings", description="Show the inheritance diagram of a class using Mermaid.", ), ] = False show_labels: Annotated[ bool, _Field( group="docstrings", description="Whether to show labels of the members.", ), ] = True show_object_full_path: Annotated[ bool, _Field( group="docstrings", description="Show the full Python path of every object.", ), ] = False show_root_full_path: Annotated[ bool, _Field( group="docstrings", description="Show the full Python path for the root object heading.", ), ] = True show_root_heading: Annotated[ bool, _Field( group="headings", description="""Show the heading of the object at the root of the documentation tree. The root object is the object referenced by the identifier after `:::`. """, ), ] = False show_root_members_full_path: Annotated[ bool, _Field( group="headings", description="Show the full Python path of the root members.", ), ] = False show_root_toc_entry: Annotated[ bool, _Field( group="headings", description="If the root heading is not shown, at least add a ToC entry for it.", ), ] = True show_signature_annotations: Annotated[ bool, _Field( group="signatures", description="Show the type annotations in methods and functions signatures.", ), ] = False show_signature_type_parameters: Annotated[ bool, _Field( group="signatures", description="Show the type parameters in generic classes, methods, functions and type aliases signatures.", ), ] = False show_signature: Annotated[ bool, _Field( group="signatures", description="Show methods and functions signatures.", ), ] = True show_source: Annotated[ bool, _Field( group="general", description="Show the source code of this object.", ), ] = True show_submodules: Annotated[ bool, _Field( group="members", description="When rendering a module, show its submodules recursively.", ), ] = False show_symbol_type_heading: Annotated[ bool, _Field( group="headings", description="Show the symbol type in headings (e.g. mod, class, meth, func and attr).", ), ] = False show_symbol_type_toc: Annotated[ bool, _Field( group="headings", description="Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).", ), ] = False skip_local_inventory: Annotated[ bool, _Field( group="general", description="Whether to prevent objects from being registered in the local objects inventory.", ), ] = False signature_crossrefs: Annotated[ bool, _Field( group="signatures", description="Whether to render cross-references for type annotations in signatures.", ), ] = False summary: Annotated[ bool | SummaryOption, _Field( group="members", description="Whether to render summaries of modules, classes, functions (methods) and attributes.", ), ] = field(default_factory=SummaryOption) toc_label: Annotated[ str, _Field( group="headings", description="A custom string to override the autogenerated toc label of the root object.", ), ] = "" type_parameter_headings: Annotated[ bool, _Field( group="headings", description="Whether to render headings for type parameters (therefore showing type parameters in the ToC).", ), ] = False unwrap_annotated: Annotated[ bool, _Field( group="signatures", description="Whether to unwrap `Annotated` types to show only the type without the annotations.", ), ] = False extra: Annotated[ dict[str, Any], _Field( group="general", description="Extra options.", ), ] = field(default_factory=dict) @classmethod def _extract_extra(cls, data: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]: field_names = {field.name for field in fields(cls)} copy = data.copy() return {name: copy.pop(name) for name in data if name not in field_names}, copy @classmethod def coerce(cls, **data: Any) -> MutableMapping[str, Any]: """Coerce data.""" if "docstring_options" in data: docstring_style = data.get("docstring_style", "google") docstring_options = data["docstring_options"] if docstring_options is not None: if docstring_style == "auto": docstring_options = AutoStyleOptions.from_data(**docstring_options) elif docstring_style == "google": docstring_options = GoogleStyleOptions(**docstring_options) elif docstring_style == "numpy": docstring_options = NumpyStyleOptions(**docstring_options) elif docstring_style == "sphinx": docstring_options = SphinxStyleOptions(**docstring_options) data["docstring_options"] = docstring_options if "summary" in data: summary = data["summary"] if summary is True: summary = SummaryOption(attributes=True, functions=True, classes=True, modules=True, type_aliases=True) elif summary is False: summary = SummaryOption( attributes=False, functions=False, classes=False, modules=False, type_aliases=False, ) else: summary = SummaryOption(**summary) data["summary"] = summary return data @classmethod def from_data(cls, **data: Any) -> Self: """Create an instance from a dictionary.""" return cls(**cls.coerce(**data)) # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. @dataclass(**_dataclass_options) # type: ignore[call-overload] class PythonOptions(PythonInputOptions): # type: ignore[override,unused-ignore] """Final options passed as template context.""" filters: list[tuple[re.Pattern, bool]] | Literal["public"] = field( # type: ignore[assignment] default_factory=lambda: [ (re.compile(filtr.removeprefix("!")), filtr.startswith("!")) for filtr in _DEFAULT_FILTERS ], ) """A list of filters, or `"public"`.""" summary: SummaryOption = field(default_factory=SummaryOption) """Whether to render summaries of modules, classes, functions (methods), attributes and type aliases.""" @classmethod def coerce(cls, **data: Any) -> MutableMapping[str, Any]: """Create an instance from a dictionary.""" if "filters" in data: # Non-insiders: transform back to default filters. # Next: `if "filters" in data and not isinstance(data["filters"], str):`. if data["filters"] == "public": data["filters"] = _DEFAULT_FILTERS # Filters are `None` or a sequence of strings (tests use tuples). data["filters"] = [ (re.compile(filtr.removeprefix("!")), filtr.startswith("!")) for filtr in data["filters"] or () ] return super().coerce(**data) # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. @dataclass(**_dataclass_options) # type: ignore[call-overload] class Inventory: """An inventory.""" url: Annotated[ str, _Field( parent="inventories", description="The URL of the inventory.", ), ] base_url: Annotated[ str | None, _Field( parent="inventories", description="The base URL of the inventory.", ), ] = None domains: Annotated[ list[str], _Field( parent="inventories", description="The domains to load from the inventory.", ), ] = field(default_factory=lambda: ["py"]) @property def _config(self) -> dict[str, Any]: return {"base_url": self.base_url, "domains": self.domains} # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. @dataclass(**_dataclass_options) # type: ignore[call-overload] class PythonInputConfig: """Python handler configuration.""" inventories: Annotated[ list[str | Inventory], _Field(description="The inventories to load."), ] = field(default_factory=list) paths: Annotated[ list[str], _Field(description="The paths in which to search for Python packages."), ] = field(default_factory=lambda: ["."]) load_external_modules: Annotated[ bool | None, _Field(description="Whether to always load external modules/packages."), ] = None options: Annotated[ PythonInputOptions, _Field(description="Configuration options for collecting and rendering objects."), ] = field(default_factory=PythonInputOptions) locale: Annotated[ str | None, _Field( description="Deprecated. Use mkdocstrings' own `locale` setting instead. The locale to use when translating template strings.", ), ] = None @classmethod def coerce(cls, **data: Any) -> MutableMapping[str, Any]: """Coerce data.""" return data @classmethod def from_data(cls, **data: Any) -> Self: """Create an instance from a dictionary.""" return cls(**cls.coerce(**data)) # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. @dataclass(**_dataclass_options) # type: ignore[call-overload] class PythonConfig(PythonInputConfig): # type: ignore[override,unused-ignore] """Python handler configuration.""" inventories: Annotated[ list[Inventory], _Field(description="The object inventories to load."), ] = field(default_factory=list) # type: ignore[assignment] options: Annotated[ dict[str, Any], _Field(description="Configuration options for collecting and rendering objects."), ] = field(default_factory=dict) # type: ignore[assignment] @classmethod def coerce(cls, **data: Any) -> MutableMapping[str, Any]: """Coerce data.""" if "inventories" in data: data["inventories"] = [ Inventory(url=inv) if isinstance(inv, str) else Inventory(**inv) for inv in data["inventories"] ] return data ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1755598814.4891202 mkdocstrings_python-1.18.2/src/mkdocstrings_handlers/python/_internal/debug.py0000644000000000000000000000543515051047736024772 0ustar00from __future__ import annotations import os import platform import sys from dataclasses import dataclass from importlib import metadata @dataclass class _Variable: """Dataclass describing an environment variable.""" name: str """Variable name.""" value: str """Variable value.""" @dataclass class _Package: """Dataclass describing a Python package.""" name: str """Package name.""" version: str """Package version.""" @dataclass class _Environment: """Dataclass to store environment information.""" interpreter_name: str """Python interpreter name.""" interpreter_version: str """Python interpreter version.""" interpreter_path: str """Path to Python executable.""" platform: str """Operating System.""" packages: list[_Package] """Installed packages.""" variables: list[_Variable] """Environment variables.""" def _interpreter_name_version() -> tuple[str, str]: if hasattr(sys, "implementation"): impl = sys.implementation.version version = f"{impl.major}.{impl.minor}.{impl.micro}" kind = impl.releaselevel if kind != "final": version += kind[0] + str(impl.serial) return sys.implementation.name, version return "", "0.0.0" def _get_version(dist: str = "mkdocstrings-python") -> str: """Get version of the given distribution. Parameters: dist: A distribution name. Returns: A version number. """ try: return metadata.version(dist) except metadata.PackageNotFoundError: return "0.0.0" def _get_debug_info() -> _Environment: """Get debug/environment information. Returns: Environment information. """ py_name, py_version = _interpreter_name_version() packages = ["mkdocstrings-python"] variables = ["PYTHONPATH", *[var for var in os.environ if var.startswith("MKDOCSTRINGS_PYTHON")]] return _Environment( interpreter_name=py_name, interpreter_version=py_version, interpreter_path=sys.executable, platform=platform.platform(), variables=[_Variable(var, val) for var in variables if (val := os.getenv(var))], packages=[_Package(pkg, _get_version(pkg)) for pkg in packages], ) def _print_debug_info() -> None: """Print debug/environment information.""" info = _get_debug_info() print(f"- __System__: {info.platform}") print(f"- __Python__: {info.interpreter_name} {info.interpreter_version} ({info.interpreter_path})") print("- __Environment variables__:") for var in info.variables: print(f" - `{var.name}`: `{var.value}`") print("- __Installed packages__:") for pkg in info.packages: print(f" - `{pkg.name}` v{pkg.version}") if __name__ == "__main__": _print_debug_info() ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1756397314.5657327 mkdocstrings_python-1.18.2/src/mkdocstrings_handlers/python/_internal/handler.py0000644000000000000000000004051115054077403025310 0ustar00# This module implements a handler for the Python language. from __future__ import annotations import glob import os import posixpath import sys from contextlib import suppress from dataclasses import asdict from pathlib import Path from typing import TYPE_CHECKING, Any, BinaryIO, ClassVar from warnings import warn from griffe import ( AliasResolutionError, GriffeLoader, LinesCollection, ModulesCollection, Parser, load_extensions, patch_loggers, ) from mkdocs.exceptions import PluginError from mkdocstrings import BaseHandler, CollectionError, CollectorItem, HandlerOptions, Inventory, get_logger from mkdocstrings_handlers.python._internal import rendering from mkdocstrings_handlers.python._internal.config import PythonConfig, PythonOptions if TYPE_CHECKING: from collections.abc import Iterator, Mapping, MutableMapping, Sequence from mkdocs.config.defaults import MkDocsConfig # YORE: EOL 3.10: Replace block with line 2. if sys.version_info >= (3, 11): from contextlib import chdir else: from contextlib import contextmanager @contextmanager def chdir(path: str) -> Iterator[None]: old_wd = os.getcwd() os.chdir(path) try: yield finally: os.chdir(old_wd) _logger = get_logger(__name__) patch_loggers(get_logger) # YORE: Bump 2: Remove block. def _warn_extra_options(names: Sequence[str]) -> None: warn( "Passing extra options directly under `options` is deprecated. " "Instead, pass them under `options.extra`, and update your templates. " f"Current extra (unrecognized) options: {', '.join(sorted(names))}", DeprecationWarning, stacklevel=3, ) class PythonHandler(BaseHandler): """The Python handler class.""" name: ClassVar[str] = "python" """The handler's name.""" domain: ClassVar[str] = "py" """The cross-documentation domain/language for this handler.""" enable_inventory: ClassVar[bool] = True """Whether this handler is interested in enabling the creation of the `objects.inv` Sphinx inventory file.""" fallback_theme: ClassVar[str] = "material" """The fallback theme.""" def __init__(self, config: PythonConfig, base_dir: Path, **kwargs: Any) -> None: """Initialize the handler. Parameters: config: The handler configuration. base_dir: The base directory of the project. **kwargs: Arguments passed to the parent constructor. """ super().__init__(**kwargs) self.config = config """The handler configuration.""" self.base_dir = base_dir """The base directory of the project.""" # YORE: Bump 2: Remove block. global_extra, global_options = PythonOptions._extract_extra(config.options) if global_extra: _warn_extra_options(global_extra.keys()) # type: ignore[arg-type] self._global_extra = global_extra self.global_options = global_options """The global configuration options (in `mkdocs.yml`).""" # YORE: Bump 2: Replace `# ` with `` within block. # self.global_options = config.options # """The global configuration options (in `mkdocs.yml`).""" # Warn if user overrides base templates. if self.custom_templates: for theme_dir in base_dir.joinpath(self.custom_templates, "python").iterdir(): if theme_dir.joinpath("_base").is_dir(): _logger.warning( f"Overriding base template '{theme_dir.name}/_base/