├── logo.png ├── scripts ├── make ├── get_version.py ├── griffe_extensions.py └── mkdocs_hooks.py ├── .envrc ├── src └── mkdocstrings_handlers │ └── python │ ├── py.typed │ ├── _internal │ ├── __init__.py │ └── debug.py │ ├── templates │ ├── readthedocs │ │ ├── class.html │ │ ├── class.html.jinja │ │ ├── language.html.jinja │ │ ├── languages │ │ │ ├── en.html.jinja │ │ │ ├── ja.html.jinja │ │ │ └── zh.html.jinja │ │ ├── docstring │ │ │ ├── raises.html.jinja │ │ │ ├── returns.html.jinja │ │ │ ├── warns.html.jinja │ │ │ ├── yields.html.jinja │ │ │ ├── receives.html.jinja │ │ │ ├── attributes.html.jinja │ │ │ ├── parameters.html.jinja │ │ │ └── other_parameters.html.jinja │ │ ├── _base │ │ │ ├── class.html │ │ │ ├── language.html.jinja │ │ │ ├── languages │ │ │ │ ├── zh.html.jinja │ │ │ │ ├── ja.html.jinja │ │ │ │ └── en.html.jinja │ │ │ └── docstring │ │ │ │ ├── warns.html.jinja │ │ │ │ ├── raises.html.jinja │ │ │ │ ├── attributes.html.jinja │ │ │ │ ├── other_parameters.html.jinja │ │ │ │ ├── returns.html.jinja │ │ │ │ ├── yields.html.jinja │ │ │ │ ├── receives.html.jinja │ │ │ │ └── parameters.html.jinja │ │ └── style.css │ └── material │ │ ├── class.html.jinja │ │ ├── labels.html.jinja │ │ ├── module.html.jinja │ │ ├── children.html.jinja │ │ ├── function.html.jinja │ │ ├── language.html.jinja │ │ ├── summary.html.jinja │ │ ├── type_alias.html │ │ ├── attribute.html.jinja │ │ ├── backlinks.html.jinja │ │ ├── docstring.html.jinja │ │ ├── expression.html.jinja │ │ ├── signature.html.jinja │ │ ├── type_alias.html.jinja │ │ ├── languages │ │ ├── en.html.jinja │ │ ├── ja.html.jinja │ │ └── zh.html.jinja │ │ ├── type_parameters.html │ │ ├── docstring │ │ ├── raises.html.jinja │ │ ├── warns.html.jinja │ │ ├── yields.html.jinja │ │ ├── classes.html.jinja │ │ ├── examples.html.jinja │ │ ├── modules.html.jinja │ │ ├── receives.html.jinja │ │ ├── returns.html.jinja │ │ ├── admonition.html.jinja │ │ ├── attributes.html.jinja │ │ ├── functions.html.jinja │ │ ├── parameters.html.jinja │ │ ├── type_aliases.html │ │ ├── type_aliases.html.jinja │ │ ├── type_parameters.html │ │ ├── other_parameters.html.jinja │ │ └── type_parameters.html.jinja │ │ ├── summary │ │ ├── classes.html.jinja │ │ ├── modules.html.jinja │ │ ├── attributes.html.jinja │ │ ├── functions.html.jinja │ │ ├── type_aliases.html │ │ └── type_aliases.html.jinja │ │ ├── type_parameters.html.jinja │ │ └── _base │ │ ├── language.html.jinja │ │ ├── docstring │ │ ├── admonition.html.jinja │ │ ├── examples.html.jinja │ │ ├── classes.html.jinja │ │ ├── modules.html.jinja │ │ └── type_aliases.html.jinja │ │ ├── summary │ │ ├── modules.html.jinja │ │ ├── classes.html.jinja │ │ ├── attributes.html.jinja │ │ ├── functions.html.jinja │ │ └── type_aliases.html.jinja │ │ ├── labels.html.jinja │ │ ├── summary.html.jinja │ │ ├── languages │ │ ├── zh.html.jinja │ │ ├── ja.html.jinja │ │ └── en.html.jinja │ │ ├── backlinks.html.jinja │ │ ├── type_parameters.html.jinja │ │ └── docstring.html.jinja │ └── __init__.py ├── .github ├── FUNDING.yml ├── ISSUE_TEMPLATE │ ├── config.yml │ ├── 3-docs.md │ ├── 4-change.md │ ├── 2-feature.md │ └── 1-bug.md ├── pull_request_template.md └── workflows │ ├── release.yml │ └── sponsors.yml ├── docs ├── logo.png ├── changelog.md ├── contributing.md ├── code_of_conduct.md ├── index.md ├── snippets │ └── package │ │ ├── modern.py │ │ ├── __init__.py │ │ └── generics.py ├── license.md ├── credits.md ├── reference │ └── api.md ├── usage │ ├── docstrings │ │ ├── sphinx.md │ │ ├── numpy.md │ │ └── google.md │ └── extensions.md ├── js │ └── feedback.js ├── .overrides │ └── partials │ │ ├── path-item.html │ │ └── comments.html ├── .glossary.md └── css │ ├── material.css │ └── mkdocstrings.css ├── config ├── black.toml ├── mypy.ini ├── git-changelog.toml ├── coverage.ini ├── pytest.ini ├── vscode │ ├── settings.json │ ├── launch.json │ └── tasks.json └── ruff.toml ├── tests ├── __init__.py ├── snapshots │ ├── headings │ │ ├── heading=Some heading,separate_signature=False.html │ │ ├── heading=Some heading,separate_signature=True.html │ │ ├── heading=,separate_signature=False.html │ │ └── heading=,separate_signature=True.html │ ├── members │ │ ├── filters=(),inherited_members=(),members=().html │ │ ├── filters=(),inherited_members=(),members=False.html │ │ ├── filters=(),inherited_members=False,members=().html │ │ ├── filters=(),inherited_members=True,members=().html │ │ ├── filters=None,inherited_members=(),members=().html │ │ ├── filters=None,inherited_members=True,members=().html │ │ ├── filters=(),inherited_members=False,members=False.html │ │ ├── filters=(),inherited_members=True,members=False.html │ │ ├── filters=None,inherited_members=(),members=False.html │ │ ├── filters=None,inherited_members=False,members=().html │ │ ├── filters=public,inherited_members=(),members=().html │ │ ├── filters=None,inherited_members=False,members=False.html │ │ ├── filters=None,inherited_members=True,members=False.html │ │ ├── filters=public,inherited_members=(),members=False.html │ │ ├── filters=public,inherited_members=False,members=().html │ │ ├── filters=public,inherited_members=True,members=().html │ │ ├── filters=public,inherited_members=False,members=False.html │ │ ├── filters=public,inherited_members=True,members=False.html │ │ ├── filters=(),inherited_members=('method1',),members=().html │ │ ├── filters=(),inherited_members=('method1',),members=False.html │ │ ├── filters=None,inherited_members=('method1',),members=().html │ │ ├── filters=None,inherited_members=('method1',),members=False.html │ │ ├── filters=public,inherited_members=('method1',),members=().html │ │ ├── filters=public,inherited_members=('method1',),members=False.html │ │ ├── filters=('!module_attribute',),inherited_members=(),members=().html │ │ ├── filters=('module_attribute',),inherited_members=(),members=().html │ │ ├── filters=('!module_attribute',),inherited_members=(),members=False.html │ │ ├── filters=('!module_attribute',),inherited_members=False,members=().html │ │ ├── filters=('!module_attribute',),inherited_members=True,members=().html │ │ ├── filters=('module_attribute',),inherited_members=(),members=False.html │ │ ├── filters=('module_attribute',),inherited_members=False,members=().html │ │ ├── filters=('module_attribute',),inherited_members=True,members=().html │ │ ├── filters=('!module_attribute',),inherited_members=True,members=False.html │ │ ├── filters=('module_attribute',),inherited_members=False,members=False.html │ │ ├── filters=('module_attribute',),inherited_members=True,members=False.html │ │ ├── filters=('!module_attribute',),inherited_members=False,members=False.html │ │ ├── filters=('module_attribute',),inherited_members=('method1',),members=().html │ │ ├── filters=('!module_attribute',),inherited_members=('method1',),members=().html │ │ ├── filters=('module_attribute',),inherited_members=('method1',),members=False.html │ │ ├── filters=('!module_attribute',),inherited_members=('method1',),members=False.html │ │ ├── filters=(),inherited_members=(),members=('module_attribute',).html │ │ ├── filters=('module_attribute',),inherited_members=(),members=None.html │ │ ├── filters=('module_attribute',),inherited_members=True,members=None.html │ │ ├── filters=(),inherited_members=False,members=('module_attribute',).html │ │ ├── filters=(),inherited_members=True,members=('module_attribute',).html │ │ ├── filters=None,inherited_members=(),members=('module_attribute',).html │ │ ├── filters=None,inherited_members=True,members=('module_attribute',).html │ │ ├── filters=('module_attribute',),inherited_members=False,members=None.html │ │ ├── filters=None,inherited_members=False,members=('module_attribute',).html │ │ ├── filters=public,inherited_members=(),members=('module_attribute',).html │ │ ├── filters=public,inherited_members=False,members=('module_attribute',).html │ │ ├── filters=public,inherited_members=True,members=('module_attribute',).html │ │ ├── filters=(),inherited_members=('method1',),members=('module_attribute',).html │ │ ├── filters=('module_attribute',),inherited_members=('method1',),members=None.html │ │ ├── filters=None,inherited_members=('method1',),members=('module_attribute',).html │ │ ├── filters=public,inherited_members=('method1',),members=('module_attribute',).html │ │ ├── filters=('!module_attribute',),inherited_members=(),members=('module_attribute',).html │ │ ├── filters=('module_attribute',),inherited_members=(),members=('module_attribute',).html │ │ ├── filters=('!module_attribute',),inherited_members=False,members=('module_attribute',).html │ │ ├── filters=('!module_attribute',),inherited_members=True,members=('module_attribute',).html │ │ ├── filters=('module_attribute',),inherited_members=False,members=('module_attribute',).html │ │ ├── filters=('module_attribute',),inherited_members=True,members=('module_attribute',).html │ │ ├── filters=('module_attribute',),inherited_members=('method1',),members=('module_attribute',).html │ │ ├── filters=('!module_attribute',),inherited_members=('method1',),members=('module_attribute',).html │ │ ├── filters=('module_attribute',),inherited_members=(),members=True.html │ │ ├── filters=('module_attribute',),inherited_members=True,members=True.html │ │ └── filters=('module_attribute',),inherited_members=False,members=True.html │ ├── signatures │ │ ├── separate_signature=True,show_signature_annotations=False,signature_crossrefs=False.html │ │ ├── separate_signature=True,show_signature_annotations=False,signature_crossrefs=True.html │ │ ├── separate_signature=False,show_signature_annotations=False,signature_crossrefs=False.html │ │ ├── separate_signature=False,show_signature_annotations=False,signature_crossrefs=True.html │ │ └── separate_signature=True,show_signature_annotations=True,signature_crossrefs=False.html │ └── overloads │ │ └── overloads_only=False,separate_signature=True,show_overloads=False.html ├── test_themes.py └── helpers.py ├── .gitignore ├── .copier-answers.yml ├── LICENSE └── Makefile /logo.png: -------------------------------------------------------------------------------- 1 | docs/logo.png -------------------------------------------------------------------------------- /scripts/make: -------------------------------------------------------------------------------- 1 | make.py -------------------------------------------------------------------------------- /.envrc: -------------------------------------------------------------------------------- 1 | PATH_add scripts 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/py.typed: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | github: pawamoy 2 | polar: pawamoy 3 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/_internal/__init__.py: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /docs/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mkdocstrings/python/HEAD/docs/logo.png -------------------------------------------------------------------------------- /config/black.toml: -------------------------------------------------------------------------------- 1 | [tool.black] 2 | line-length = 120 3 | exclude = "tests/fixtures" 4 | -------------------------------------------------------------------------------- /docs/changelog.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Changelog 3 | --- 4 | 5 | --8<-- "CHANGELOG.md" 6 | -------------------------------------------------------------------------------- /docs/contributing.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Contributing 3 | --- 4 | 5 | --8<-- "CONTRIBUTING.md" 6 | -------------------------------------------------------------------------------- /docs/code_of_conduct.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Code of Conduct 3 | --- 4 | 5 | --8<-- "CODE_OF_CONDUCT.md" 6 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Overview 3 | hide: 4 | - feedback 5 | --- 6 | 7 | --8<-- "README.md" 8 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/class.html: -------------------------------------------------------------------------------- 1 | {% extends "_base/class.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/class.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/class.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/labels.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/labels.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/module.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/module.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/children.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/children.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/function.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/function.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/language.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/language.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/summary.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/summary.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/type_alias.html: -------------------------------------------------------------------------------- 1 | {% extends "_base/type_alias.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/class.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/class.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/attribute.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/attribute.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/backlinks.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/backlinks.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/expression.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/expression.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/signature.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/signature.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/type_alias.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/type_alias.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/language.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/language.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/languages/en.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/languages/en.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/languages/ja.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/languages/ja.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/languages/zh.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/languages/zh.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/type_parameters.html: -------------------------------------------------------------------------------- 1 | {% extends "_base/type_parameters.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/languages/en.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/languages/en.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/languages/ja.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/languages/ja.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/languages/zh.html.jinja" %} 2 | -------------------------------------------------------------------------------- /docs/snippets/package/modern.py: -------------------------------------------------------------------------------- 1 | from typing import Optional, Union, List 2 | 3 | example: Optional[Union[int, List[int]]] = None 4 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/raises.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/raises.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/warns.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/warns.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/yields.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/yields.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/summary/classes.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/summary/classes.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/summary/modules.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/summary/modules.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/type_parameters.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/type_parameters.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/classes.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/classes.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/examples.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/examples.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/modules.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/modules.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/receives.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/receives.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/returns.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/returns.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/summary/attributes.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/summary/attributes.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/summary/functions.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/summary/functions.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/summary/type_aliases.html: -------------------------------------------------------------------------------- 1 | {% extends "_base/summary/type_aliases.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/raises.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/returns.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/warns.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/yields.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/admonition.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/admonition.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/attributes.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/attributes.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/functions.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/functions.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/parameters.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/parameters.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/type_aliases.html: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/type_aliases.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/summary/type_aliases.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/summary/type_aliases.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/receives.html.jinja" %} 2 | -------------------------------------------------------------------------------- /docs/license.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: License 3 | hide: 4 | - feedback 5 | --- 6 | 7 | # License 8 | 9 | ``` 10 | --8<-- "LICENSE" 11 | ``` 12 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/type_aliases.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/type_aliases.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/type_parameters.html: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/type_parameters.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/attributes.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/parameters.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/other_parameters.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/other_parameters.html.jinja" %} 2 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/docstring/type_parameters.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/type_parameters.html.jinja" %} 2 | -------------------------------------------------------------------------------- /docs/credits.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Credits 3 | hide: 4 | - toc 5 | --- 6 | 7 | ```python exec="yes" 8 | --8<-- "scripts/gen_credits.py" 9 | ``` 10 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html.jinja: -------------------------------------------------------------------------------- 1 | {% extends "_base/docstring/other_parameters.html.jinja" %} 2 | -------------------------------------------------------------------------------- /docs/reference/api.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: API reference 3 | hide: 4 | - navigation 5 | --- 6 | 7 | # ::: mkdocstrings_handlers.python 8 | options: 9 | show_submodules: true 10 | -------------------------------------------------------------------------------- /config/mypy.ini: -------------------------------------------------------------------------------- 1 | [mypy] 2 | ignore_missing_imports = true 3 | exclude = tests/fixtures/ 4 | warn_unused_ignores = true 5 | show_error_codes = true 6 | namespace_packages = true 7 | explicit_package_bases = true 8 | -------------------------------------------------------------------------------- /tests/__init__.py: -------------------------------------------------------------------------------- 1 | """Tests suite for `mkdocstrings_handlers`.""" 2 | 3 | from pathlib import Path 4 | 5 | TESTS_DIR = Path(__file__).parent 6 | TMP_DIR = TESTS_DIR / "tmp" 7 | FIXTURES_DIR = TESTS_DIR / "fixtures" 8 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | contact_links: 3 | - name: I have a question / I need help 4 | url: https://github.com/mkdocstrings/python/discussions/new?category=q-a 5 | about: Ask and answer questions in the Discussions tab. 6 | -------------------------------------------------------------------------------- /config/git-changelog.toml: -------------------------------------------------------------------------------- 1 | bump = "auto" 2 | convention = "angular" 3 | in-place = true 4 | output = "CHANGELOG.md" 5 | parse-refs = false 6 | parse-trailers = true 7 | sections = ["build", "deps", "feat", "fix", "refactor"] 8 | template = "keepachangelog" 9 | versioning = "pep440" 10 | -------------------------------------------------------------------------------- /docs/usage/docstrings/sphinx.md: -------------------------------------------------------------------------------- 1 | # Sphinx style 2 | 3 | ## :warning: Work in Progress! 4 | 5 | See [Sphinx's documentation](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html). 6 | See the supported docstring sections on [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/). 7 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # editors 2 | .idea/ 3 | .vscode/ 4 | 5 | # python 6 | *.egg-info/ 7 | *.py[cod] 8 | .venv/ 9 | .venvs/ 10 | /build/ 11 | /dist/ 12 | 13 | # tools 14 | .coverage* 15 | /.pdm-build/ 16 | /htmlcov/ 17 | /site/ 18 | uv.lock 19 | 20 | # cache 21 | .cache/ 22 | .pytest_cache/ 23 | .mypy_cache/ 24 | .ruff_cache/ 25 | __pycache__/ 26 | -------------------------------------------------------------------------------- /tests/snapshots/headings/heading=Some heading,separate_signature=False.html: -------------------------------------------------------------------------------- 1 | 7 | 8 |
9 |

10 | Some heading 11 |

12 |
13 |
14 |
15 |
16 |
17 | -------------------------------------------------------------------------------- /tests/snapshots/headings/heading=Some heading,separate_signature=True.html: -------------------------------------------------------------------------------- 1 | 7 | 8 |
9 |

10 | Some heading 11 |

12 |
13 |
14 |
15 |
16 |
17 | -------------------------------------------------------------------------------- /tests/snapshots/headings/heading=,separate_signature=False.html: -------------------------------------------------------------------------------- 1 | 7 | 8 |
9 |

10 | 11 | headings_package 12 | 13 |

14 |
15 |
16 |
17 |
18 |
19 | -------------------------------------------------------------------------------- /tests/snapshots/headings/heading=,separate_signature=True.html: -------------------------------------------------------------------------------- 1 | 7 | 8 |
9 |

10 | 11 | headings_package 12 | 13 |

14 |
15 |
16 |
17 |
18 |
19 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=(),inherited_members=(),members=().html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=(),inherited_members=(),members=False.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=(),inherited_members=False,members=().html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=(),inherited_members=True,members=().html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=None,inherited_members=(),members=().html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=None,inherited_members=True,members=().html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | ### For reviewers 2 | 3 | 4 | - [ ] I did not use AI 5 | - [ ] I used AI and thoroughly reviewed every code/docs change 6 | 7 | ### Description of the change 8 | 9 | 10 | ### Relevant resources 11 | 12 | 13 | - 14 | - 15 | - 16 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/_base/class.html: -------------------------------------------------------------------------------- 1 | {% extends "_base/class.html.jinja" %} 2 | 3 | {% block logs scoped %} 4 | {{ super() }} 5 | {# TODO: Switch to a warning after some time. #} 6 | {{ log.info( 7 | "DeprecationWarning: Extending '_base/class.html' is deprecated, extend '_base/class.html.jinja' instead. " ~ 8 | "After some time, this message will be logged as a warning, causing strict builds to fail.", 9 | once=True, 10 | ) }} 11 | {% endblock logs %} 12 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=(),inherited_members=False,members=False.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=(),inherited_members=True,members=False.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=None,inherited_members=(),members=False.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=None,inherited_members=False,members=().html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=public,inherited_members=(),members=().html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=None,inherited_members=False,members=False.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=None,inherited_members=True,members=False.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=public,inherited_members=(),members=False.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=public,inherited_members=False,members=().html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=public,inherited_members=True,members=().html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=public,inherited_members=False,members=False.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=public,inherited_members=True,members=False.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
10 |

11 | 12 | members_package 13 | 14 |

15 |
16 |

17 | Docstring for the package. 18 |

19 |
20 |
21 |
22 |
23 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=(),inherited_members=('method1',),members=().html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=(),inherited_members=('method1',),members=False.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=None,inherited_members=('method1',),members=().html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /config/coverage.ini: -------------------------------------------------------------------------------- 1 | [coverage:run] 2 | branch = true 3 | parallel = true 4 | source = 5 | src/mkdocstrings_handlers 6 | tests/ 7 | 8 | [coverage:paths] 9 | equivalent = 10 | src/ 11 | .venv/lib/*/site-packages/ 12 | .venvs/*/lib/*/site-packages/ 13 | 14 | [coverage:report] 15 | include_namespace_packages = true 16 | precision = 2 17 | omit = 18 | src/*/__init__.py 19 | src/*/__main__.py 20 | tests/__init__.py 21 | exclude_lines = 22 | pragma: no cover 23 | if TYPE_CHECKING 24 | 25 | [coverage:json] 26 | output = htmlcov/coverage.json 27 | -------------------------------------------------------------------------------- /docs/snippets/package/__init__.py: -------------------------------------------------------------------------------- 1 | from importlib import metadata 2 | 3 | def get_version(dist: str = "mkdocstrings-python") -> str: 4 | """Get version of the given distribution. 5 | 6 | Parameters: 7 | dist: A distribution name. 8 | 9 | Returns: 10 | A version number. 11 | """ 12 | try: 13 | return metadata.version(dist) 14 | except metadata.PackageNotFoundError: 15 | return "0.0.0" 16 | 17 | 18 | current_version: str = get_version(dist="mkdocstrings-python") 19 | """Current package version.""" 20 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=None,inherited_members=('method1',),members=False.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=public,inherited_members=('method1',),members=().html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=public,inherited_members=('method1',),members=False.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /config/pytest.ini: -------------------------------------------------------------------------------- 1 | [pytest] 2 | python_files = 3 | test_*.py 4 | addopts = 5 | --cov 6 | --cov-config config/coverage.ini 7 | testpaths = 8 | tests 9 | 10 | # action:message_regex:warning_class:module_regex:line 11 | filterwarnings = 12 | error 13 | default::EncodingWarning 14 | error::EncodingWarning:python 15 | # TODO: Remove once pytest-xdist 4 is released. 16 | ignore:.*rsyncdir:DeprecationWarning:xdist 17 | # TODO: Remove once mkdocstrings stops setting fallback function. 18 | ignore:.*fallback anchor function:DeprecationWarning:mkdocstrings 19 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=().html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=().html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=False.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=().html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=().html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=False.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=().html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=().html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=False.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=False.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=False.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /docs/js/feedback.js: -------------------------------------------------------------------------------- 1 | const feedback = document.forms.feedback; 2 | feedback.hidden = false; 3 | 4 | feedback.addEventListener("submit", function(ev) { 5 | ev.preventDefault(); 6 | const commentElement = document.getElementById("feedback"); 7 | commentElement.style.display = "block"; 8 | feedback.firstElementChild.disabled = true; 9 | const data = ev.submitter.getAttribute("data-md-value"); 10 | const note = feedback.querySelector(".md-feedback__note [data-md-value='" + data + "']"); 11 | if (note) { 12 | note.hidden = false; 13 | } 14 | }) 15 | -------------------------------------------------------------------------------- /docs/usage/docstrings/numpy.md: -------------------------------------------------------------------------------- 1 | # Numpydoc style 2 | 3 | ## :warning: Work in Progress! 4 | 5 | NOTE: As Numpy-style is partially supported by the underlying parser, 6 | you may experience problems in the building process if your docstring 7 | has a `Methods` section in the class docstring 8 | (see [#366](https://github.com/mkdocstrings/mkdocstrings/issues/366)). 9 | 10 | See [Numpydoc's documentation](https://numpydoc.readthedocs.io/en/latest/format.html). 11 | See the supported docstring sections on [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/). 12 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=False.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
12 |

13 | 14 | members_package 15 | 16 |

17 |
18 |

19 | Docstring for the package. 20 |

21 |
22 |
23 |
24 |
25 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=().html: -------------------------------------------------------------------------------- 1 | 12 | 13 |
14 |

15 | 16 | members_package 17 | 18 |

19 |
20 |

21 | Docstring for the package. 22 |

23 |
24 |
25 |
26 |
27 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=().html: -------------------------------------------------------------------------------- 1 | 12 | 13 |
14 |

15 | 16 | members_package 17 | 18 |

19 |
20 |

21 | Docstring for the package. 22 |

23 |
24 |
25 |
26 |
27 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=False.html: -------------------------------------------------------------------------------- 1 | 12 | 13 |
14 |

15 | 16 | members_package 17 | 18 |

19 |
20 |

21 | Docstring for the package. 22 |

23 |
24 |
25 |
26 |
27 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=False.html: -------------------------------------------------------------------------------- 1 | 12 | 13 |
14 |

15 | 16 | members_package 17 | 18 |

19 |
20 |

21 | Docstring for the package. 22 |

23 |
24 |
25 |
26 |
27 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/3-docs.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Documentation update 3 | about: Point at unclear, missing or outdated documentation. 4 | title: "docs: " 5 | labels: docs 6 | assignees: pawamoy 7 | --- 8 | 9 | ### Is something unclear, missing or outdated in our documentation? 10 | 11 | 12 | ### Relevant code snippets 13 | 14 | 15 | ### Link to the relevant documentation section 16 | 17 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/4-change.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Change request 3 | about: Suggest any other kind of change for this project. 4 | title: "change: " 5 | assignees: pawamoy 6 | --- 7 | 8 | ### Is your change request related to a problem? Please describe. 9 | 10 | 11 | ### Describe the solution you'd like 12 | 13 | 14 | ### Describe alternatives you've considered 15 | 16 | 17 | ### Additional context 18 | 19 | -------------------------------------------------------------------------------- /.copier-answers.yml: -------------------------------------------------------------------------------- 1 | # Changes here will be overwritten by Copier. 2 | _commit: 1.6.1 3 | _src_path: gh:mkdocstrings/handler-template 4 | author_email: dev@pawamoy.fr 5 | author_fullname: Timothée Mazzucotelli 6 | author_username: pawamoy 7 | copyright_date: '2021' 8 | copyright_holder: Timothée Mazzucotelli 9 | copyright_holder_email: dev@pawamoy.fr 10 | copyright_license: ISC 11 | language: Python 12 | project_description: A Python handler for mkdocstrings. 13 | project_name: mkdocstrings-python 14 | python_package_distribution_name: mkdocstrings-python 15 | python_package_import_name: python 16 | repository_name: python 17 | repository_namespace: mkdocstrings 18 | repository_provider: github.com 19 | 20 | -------------------------------------------------------------------------------- /docs/usage/extensions.md: -------------------------------------------------------------------------------- 1 | # Extensions 2 | 3 | ## :warning: Work in Progress! 4 | 5 | The Python handler supports extensions through 6 | [*mkdocstrings*' handler extensions](https://mkdocstrings.github.io/usage/handlers/#handler-extensions). 7 | 8 | Specifically, additional templates can be added to the handler, 9 | and Griffe extensions can instruct the handler to use a particular template 10 | for a particular object by setting a value in the Griffe object's `extra` dictionary: 11 | 12 | ```python title="griffe_extension.py" 13 | obj = ... # get a reference to a Griffe object 14 | if "mkdocstrings" not in obj.extra: 15 | obj.extra["mkdocstrings"] = {} 16 | obj.extra["mkdocstrings"]["template"] = "template_name.html" 17 | ``` 18 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/2-feature.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project. 4 | title: "feature: " 5 | labels: feature 6 | assignees: pawamoy 7 | --- 8 | 9 | ### Is your feature request related to a problem? Please describe. 10 | 11 | 12 | ### Describe the solution you'd like 13 | 14 | 15 | ### Describe alternatives you've considered 16 | 17 | 18 | ### Additional context 19 | 20 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Import translation macros for the given language and fallback language. -#} 2 | 3 | {% block logs scoped %} 4 | {#- Logging block. 5 | 6 | This block can be used to log debug messages, deprecation messages, warnings, etc. 7 | -#} 8 | {% endblock logs %} 9 | 10 | {% set lang_pth = "languages/" ~ locale ~ ".html.jinja" %} 11 | {% if lang_pth is existing_template %} 12 | {% import lang_pth as lang %} 13 | {% import "languages/en.html.jinja" as fallback %} 14 | {% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %} 15 | {% else %} 16 | {% import "languages/en.html.jinja" as lang %} 17 | {% macro t(key) %}{{ lang.t(key) }}{% endmacro %} 18 | {% endif %} 19 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Import translation macros for the given language and fallback language. -#} 2 | 3 | {% block logs scoped %} 4 | {#- Logging block. 5 | 6 | This block can be used to log debug messages, deprecation messages, warnings, etc. 7 | -#} 8 | {% endblock logs %} 9 | 10 | {% set lang_pth = "languages/" ~ locale ~ ".html.jinja" %} 11 | {% if lang_pth is existing_template %} 12 | {% import lang_pth as lang %} 13 | {% import "languages/en.html.jinja" as fallback %} 14 | {% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %} 15 | {% else %} 16 | {% import "languages/en.html.jinja" as lang %} 17 | {% macro t(key) %}{{ lang.t(key) }}{% endmacro %} 18 | {% endif %} 19 | -------------------------------------------------------------------------------- /docs/.overrides/partials/path-item.html: -------------------------------------------------------------------------------- 1 | {# Fix breadcrumbs for when mkdocs-section-index is used. #} 2 | {# See https://github.com/squidfunk/mkdocs-material/issues/7614. #} 3 | 4 | 5 | {% macro render_content(nav_item) %} 6 | 7 | {{ nav_item.title }} 8 | 9 | {% endmacro %} 10 | 11 | 12 | {% macro render(nav_item, ref=nav_item) %} 13 | {% if nav_item.is_page %} 14 |
  • 15 | 16 | {{ render_content(ref) }} 17 | 18 |
    • 19 | {% elif nav_item.children %} 20 | {{ render(nav_item.children | first, ref) }} 21 | {% endif %} 22 | {% endmacro %} 23 | -------------------------------------------------------------------------------- /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | name: release 2 | 3 | on: push 4 | permissions: 5 | contents: write 6 | 7 | jobs: 8 | release: 9 | runs-on: ubuntu-latest 10 | if: startsWith(github.ref, 'refs/tags/') 11 | steps: 12 | - name: Checkout 13 | uses: actions/checkout@v4 14 | with: 15 | fetch-depth: 0 16 | fetch-tags: true 17 | - name: Setup Python 18 | uses: actions/setup-python@v6 19 | with: 20 | python-version: "3.13" 21 | - name: Setup uv 22 | uses: astral-sh/setup-uv@v5 23 | - name: Prepare release notes 24 | run: uv tool run git-changelog --release-notes > release-notes.md 25 | - name: Create release 26 | uses: softprops/action-gh-release@v2 27 | with: 28 | body_path: release-notes.md 29 | 30 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | ISC License 2 | 3 | Copyright (c) 2021, Timothée Mazzucotelli 4 | 5 | Permission to use, copy, modify, and/or distribute this software for any 6 | purpose with or without fee is hereby granted, provided that the above 7 | copyright notice and this permission notice appear in all copies. 8 | 9 | THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10 | WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11 | MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12 | ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14 | ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15 | OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16 | -------------------------------------------------------------------------------- /.github/workflows/sponsors.yml: -------------------------------------------------------------------------------- 1 | name: Update sponsors 2 | 3 | on: 4 | schedule: 5 | - cron: '0 0 * * *' 6 | workflow_dispatch: 7 | 8 | permissions: 9 | contents: write 10 | pull-requests: write 11 | 12 | jobs: 13 | update-readme: 14 | runs-on: ubuntu-latest 15 | steps: 16 | - name: Checkout repository 17 | uses: actions/checkout@v4 18 | - name: Update README and create PR 19 | uses: pawamoy/readme-insert@main 20 | with: 21 | markup-url: https://pawamoy.github.io/sponsors.txt 22 | start-marker: '' 23 | end-marker: '' 24 | commit-message: 'chore: Update sponsors section in README' 25 | pr-title: 'chore: Update sponsors section in README' 26 | pr-body: 'This PR updates the sponsors section in the README file.' 27 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for admonitions in docstrings. 2 | 3 | This template renders admonitions using the `details` HTML element. 4 | 5 | Context: 6 | section (griffe.DocstringSectionAdmonition): The section to render. 7 | -#} 8 | 9 | {% block logs scoped %} 10 | {#- Logging block. 11 | 12 | This block can be used to log debug messages, deprecation messages, warnings, etc. 13 | -#} 14 | {{ log.debug("Rendering admonition") }} 15 | {% endblock logs %} 16 | 17 |
    18 | {{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True, autoref_hook=autoref_hook) }} 19 | {{ section.value.contents|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 20 |
    21 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # If you have `direnv` loaded in your shell, and allow it in the repository, 2 | # the `make` command will point at the `scripts/make` shell script. 3 | # This Makefile is just here to allow auto-completion in the terminal. 4 | 5 | default: help 6 | @echo 7 | @echo 'Enable direnv in your shell to use the `make` command: `direnv allow`' 8 | @echo 'Or use `python scripts/make ARGS` to run the commands/tasks directly.' 9 | 10 | .DEFAULT_GOAL: default 11 | 12 | actions = \ 13 | allrun \ 14 | changelog \ 15 | check \ 16 | check-api \ 17 | check-docs \ 18 | check-quality \ 19 | check-types \ 20 | clean \ 21 | coverage \ 22 | docs \ 23 | docs-deploy \ 24 | format \ 25 | help \ 26 | multirun \ 27 | release \ 28 | run \ 29 | setup \ 30 | test \ 31 | vscode 32 | 33 | .PHONY: $(actions) 34 | $(actions): 35 | @python scripts/make "$@" 36 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/summary/modules.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Summary of modules. -#} 2 | 3 | {% block logs scoped %} 4 | {#- Logging block. 5 | 6 | This block can be used to log debug messages, deprecation messages, warnings, etc. 7 | -#} 8 | {% endblock logs %} 9 | 10 | {% if not obj.docstring.parsed | selectattr("kind.value", "eq", "modules") | list %} 11 | {% with section = obj.modules 12 | |filter_objects( 13 | filters=config.filters, 14 | members_list=members_list, 15 | inherited_members=config.inherited_members, 16 | keep_no_docstrings=config.show_if_no_docstring, 17 | ) 18 | |order_members("alphabetical", members_list) 19 | |as_modules_section(check_public=not members_list) 20 | %} 21 | {% if section %}{% include "docstring/modules.html.jinja" with context %}{% endif %} 22 | {% endwith %} 23 | {% endif %} 24 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/summary/classes.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Summary of classes. -#} 2 | 3 | {% block logs scoped %} 4 | {#- Logging block. 5 | 6 | This block can be used to log debug messages, deprecation messages, warnings, etc. 7 | -#} 8 | {% endblock logs %} 9 | 10 | {% if not obj.docstring.parsed | selectattr("kind.value", "eq", "classes") | list %} 11 | {% with section = obj.classes 12 | |filter_objects( 13 | filters=config.filters, 14 | members_list=members_list, 15 | inherited_members=config.inherited_members, 16 | keep_no_docstrings=config.show_if_no_docstring, 17 | ) 18 | |order_members(config.members_order, members_list) 19 | |as_classes_section(check_public=not members_list) 20 | %} 21 | {% if section %}{% include "docstring/classes.html.jinja" with context %}{% endif %} 22 | {% endwith %} 23 | {% endif %} 24 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/summary/attributes.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Summary of attributes. -#} 2 | 3 | {% block logs scoped %} 4 | {#- Logging block. 5 | 6 | This block can be used to log debug messages, deprecation messages, warnings, etc. 7 | -#} 8 | {% endblock logs %} 9 | 10 | {% if not obj.docstring.parsed | selectattr("kind.value", "eq", "attributes") | list %} 11 | {% with section = obj.attributes 12 | |filter_objects( 13 | filters=config.filters, 14 | members_list=members_list, 15 | inherited_members=config.inherited_members, 16 | keep_no_docstrings=config.show_if_no_docstring, 17 | ) 18 | |order_members(config.members_order, members_list) 19 | |as_attributes_section(check_public=not members_list) 20 | %} 21 | {% if section %}{% include "docstring/attributes.html.jinja" with context %}{% endif %} 22 | {% endwith %} 23 | {% endif %} 24 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/summary/functions.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Summary of functions/methods. -#} 2 | 3 | {% block logs scoped %} 4 | {#- Logging block. 5 | 6 | This block can be used to log debug messages, deprecation messages, warnings, etc. 7 | -#} 8 | {% endblock logs %} 9 | 10 | {% if not obj.docstring.parsed | selectattr("kind.value", "eq", "functions") | list %} 11 | {% with section = obj.functions 12 | |filter_objects( 13 | filters=config.filters, 14 | members_list=members_list, 15 | inherited_members=config.inherited_members, 16 | keep_no_docstrings=config.show_if_no_docstring, 17 | ) 18 | |order_members(config.members_order, members_list) 19 | |as_functions_section(check_public=not members_list) 20 | %} 21 | {% if section %}{% include "docstring/functions.html.jinja" with context %}{% endif %} 22 | {% endwith %} 23 | {% endif %} 24 | -------------------------------------------------------------------------------- /docs/.glossary.md: -------------------------------------------------------------------------------- 1 | [__all__]: https://docs.python.org/3/tutorial/modules.html#importing-from-a-package 2 | [class template]: https://github.com/mkdocstrings/python/blob/master/src/mkdocstrings_handlers/python/templates/material/_base/class.html 3 | [function template]: https://github.com/mkdocstrings/python/blob/master/src/mkdocstrings_handlers/python/templates/material/_base/function.html 4 | [autodoc syntax]: https://mkdocstrings.github.io/usage/#autodoc-syntax 5 | [autopages recipe]: https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages 6 | [Griffe]: https://github.com/mkdocstrings/griffe 7 | [ReadTheDocs Sphinx theme]: https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html 8 | [Spacy's documentation]: https://spacy.io/api/doc/ 9 | [Black]: https://pypi.org/project/black/ 10 | [Material for MkDocs]: https://squidfunk.github.io/mkdocs-material 11 | [Ruff]: https://docs.astral.sh/ruff 12 | 13 | *[ToC]: Table of Contents 14 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/summary/type_aliases.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Summary of type aliases. -#} 2 | 3 | {% block logs scoped %} 4 | {#- Logging block. 5 | 6 | This block can be used to log debug messages, deprecation messages, warnings, etc. 7 | -#} 8 | {% endblock logs %} 9 | 10 | {% if not obj.docstring.parsed | selectattr("kind.value", "eq", "type aliases") | list %} 11 | {% with section = obj.type_aliases 12 | |filter_objects( 13 | filters=config.filters, 14 | members_list=members_list, 15 | inherited_members=config.inherited_members, 16 | keep_no_docstrings=config.show_if_no_docstring, 17 | ) 18 | |order_members("alphabetical", members_list) 19 | |as_type_aliases_section(check_public=not members_list) 20 | %} 21 | {% if section %}{% include "docstring/type_aliases.html.jinja" with context %}{% endif %} 22 | {% endwith %} 23 | {% endif %} 24 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for object labels. 2 | 3 | Labels are additional information that can be displayed alongside an object. 4 | Example labels include "property", "writable" or "cached" for properties, 5 | "classmethod" or "staticmethod" for methods, etc. 6 | 7 | Context: 8 | labels (list): The list of labels to render. 9 | config (dict): The configuration options. 10 | -#} 11 | 12 | {% if config.show_labels and labels %} 13 | {% block logs scoped %} 14 | {#- Logging block. 15 | 16 | This block can be used to log debug messages, deprecation messages, warnings, etc. 17 | -#} 18 | {{ log.debug("Rendering labels") }} 19 | {% endblock logs %} 20 | 21 | {% for label in labels|sort %} 22 | {{ label }} 23 | {% endfor %} 24 | 25 | {% endif %} 26 | -------------------------------------------------------------------------------- /docs/usage/docstrings/google.md: -------------------------------------------------------------------------------- 1 | # Google style 2 | 3 | ## :warning: Work in Progress! 4 | 5 | ### Google-style admonitions 6 | 7 | With Google-style docstrings, any section that is not recognized will be transformed into its admonition equivalent. 8 | For example: 9 | 10 | === "Docstring" 11 | ```python 12 | """ 13 | Note: 14 | It looks like a section, but it will be rendered as an admonition. 15 | 16 | Tip: You can even choose a title. 17 | This admonition has a custom title! 18 | """ 19 | ``` 20 | 21 | === "Result" 22 | NOTE: It looks like a section, but it will be rendered as an admonition. 23 | 24 | TIP: **You can even choose a title.** 25 | This admonition has a custom title! 26 | 27 | See [Napoleon's documentation](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). 28 | See the supported docstring sections on [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/). 29 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/summary.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for auto-summaries. -#} 2 | 3 | {% block logs scoped %} 4 | {#- Logging block. 5 | 6 | This block can be used to log debug messages, deprecation messages, warnings, etc. 7 | -#} 8 | {% endblock logs %} 9 | 10 | {% with members_list = config.members if root_members else None %} 11 | {% if config.summary.modules %} 12 | {% include "summary/modules.html.jinja" with context %} 13 | {% endif %} 14 | 15 | {% if config.summary.type_aliases %} 16 | {% include "summary/type_aliases.html.jinja" with context %} 17 | {% endif %} 18 | 19 | {% if config.summary.classes %} 20 | {% include "summary/classes.html.jinja" with context %} 21 | {% endif %} 22 | 23 | {% if config.summary.functions %} 24 | {% include "summary/functions.html.jinja" with context %} 25 | {% endif %} 26 | 27 | {% if config.summary.attributes %} 28 | {% include "summary/attributes.html.jinja" with context %} 29 | {% endif %} 30 | {% endwith %} 31 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/zh.html.jinja: -------------------------------------------------------------------------------- 1 | 2 | {% block logs scoped %} 3 | {% endblock logs %} 4 | {% macro t(key) %}{{ { 5 | "ATTRIBUTE": "属性", 6 | "Attributes:": "属性：", 7 | "Classes:": "类：", 8 | "CLASS": "类", 9 | "DEFAULT:": "默认：", 10 | "Default": "默认", 11 | "default:": "默认：", 12 | "DESCRIPTION": "描述", 13 | "Description": "描述", 14 | "Examples:": "示例：", 15 | "Functions:": "函数：", 16 | "FUNCTION": "函数", 17 | "Methods:": "方法：", 18 | "METHOD": "方法", 19 | "Modules:": "模块：", 20 | "MODULE": "模块", 21 | "Name": "名称", 22 | "Other Parameters:": "其他参数：", 23 | "PARAMETER": "参数", 24 | "Parameters:": "参数：", 25 | "RAISES": "引发", 26 | "Raises:" : "引发：", 27 | "Receives:": "接收：", 28 | "RECEIVES": "接收", 29 | "required": "必需", 30 | "RETURNS": "返回", 31 | "Returns:": "返回：", 32 | "Source code in": "源代码位于：", 33 | "TYPE:": "类型：", 34 | "Type": "类型", 35 | "Warns:": "警告：", 36 | "WARNS": "警告", 37 | "YIELDS": "产生", 38 | "Yields:": "产生：", 39 | }[key] }}{% endmacro %} -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/ja.html.jinja: -------------------------------------------------------------------------------- 1 | 2 | {% block logs scoped %} 3 | {% endblock logs %} 4 | {% macro t(key) %}{{ { 5 | "ATTRIBUTE": "属性", 6 | "Attributes:": "属性：", 7 | "Classes:": "クラス：", 8 | "CLASS": "クラス", 9 | "DEFAULT:": "デフォルト：", 10 | "Default": "デフォルト", 11 | "default:": "デフォルト：", 12 | "DESCRIPTION": "デスクリプション", 13 | "Description": "デスクリプション", 14 | "Examples:": "例：", 15 | "Functions:": "関数：", 16 | "FUNCTION": "関数", 17 | "Methods:": "メソッド：", 18 | "METHOD": "メソッド", 19 | "Modules:": "モジュール：", 20 | "MODULE": "モジュール", 21 | "Name": "名前", 22 | "Other Parameters:": "他の引数：", 23 | "PARAMETER": "引数", 24 | "Parameters:": "引数：", 25 | "RAISES": "発生", 26 | "Raises:" : "発生：", 27 | "RECEIVES": "取得", 28 | "Receives:": "取得：", 29 | "required": "必須", 30 | "RETURNS": "戻り値", 31 | "Returns:": "戻り値：", 32 | "Source code in": "ソースコード位置：", 33 | "TYPE:": "タイプ：", 34 | "Type": "タイプ", 35 | "WARNS": "警告", 36 | "Warns:": "警告：", 37 | "YIELDS": "返す", 38 | "Yields:": "返す：", 39 | }[key] }}{% endmacro %} -------------------------------------------------------------------------------- /config/vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "files.watcherExclude": { 3 | "**/.venv*/**": true, 4 | "**/.venvs*/**": true, 5 | "**/venv*/**": true 6 | }, 7 | "mypy-type-checker.args": [ 8 | "--config-file=config/mypy.ini" 9 | ], 10 | "python.testing.unittestEnabled": false, 11 | "python.testing.pytestEnabled": true, 12 | "python.testing.pytestArgs": [ 13 | "--config-file=config/pytest.ini" 14 | ], 15 | "ruff.enable": true, 16 | "ruff.format.args": [ 17 | "--config=config/ruff.toml" 18 | ], 19 | "ruff.lint.args": [ 20 | "--config=config/ruff.toml" 21 | ], 22 | "yaml.schemas": { 23 | "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml" 24 | }, 25 | "yaml.customTags": [ 26 | "!ENV scalar", 27 | "!ENV sequence", 28 | "!relative scalar", 29 | "tag:yaml.org,2002:python/name:materialx.emoji.to_svg", 30 | "tag:yaml.org,2002:python/name:materialx.emoji.twemoji", 31 | "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format" 32 | ] 33 | } -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for "Examples" sections in docstrings. 2 | 3 | This template renders a list of documented examples. 4 | It alternates between rendering text and code examples. 5 | 6 | Context: 7 | section (griffe.DocstringSectionAttributes): The section to render. 8 | -#} 9 | 10 | {% block logs scoped %} 11 | {#- Logging block. 12 | 13 | This block can be used to log debug messages, deprecation messages, warnings, etc. 14 | -#} 15 | {{ log.debug("Rendering examples section") }} 16 | {% endblock logs %} 17 | 18 | {% import "language.html.jinja" as lang with context %} 19 | {#- Language module providing the `t` translation method. -#} 20 | 21 |

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

    22 | {% for section_type, sub_section in section.value %} 23 | {% if section_type.value == "text" %} 24 | {{ sub_section|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 25 | {% elif section_type.value == "examples" %} 26 | {{ sub_section|highlight(language="pycon") }} 27 | {% endif %} 28 | {% endfor %} 29 | -------------------------------------------------------------------------------- /tests/test_themes.py: -------------------------------------------------------------------------------- 1 | """Tests for the different themes we claim to support.""" 2 | 3 | from __future__ import annotations 4 | 5 | from typing import TYPE_CHECKING 6 | 7 | import pytest 8 | 9 | if TYPE_CHECKING: 10 | from mkdocstrings_handlers.python import PythonHandler 11 | 12 | 13 | @pytest.mark.parametrize( 14 | "plugin", 15 | [ 16 | {"theme": "mkdocs"}, 17 | {"theme": "readthedocs"}, 18 | {"theme": {"name": "material"}}, 19 | ], 20 | indirect=["plugin"], 21 | ) 22 | @pytest.mark.parametrize( 23 | "identifier", 24 | [ 25 | "mkdocstrings_handlers.python._internal.config", 26 | "mkdocstrings_handlers.python._internal.handler", 27 | "mkdocstrings_handlers.python._internal.rendering", 28 | ], 29 | ) 30 | def test_render_themes_templates_python(identifier: str, handler: PythonHandler) -> None: 31 | """Test rendering of a given theme's templates. 32 | 33 | Parameters: 34 | identifier: Parametrized identifier. 35 | handler: Python handler (fixture). 36 | """ 37 | options = handler.get_options({}) 38 | data = handler.collect(identifier, options) 39 | handler.render(data, options) 40 | -------------------------------------------------------------------------------- /scripts/get_version.py: -------------------------------------------------------------------------------- 1 | # Get current project version from Git tags or changelog. 2 | 3 | import re 4 | from contextlib import suppress 5 | from pathlib import Path 6 | 7 | from pdm.backend.hooks.version import ( # ty: ignore[unresolved-import] 8 | SCMVersion, 9 | Version, 10 | default_version_formatter, 11 | get_version_from_scm, 12 | ) 13 | 14 | _root = Path(__file__).parent.parent 15 | _changelog = _root / "CHANGELOG.md" 16 | _changelog_version_re = re.compile(r"^## \[(\d+\.\d+\.\d+)\].*$") 17 | _default_scm_version = SCMVersion(Version("0.0.0"), None, False, None, None) # noqa: FBT003 18 | 19 | 20 | def get_version() -> str: 21 | scm_version = get_version_from_scm(_root) or _default_scm_version 22 | if scm_version.version <= Version("0.1"): # Missing Git tags? 23 | with suppress(OSError, StopIteration): # noqa: SIM117 24 | with _changelog.open("r", encoding="utf8") as file: 25 | match = next(filter(None, map(_changelog_version_re.match, file))) 26 | scm_version = scm_version._replace(version=Version(match.group(1))) 27 | return default_version_formatter(scm_version) 28 | 29 | 30 | if __name__ == "__main__": 31 | print(get_version()) 32 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/en.html.jinja: -------------------------------------------------------------------------------- 1 | 2 | {% block logs scoped %} 3 | {% endblock logs %} 4 | {% macro t(key) %}{{ { 5 | "ATTRIBUTE": "ATTRIBUTE", 6 | "Attributes:": "Attributes:", 7 | "Classes:": "Classes:", 8 | "CLASS": "CLASS", 9 | "DEFAULT:": "DEFAULT:", 10 | "Default": "Default", 11 | "default:": "default:", 12 | "DESCRIPTION": "DESCRIPTION", 13 | "Description": "Description", 14 | "Examples:": "Examples:", 15 | "Functions:": "Functions:", 16 | "FUNCTION": "FUNCTION", 17 | "Methods:": "Methods:", 18 | "METHOD": "METHOD", 19 | "Modules:": "Modules:", 20 | "MODULE": "MODULE", 21 | "Name": "Name", 22 | "Other Parameters:": "Other Parameters:", 23 | "PARAMETER": "PARAMETER", 24 | "Parameters:": "Parameters:", 25 | "RAISES": "RAISES", 26 | "Raises:" : "Raises:", 27 | "RECEIVES": "RECEIVES", 28 | "Receives:": "Receives:", 29 | "required": "required", 30 | "RETURNS": "RETURNS", 31 | "Returns:": "Returns:", 32 | "Source code in": "Source code in", 33 | "TYPE:": "TYPE:", 34 | "Type": "Type", 35 | "WARNS": "WARNS", 36 | "Warns:": "Warns:", 37 | "YIELDS": "YIELDS", 38 | "Yields:": "Yields:", 39 | }[key] }}{% endmacro %} -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/style.css: -------------------------------------------------------------------------------- 1 | /* Avoid breaking parameters name, etc. in table cells. */ 2 | .doc-contents td code { 3 | word-break: normal !important; 4 | } 5 | 6 | /* No line break before first paragraph of descriptions. */ 7 | .doc-md-description, 8 | .doc-md-description>p:first-child { 9 | display: inline; 10 | } 11 | 12 | /* Avoid breaking code headings. */ 13 | .doc-heading code { 14 | white-space: normal; 15 | } 16 | 17 | /* Improve rendering of parameters, returns and exceptions. */ 18 | .doc-contents .field-name { 19 | min-width: 100px; 20 | } 21 | 22 | /* Other curious-spacing fixes. */ 23 | .doc-contents .field-name, 24 | .doc-contents .field-body { 25 | border: none !important; 26 | padding: 0 !important; 27 | } 28 | 29 | .doc-contents p { 30 | margin: 1em 0 1em; 31 | } 32 | 33 | .doc-contents .field-list { 34 | margin: 0 !important; 35 | } 36 | 37 | .doc-contents pre { 38 | padding: 0 !important; 39 | } 40 | 41 | .doc-contents .wy-table-responsive { 42 | margin-bottom: 0 !important; 43 | } 44 | 45 | .doc-contents td.code { 46 | padding: 0 !important; 47 | } 48 | 49 | .doc-contents td.linenos { 50 | padding: 0 8px !important; 51 | } 52 | 53 | .doc-children, 54 | footer { 55 | margin-top: 20px; 56 | } -------------------------------------------------------------------------------- /docs/snippets/package/generics.py: -------------------------------------------------------------------------------- 1 | """Some module showing generics. 2 | 3 | Type Aliases: 4 | SomeType: Some type alias. 5 | """ 6 | 7 | type SomeType[Z] = int | list[Z] 8 | """Some type alias. 9 | 10 | Type parameters: 11 | Z: Some type parameter. 12 | """ 13 | 14 | 15 | class MagicBag[T: (str, bytes) = str](list[T]): 16 | """A magic bag of items. 17 | 18 | Type parameters: 19 | T: Some type. 20 | """ 21 | 22 | def __init__[U: (int, bool)](self, *args: T, flag1: U | None = None, flag2: U | None = None) -> None: 23 | """Initialize bag. 24 | 25 | Type parameters: 26 | U: Some flag type. 27 | 28 | Parameters: 29 | flag1: Some flag. 30 | flag2: Some flag. 31 | """ 32 | super().__init__(args) 33 | self.flag1 = flag1 34 | self.flag2 = flag2 35 | 36 | def mutate[K](self, item: T, into: K) -> K: 37 | """Shake the bag to mutate an item into something else (and eject it). 38 | 39 | Type parameters: 40 | K: Some other type. 41 | 42 | Parameters: 43 | item: The item to mutate. 44 | into: Mutate the item into something like this. 45 | 46 | Returns: 47 | The mutated item. 48 | """ 49 | ... 50 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=(),inherited_members=(),members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |
    55 |
    56 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=None.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |
    55 |
    56 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=None.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |
    55 |
    56 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=(),inherited_members=False,members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |
    55 |
    56 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=(),inherited_members=True,members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |
    55 |
    56 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=None,inherited_members=(),members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |
    55 |
    56 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=None,inherited_members=True,members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |
    55 |
    56 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=None.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |
    55 |
    56 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=None,inherited_members=False,members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |
    55 |
    56 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=public,inherited_members=(),members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |
    55 |
    56 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=public,inherited_members=False,members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |
    55 |
    56 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=public,inherited_members=True,members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |
    55 |
    56 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=(),inherited_members=('method1',),members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 12 | 13 |
    14 |

    15 | 16 | members_package 17 | 18 |

    19 |
    20 |

    21 | Docstring for the package. 22 |

    23 |
    24 |
    25 |

    26 | 27 | 28 | module_attribute 29 | 30 | 31 | = 32 | 33 | 34 | 42 35 | 36 | 37 | 38 | 39 | 40 | module-attribute 41 | 42 | 43 | 44 |

    45 |
    46 |

    47 | Docstring for 48 | 49 | module_attribute 50 | 51 | . 52 |

    53 |
    54 |
    55 |
    56 |
    57 |
    58 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=None.html: -------------------------------------------------------------------------------- 1 | 12 | 13 |
    14 |

    15 | 16 | members_package 17 | 18 |

    19 |
    20 |

    21 | Docstring for the package. 22 |

    23 |
    24 |
    25 |

    26 | 27 | 28 | module_attribute 29 | 30 | 31 | = 32 | 33 | 34 | 42 35 | 36 | 37 | 38 | 39 | 40 | module-attribute 41 | 42 | 43 | 44 |

    45 |
    46 |

    47 | Docstring for 48 | 49 | module_attribute 50 | 51 | . 52 |

    53 |
    54 |
    55 |
    56 |
    57 |
    58 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=None,inherited_members=('method1',),members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 12 | 13 |
    14 |

    15 | 16 | members_package 17 | 18 |

    19 |
    20 |

    21 | Docstring for the package. 22 |

    23 |
    24 |
    25 |

    26 | 27 | 28 | module_attribute 29 | 30 | 31 | = 32 | 33 | 34 | 42 35 | 36 | 37 | 38 | 39 | 40 | module-attribute 41 | 42 | 43 | 44 |

    45 |
    46 |

    47 | Docstring for 48 | 49 | module_attribute 50 | 51 | . 52 |

    53 |
    54 |
    55 |
    56 |
    57 |
    58 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=public,inherited_members=('method1',),members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 12 | 13 |
    14 |

    15 | 16 | members_package 17 | 18 |

    19 |
    20 |

    21 | Docstring for the package. 22 |

    23 |
    24 |
    25 |

    26 | 27 | 28 | module_attribute 29 | 30 | 31 | = 32 | 33 | 34 | 42 35 | 36 | 37 | 38 | 39 | 40 | module-attribute 41 | 42 | 43 | 44 |

    45 |
    46 |

    47 | Docstring for 48 | 49 | module_attribute 50 | 51 | . 52 |

    53 |
    54 |
    55 |
    56 |
    57 |
    58 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 12 | 13 |
    14 |

    15 | 16 | members_package 17 | 18 |

    19 |
    20 |

    21 | Docstring for the package. 22 |

    23 |
    24 |
    25 |

    26 | 27 | 28 | module_attribute 29 | 30 | 31 | = 32 | 33 | 34 | 42 35 | 36 | 37 | 38 | 39 | 40 | module-attribute 41 | 42 | 43 | 44 |

    45 |
    46 |

    47 | Docstring for 48 | 49 | module_attribute 50 | 51 | . 52 |

    53 |
    54 |
    55 |
    56 |
    57 |
    58 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 12 | 13 |
    14 |

    15 | 16 | members_package 17 | 18 |

    19 |
    20 |

    21 | Docstring for the package. 22 |

    23 |
    24 |
    25 |

    26 | 27 | 28 | module_attribute 29 | 30 | 31 | = 32 | 33 | 34 | 42 35 | 36 | 37 | 38 | 39 | 40 | module-attribute 41 | 42 | 43 | 44 |

    45 |
    46 |

    47 | Docstring for 48 | 49 | module_attribute 50 | 51 | . 52 |

    53 |
    54 |
    55 |
    56 |
    57 |
    58 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 12 | 13 |
    14 |

    15 | 16 | members_package 17 | 18 |

    19 |
    20 |

    21 | Docstring for the package. 22 |

    23 |
    24 |
    25 |

    26 | 27 | 28 | module_attribute 29 | 30 | 31 | = 32 | 33 | 34 | 42 35 | 36 | 37 | 38 | 39 | 40 | module-attribute 41 | 42 | 43 | 44 |

    45 |
    46 |

    47 | Docstring for 48 | 49 | module_attribute 50 | 51 | . 52 |

    53 |
    54 |
    55 |
    56 |
    57 |
    58 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 12 | 13 |
    14 |

    15 | 16 | members_package 17 | 18 |

    19 |
    20 |

    21 | Docstring for the package. 22 |

    23 |
    24 |
    25 |

    26 | 27 | 28 | module_attribute 29 | 30 | 31 | = 32 | 33 | 34 | 42 35 | 36 | 37 | 38 | 39 | 40 | module-attribute 41 | 42 | 43 | 44 |

    45 |
    46 |

    47 | Docstring for 48 | 49 | module_attribute 50 | 51 | . 52 |

    53 |
    54 |
    55 |
    56 |
    57 |
    58 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 12 | 13 |
    14 |

    15 | 16 | members_package 17 | 18 |

    19 |
    20 |

    21 | Docstring for the package. 22 |

    23 |
    24 |
    25 |

    26 | 27 | 28 | module_attribute 29 | 30 | 31 | = 32 | 33 | 34 | 42 35 | 36 | 37 | 38 | 39 | 40 | module-attribute 41 | 42 | 43 | 44 |

    45 |
    46 |

    47 | Docstring for 48 | 49 | module_attribute 50 | 51 | . 52 |

    53 |
    54 |
    55 |
    56 |
    57 |
    58 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 12 | 13 |
    14 |

    15 | 16 | members_package 17 | 18 |

    19 |
    20 |

    21 | Docstring for the package. 22 |

    23 |
    24 |
    25 |

    26 | 27 | 28 | module_attribute 29 | 30 | 31 | = 32 | 33 | 34 | 42 35 | 36 | 37 | 38 | 39 | 40 | module-attribute 41 | 42 | 43 | 44 |

    45 |
    46 |

    47 | Docstring for 48 | 49 | module_attribute 50 | 51 | . 52 |

    53 |
    54 |
    55 |
    56 |
    57 |
    58 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 14 | 15 |
    16 |

    17 | 18 | members_package 19 | 20 |

    21 |
    22 |

    23 | Docstring for the package. 24 |

    25 |
    26 |
    27 |

    28 | 29 | 30 | module_attribute 31 | 32 | 33 | = 34 | 35 | 36 | 42 37 | 38 | 39 | 40 | 41 | 42 | module-attribute 43 | 44 | 45 | 46 |

    47 |
    48 |

    49 | Docstring for 50 | 51 | module_attribute 52 | 53 | . 54 |

    55 |
    56 |
    57 |
    58 |
    59 |
    60 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=('module_attribute',).html: -------------------------------------------------------------------------------- 1 | 14 | 15 |
    16 |

    17 | 18 | members_package 19 | 20 |

    21 |
    22 |

    23 | Docstring for the package. 24 |

    25 |
    26 |
    27 |

    28 | 29 | 30 | module_attribute 31 | 32 | 33 | = 34 | 35 | 36 | 42 37 | 38 | 39 | 40 | 41 | 42 | module-attribute 43 | 44 | 45 | 46 |

    47 |
    48 |

    49 | Docstring for 50 | 51 | module_attribute 52 | 53 | . 54 |

    55 |
    56 |
    57 |
    58 |
    59 |
    60 | -------------------------------------------------------------------------------- /docs/css/material.css: -------------------------------------------------------------------------------- 1 | /* More space at the bottom of the page. */ 2 | .md-main__inner { 3 | margin-bottom: 1.5rem; 4 | } 5 | 6 | /* Custom admonition: preview */ 7 | :root { 8 | --md-admonition-icon--preview: url('data:image/svg+xml;charset=utf-8,'); 9 | } 10 | 11 | .md-typeset .admonition.preview, 12 | .md-typeset details.preview { 13 | border-color: rgb(220, 139, 240); 14 | } 15 | 16 | .md-typeset .preview>.admonition-title, 17 | .md-typeset .preview>summary { 18 | background-color: rgba(142, 43, 155, 0.1); 19 | } 20 | 21 | .md-typeset .preview>.admonition-title::before, 22 | .md-typeset .preview>summary::before { 23 | background-color: rgb(220, 139, 240); 24 | -webkit-mask-image: var(--md-admonition-icon--preview); 25 | mask-image: var(--md-admonition-icon--preview); 26 | } 27 | -------------------------------------------------------------------------------- /scripts/griffe_extensions.py: -------------------------------------------------------------------------------- 1 | # Custom extensions for Griffe. 2 | 3 | from __future__ import annotations 4 | 5 | import ast 6 | from typing import Any 7 | 8 | import griffe 9 | 10 | _logger = griffe.get_logger("griffe_extensions") 11 | 12 | 13 | class CustomFields(griffe.Extension): 14 | """Support our custom dataclass fields.""" 15 | 16 | def on_attribute_instance( 17 | self, 18 | *, 19 | attr: griffe.Attribute, 20 | agent: griffe.Visitor | griffe.Inspector, 21 | **kwargs: Any, # noqa: ARG002 22 | ) -> None: 23 | """Fetch descriptions from `Field` annotations.""" 24 | if attr.docstring: 25 | return 26 | try: 27 | field: griffe.ExprCall = attr.annotation.slice.elements[1] # type: ignore[union-attr] 28 | except AttributeError: 29 | return 30 | 31 | if field.canonical_path == "mkdocstrings_handlers.python._internal.config._Field": 32 | description = next( 33 | attr.value 34 | for attr in field.arguments 35 | if isinstance(attr, griffe.ExprKeyword) and attr.name == "description" 36 | ) 37 | if not isinstance(description, str): 38 | _logger.warning(f"Field description of {attr.path} is not a static string") 39 | description = str(description) 40 | 41 | attr.docstring = griffe.Docstring( 42 | ast.literal_eval(description), 43 | parent=attr, 44 | parser=agent.docstring_parser, 45 | parser_options=agent.docstring_options, 46 | ) 47 | -------------------------------------------------------------------------------- /config/vscode/launch.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": "0.2.0", 3 | "configurations": [ 4 | { 5 | "name": "python (current file)", 6 | "type": "debugpy", 7 | "request": "launch", 8 | "program": "${file}", 9 | "console": "integratedTerminal", 10 | "justMyCode": false, 11 | "args": "${command:pickArgs}" 12 | }, 13 | { 14 | "name": "run", 15 | "type": "debugpy", 16 | "request": "launch", 17 | "module": "python", 18 | "console": "integratedTerminal", 19 | "justMyCode": false, 20 | "args": "${command:pickArgs}" 21 | }, 22 | { 23 | "name": "docs", 24 | "type": "debugpy", 25 | "request": "launch", 26 | "module": "mkdocs", 27 | "justMyCode": false, 28 | "args": [ 29 | "serve", 30 | "-v" 31 | ] 32 | }, 33 | { 34 | "name": "test", 35 | "type": "debugpy", 36 | "request": "launch", 37 | "module": "pytest", 38 | "justMyCode": false, 39 | "args": [ 40 | "-c=config/pytest.ini", 41 | "-vvv", 42 | "--no-cov", 43 | "--dist=no", 44 | "tests", 45 | "-k=${input:tests_selection}" 46 | ] 47 | } 48 | ], 49 | "inputs": [ 50 | { 51 | "id": "tests_selection", 52 | "type": "promptString", 53 | "description": "Tests selection", 54 | "default": "" 55 | } 56 | ] 57 | } -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for "Warns" sections in docstrings. 2 | 3 | This template renders a list of documented warnings in the format 4 | specified with the [`docstring_section_style`][] configuration option. 5 | 6 | Context: 7 | section (griffe.DocstringSectionAttributes): The section to render. 8 | -#} 9 | 10 | {% block logs scoped %} 11 | {#- Logging block. 12 | 13 | This block can be used to log debug messages, deprecation messages, warnings, etc. 14 | -#} 15 | {{ log.debug() }} 16 | {% endblock %} 17 | 18 | {% import "language.html.jinja" as lang with context %} 19 | {#- Language module providing the `t` translation method. -#} 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 46 | 47 | 48 |
    {{ section.title or lang.t("Warns:") }} 30 |
      31 | {% for warns in section.value %} 32 |
    • 33 | {% if warns.annotation %} 34 | {% with expression = warns.annotation, backlink_type = "emitted-by" %} 35 | {% include "expression.html.jinja" with context %} 36 | {% endwith %} 37 | {% endif %} 38 | – 39 |
      40 | {{ warns.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 41 |
      42 |
      • 43 | {% endfor %} 44 |
    45 |
    49 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for "Raises" sections in docstrings. 2 | 3 | This template renders a list of documented exceptions in the format 4 | specified with the [`docstring_section_style`][] configuration option. 5 | 6 | Context: 7 | section (griffe.DocstringSectionAttributes): The section to render. 8 | -#} 9 | 10 | {% block logs scoped %} 11 | {#- Logging block. 12 | 13 | This block can be used to log debug messages, deprecation messages, warnings, etc. 14 | -#} 15 | {{ log.debug() }} 16 | {% endblock %} 17 | 18 | {% import "language.html.jinja" as lang with context %} 19 | {#- Language module providing the `t` translation method. -#} 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 46 | 47 | 48 |
    {{ section.title or lang.t("Raises:") }} 30 |
      31 | {% for raises in section.value %} 32 |
    • 33 | {% if raises.annotation %} 34 | {% with expression = raises.annotation, backlink_type = "raised-by" %} 35 | {% include "expression.html.jinja" with context %} 36 | {% endwith %} 37 | {% endif %} 38 | – 39 |
      40 | {{ raises.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 41 |
      42 |
      • 43 | {% endfor %} 44 |
    45 |
    49 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Macro for Chinese translations. -#} 2 | 3 | {% block logs scoped %} 4 | {#- Logging block. 5 | 6 | This block can be used to log debug messages, deprecation messages, warnings, etc. 7 | -#} 8 | {% endblock logs %} 9 | 10 | {% macro t(key) %}{{ { 11 | "ATTRIBUTE": "属性", 12 | "Attributes": "属性", 13 | "Attributes:": "属性：", 14 | "BOUND:": "边界：", 15 | "Bound or Constraints": "边界或约束", 16 | "Classes": "类", 17 | "Classes:": "类：", 18 | "Class Type Parameters:": "Class Type Parameters:", 19 | "CLASS TYPE PARAMETER": "CLASS TYPE PARAMETER", 20 | "CLASS": "类", 21 | "CONSTRAINTS:": "约束：", 22 | "DEFAULT:": "默认：", 23 | "Default": "默认", 24 | "default:": "默认：", 25 | "DESCRIPTION": "描述", 26 | "Description": "描述", 27 | "Examples:": "示例：", 28 | "Functions": "函数", 29 | "Functions:": "函数：", 30 | "FUNCTION": "函数", 31 | "Init Type Parameters:": "Init Type Parameters:", 32 | "INIT TYPE PARAMETER": "INIT TYPE PARAMETER", 33 | "Methods:": "方法：", 34 | "METHOD": "方法", 35 | "Modules": "模块", 36 | "Modules:": "模块：", 37 | "MODULE": "模块", 38 | "Name": "名称", 39 | "Other Parameters:": "其他参数：", 40 | "PARAMETER": "参数", 41 | "Parameters:": "参数：", 42 | "RAISES": "引发", 43 | "Raises:" : "引发：", 44 | "Receives:": "接收：", 45 | "RECEIVES": "接收", 46 | "required": "必需", 47 | "RETURNS": "返回", 48 | "Returns:": "返回：", 49 | "Source code in": "源代码位于：", 50 | "TYPE:": "类型：", 51 | "Type": "类型", 52 | "Type Aliases": "类型别名", 53 | "Type Aliases:": "类型别名：", 54 | "TYPE ALIAS": "类型别名", 55 | "Type Parameters:": "类型形参：", 56 | "TYPE PARAMETER": "类型形参", 57 | "Warns:": "警告：", 58 | "WARNS": "警告", 59 | "YIELDS": "产生", 60 | "Yields:": "产生：", 61 | }[key] }}{% endmacro %} 62 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/1-bug.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a bug report to help us improve. 4 | title: "bug: " 5 | labels: unconfirmed 6 | assignees: [pawamoy] 7 | --- 8 | 9 | ### Description of the bug 10 | 11 | 12 | ### To Reproduce 13 | 28 | 29 | ``` 30 | WRITE MRE / INSTRUCTIONS HERE 31 | ``` 32 | 33 | ### Full traceback 34 | 36 | 37 |
    Full traceback 38 | 39 | ```python 40 | PASTE TRACEBACK HERE 41 | ``` 42 | 43 |
    44 | 45 | ### Expected behavior 46 | 47 | 48 | ### Environment information 49 | 51 | 52 | ```bash 53 | python -m mkdocstrings_handlers.python._internal.debug # | xclip -selection clipboard 54 | ``` 55 | 56 | PASTE MARKDOWN OUTPUT HERE 57 | 58 | ### Additional context 59 | 62 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for "Attributes" sections in docstrings. 2 | 3 | This template renders a list of documented attributes in the format 4 | specified with the [`docstring_section_style`][] configuration option. 5 | 6 | Context: 7 | section (griffe.DocstringSectionAttributes): The section to render. 8 | -#} 9 | 10 | {% block logs scoped %} 11 | {#- Logging block. 12 | 13 | This block can be used to log debug messages, deprecation messages, warnings, etc. 14 | -#} 15 | {{ log.debug() }} 16 | {% endblock %} 17 | 18 | {% import "language.html.jinja" as lang with context %} 19 | {#- Language module providing the `t` translation method. -#} 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 47 | 48 | 49 |
    {{ section.title or lang.t("Attributes:") }} 30 |
      31 | {% for attribute in section.value %} 32 |
    • 33 | {{ attribute.name }} 34 | {% if attribute.annotation %} 35 | {% with expression = attribute.annotation %} 36 | ({% include "expression.html.jinja" with context %}) 37 | {% endwith %} 38 | {% endif %} 39 | – 40 |
      41 | {{ attribute.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 42 |
      43 |
      • 44 | {% endfor %} 45 |
    46 |
    50 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Macro for Japanese translations. -#} 2 | 3 | {% block logs scoped %} 4 | {#- Logging block. 5 | 6 | This block can be used to log debug messages, deprecation messages, warnings, etc. 7 | -#} 8 | {% endblock logs %} 9 | 10 | {% macro t(key) %}{{ { 11 | "ATTRIBUTE": "属性", 12 | "Attributes": "属性", 13 | "Attributes:": "属性：", 14 | "BOUND:": "境界：", 15 | "Bound or Constraints": "境界や制約", 16 | "Classes": "クラス", 17 | "Classes:": "クラス：", 18 | "Class Type Parameters:": "Class Type Parameters:", 19 | "CLASS TYPE PARAMETER": "CLASS TYPE PARAMETER", 20 | "CLASS": "クラス", 21 | "CONSTRAINTS:": "制約：", 22 | "DEFAULT:": "デフォルト：", 23 | "Default": "デフォルト", 24 | "default:": "デフォルト：", 25 | "DESCRIPTION": "デスクリプション", 26 | "Description": "デスクリプション", 27 | "Examples:": "例：", 28 | "Functions": "関数", 29 | "Functions:": "関数：", 30 | "FUNCTION": "関数", 31 | "Init Type Parameters:": "Init Type Parameters:", 32 | "INIT TYPE PARAMETER": "INIT TYPE PARAMETER", 33 | "Methods:": "メソッド：", 34 | "METHOD": "メソッド", 35 | "Modules": "モジュール", 36 | "Modules:": "モジュール：", 37 | "MODULE": "モジュール", 38 | "Name": "名前", 39 | "Other Parameters:": "他の引数：", 40 | "PARAMETER": "引数", 41 | "Parameters:": "引数：", 42 | "RAISES": "発生", 43 | "Raises:" : "発生：", 44 | "RECEIVES": "取得", 45 | "Receives:": "取得：", 46 | "required": "必須", 47 | "RETURNS": "戻り値", 48 | "Returns:": "戻り値：", 49 | "Source code in": "ソースコード位置：", 50 | "TYPE:": "タイプ：", 51 | "Type": "タイプ", 52 | "Type Aliases": "型エイリアス", 53 | "Type Aliases:": "型エイリアス：", 54 | "TYPE ALIAS": "型エイリアス", 55 | "Type Parameters:": "型パラメータ：", 56 | "TYPE PARAMETER": "型パラメータ", 57 | "WARNS": "警告", 58 | "Warns:": "警告：", 59 | "YIELDS": "返す", 60 | "Yields:": "返す：", 61 | }[key] }}{% endmacro %} 62 | -------------------------------------------------------------------------------- /scripts/mkdocs_hooks.py: -------------------------------------------------------------------------------- 1 | # Generate a JSON schema of the Python handler configuration. 2 | 3 | import json 4 | from dataclasses import dataclass, fields 5 | from os.path import join 6 | from typing import Any 7 | 8 | from mkdocs.config.defaults import MkDocsConfig 9 | from mkdocs.plugins import get_plugin_logger 10 | 11 | from mkdocstrings_handlers.python import PythonInputConfig, PythonInputOptions 12 | 13 | # TODO: Update when Pydantic supports Python 3.14 (sources and duties as well). 14 | try: 15 | from pydantic import TypeAdapter 16 | except ImportError: 17 | TypeAdapter = None # type: ignore[assignment,misc] 18 | 19 | 20 | _logger = get_plugin_logger(__name__) 21 | 22 | 23 | def on_post_build(config: MkDocsConfig, **kwargs: Any) -> None: # noqa: ARG001 24 | """Write `schema.json` to the site directory.""" 25 | if TypeAdapter is None: 26 | _logger.info("Pydantic is not installed, skipping JSON schema generation") 27 | return 28 | 29 | @dataclass 30 | class PythonHandlerSchema: 31 | python: PythonInputConfig 32 | 33 | adapter = TypeAdapter(PythonHandlerSchema) 34 | schema = adapter.json_schema() 35 | schema["$schema"] = "https://json-schema.org/draft-07/schema" 36 | with open(join(config.site_dir, "schema.json"), "w") as file: 37 | json.dump(schema, file, indent=2) 38 | _logger.debug("Generated JSON schema") 39 | 40 | autorefs = config["plugins"]["autorefs"] 41 | for field in fields(PythonInputConfig): 42 | if f"setting-{field.name}" not in autorefs._primary_url_map: 43 | _logger.warning(f"Handler setting `{field.name}` is not documented") 44 | for field in fields(PythonInputOptions): 45 | if f"option-{field.name}" not in autorefs._primary_url_map: 46 | _logger.warning(f"Configuration option `{field.name}` is not documented") 47 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for "Other parameters" sections in docstrings. 2 | 3 | This template renders a list of documented other parameters in the format 4 | specified with the [`docstring_section_style`][] configuration option. 5 | 6 | Context: 7 | section (griffe.DocstringSectionAttributes): The section to render. 8 | -#} 9 | 10 | {% block logs scoped %} 11 | {#- Logging block. 12 | 13 | This block can be used to log debug messages, deprecation messages, warnings, etc. 14 | -#} 15 | {{ log.debug() }} 16 | {% endblock %} 17 | 18 | {% import "language.html.jinja" as lang with context %} 19 | {#- Language module providing the `t` translation method. -#} 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 47 | 48 | 49 |
    {{ section.title or lang.t("Other parameters:") }} 30 |
      31 | {% for parameter in section.value %} 32 |
    • 33 | {{ parameter.name }} 34 | {% if parameter.annotation %} 35 | {% with expression = parameter.annotation, backlink_type = "used-by" %} 36 | ({% include "expression.html.jinja" with context %}) 37 | {% endwith %} 38 | {% endif %} 39 | – 40 |
      41 | {{ parameter.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 42 |
      43 |
      • 44 | {% endfor %} 45 |
    46 |
    50 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for "Returns" sections in docstrings. 2 | 3 | This template renders a list of documented returned values in the format 4 | specified with the [`docstring_section_style`][] configuration option. 5 | 6 | Context: 7 | section (griffe.DocstringSectionAttributes): The section to render. 8 | -#} 9 | 10 | {% block logs scoped %} 11 | {#- Logging block. 12 | 13 | This block can be used to log debug messages, deprecation messages, warnings, etc. 14 | -#} 15 | {{ log.debug() }} 16 | {% endblock %} 17 | 18 | {% import "language.html.jinja" as lang with context %} 19 | {#- Language module providing the `t` translation method. -#} 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 49 | 50 | 51 |
    {{ section.title or lang.t("Returns:") }} 30 |
      31 | {% for returns in section.value %} 32 |
    • 33 | {% if returns.name %}{{ returns.name }}{% endif %} 34 | {% if returns.annotation %} 35 | {% with expression = returns.annotation, backlink_type = "returned-by" %} 36 | {% if returns.name %}({% endif %} 37 | {% include "expression.html.jinja" with context %} 38 | {% if returns.name %}){% endif %} 39 | {% endwith %} 40 | {% endif %} 41 | – 42 |
      43 | {{ returns.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 44 |
      45 |
      • 46 | {% endfor %} 47 |
    48 |
    52 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for "Yields" sections in docstrings. 2 | 3 | This template renders a list of documented yielded values (generators) in the format 4 | specified with the [`docstring_section_style`][] configuration option. 5 | 6 | Context: 7 | section (griffe.DocstringSectionAttributes): The section to render. 8 | -#} 9 | 10 | {% block logs scoped %} 11 | {#- Logging block. 12 | 13 | This block can be used to log debug messages, deprecation messages, warnings, etc. 14 | -#} 15 | {{ log.debug() }} 16 | {% endblock %} 17 | 18 | {% import "language.html.jinja" as lang with context %} 19 | {#- Language module providing the `t` translation method. -#} 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 49 | 50 | 51 |
    {{ section.title or lang.t("Yields:") }} 30 |
      31 | {% for yields in section.value %} 32 |
    • 33 | {% if yields.name %}{{ yields.name }}{% endif %} 34 | {% if yields.annotation %} 35 | {% with expression = yields.annotation, backlink_type = "yielded-by" %} 36 | {% if yields.name %}({% endif %} 37 | {% include "expression.html.jinja" with context %} 38 | {% if yields.name %}){% endif %} 39 | {% endwith %} 40 | {% endif %} 41 | – 42 |
      43 | {{ yields.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 44 |
      45 |
      • 46 | {% endfor %} 47 |
    48 |
    52 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/__init__.py: -------------------------------------------------------------------------------- 1 | """Python handler for mkdocstrings.""" 2 | 3 | from mkdocstrings_handlers.python._internal.config import ( 4 | AutoStyleOptions, 5 | GoogleStyleOptions, 6 | Inventory, 7 | NumpyStyleOptions, 8 | PerStyleOptions, 9 | PythonConfig, 10 | PythonInputConfig, 11 | PythonInputOptions, 12 | PythonOptions, 13 | SphinxStyleOptions, 14 | SummaryOption, 15 | ) 16 | from mkdocstrings_handlers.python._internal.handler import PythonHandler, get_handler 17 | from mkdocstrings_handlers.python._internal.rendering import ( 18 | AutorefsHook, 19 | Order, 20 | Tree, 21 | do_as_attributes_section, 22 | do_as_classes_section, 23 | do_as_functions_section, 24 | do_as_modules_section, 25 | do_as_type_aliases_section, 26 | do_backlink_tree, 27 | do_filter_objects, 28 | do_format_attribute, 29 | do_format_code, 30 | do_format_signature, 31 | do_format_type_alias, 32 | do_get_template, 33 | do_order_members, 34 | do_split_path, 35 | do_stash_crossref, 36 | ) 37 | 38 | __all__ = [ 39 | "AutoStyleOptions", 40 | "AutorefsHook", 41 | "GoogleStyleOptions", 42 | "Inventory", 43 | "NumpyStyleOptions", 44 | "Order", 45 | "PerStyleOptions", 46 | "PythonConfig", 47 | "PythonHandler", 48 | "PythonInputConfig", 49 | "PythonInputOptions", 50 | "PythonOptions", 51 | "SphinxStyleOptions", 52 | "SummaryOption", 53 | "Tree", 54 | "do_as_attributes_section", 55 | "do_as_classes_section", 56 | "do_as_functions_section", 57 | "do_as_modules_section", 58 | "do_as_type_aliases_section", 59 | "do_backlink_tree", 60 | "do_filter_objects", 61 | "do_format_attribute", 62 | "do_format_code", 63 | "do_format_signature", 64 | "do_format_type_alias", 65 | "do_get_template", 66 | "do_order_members", 67 | "do_split_path", 68 | "do_stash_crossref", 69 | "get_handler", 70 | ] 71 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for "Receives" sections in docstrings. 2 | 3 | This template renders a list of documented received values (generators) in the format 4 | specified with the [`docstring_section_style`][] configuration option. 5 | 6 | Context: 7 | section (griffe.DocstringSectionAttributes): The section to render. 8 | -#} 9 | 10 | {% block logs scoped %} 11 | {#- Logging block. 12 | 13 | This block can be used to log debug messages, deprecation messages, warnings, etc. 14 | -#} 15 | {{ log.debug() }} 16 | {% endblock %} 17 | 18 | {% import "language.html.jinja" as lang with context %} 19 | {#- Language module providing the `t` translation method. -#} 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 49 | 50 | 51 |
    {{ section.title or lang.t("Receives:") }} 30 |
      31 | {% for receives in section.value %} 32 |
    • 33 | {% if receives.name %}{{ receives.name }}{% endif %} 34 | {% if receives.annotation %} 35 | {% with expression = receives.annotation, backlink_type = "received-by" %} 36 | {% if receives.name %}({% endif %} 37 | {% include "expression.html.jinja" with context %} 38 | {% if receives.name %}){% endif %} 39 | {% endwith %} 40 | {% endif %} 41 | – 42 |
      43 | {{ receives.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 44 |
      45 |
      • 46 | {% endfor %} 47 |
    48 |
    52 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Macro for English translations. -#} 2 | 3 | {% block logs scoped %} 4 | {#- Logging block. 5 | 6 | This block can be used to log debug messages, deprecation messages, warnings, etc. 7 | -#} 8 | {% endblock logs %} 9 | 10 | {% macro t(key) %}{{ { 11 | "ATTRIBUTE": "ATTRIBUTE", 12 | "Attributes": "Attributes", 13 | "Attributes:": "Attributes:", 14 | "BOUND:": "BOUND:", 15 | "Bound or Constraints": "Bound or Constraints", 16 | "Classes": "Classes", 17 | "Classes:": "Classes:", 18 | "Class Type Parameters:": "Class Type Parameters:", 19 | "CLASS TYPE PARAMETER": "CLASS TYPE PARAMETER", 20 | "CLASS": "CLASS", 21 | "CONSTRAINTS:": "CONSTRAINTS:", 22 | "DEFAULT:": "DEFAULT:", 23 | "Default": "Default", 24 | "default:": "default:", 25 | "DESCRIPTION": "DESCRIPTION", 26 | "Description": "Description", 27 | "Examples:": "Examples:", 28 | "Functions": "Functions", 29 | "Functions:": "Functions:", 30 | "FUNCTION": "FUNCTION", 31 | "Init Type Parameters:": "Init Type Parameters:", 32 | "INIT TYPE PARAMETER": "INIT TYPE PARAMETER", 33 | "Methods:": "Methods:", 34 | "METHOD": "METHOD", 35 | "Modules": "Modules", 36 | "Modules:": "Modules:", 37 | "MODULE": "MODULE", 38 | "Name": "Name", 39 | "Other Parameters:": "Other Parameters:", 40 | "PARAMETER": "PARAMETER", 41 | "Parameters:": "Parameters:", 42 | "RAISES": "RAISES", 43 | "Raises:" : "Raises:", 44 | "RECEIVES": "RECEIVES", 45 | "Receives:": "Receives:", 46 | "required": "required", 47 | "RETURNS": "RETURNS", 48 | "Returns:": "Returns:", 49 | "Source code in": "Source code in", 50 | "TYPE:": "TYPE:", 51 | "Type": "Type", 52 | "Type Aliases": "Type Aliases", 53 | "Type Aliases:": "Type Aliases:", 54 | "TYPE ALIAS": "TYPE ALIAS", 55 | "Type Parameters:": "Type Parameters:", 56 | "TYPE PARAMETER": "TYPE PARAMETER", 57 | "WARNS": "WARNS", 58 | "Warns:": "Warns:", 59 | "YIELDS": "YIELDS", 60 | "Yields:": "Yields:", 61 | }[key] }}{% endmacro %} 62 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for "Parameters" sections in docstrings. 2 | 3 | This template renders a list of documented parameters in the format 4 | specified with the [`docstring_section_style`][] configuration option. 5 | 6 | Context: 7 | section (griffe.DocstringSectionAttributes): The section to render. 8 | -#} 9 | 10 | {% block logs scoped %} 11 | {#- Logging block. 12 | 13 | This block can be used to log debug messages, deprecation messages, warnings, etc. 14 | -#} 15 | {{ log.debug() }} 16 | {% endblock %} 17 | 18 | {% import "language.html.jinja" as lang with context %} 19 | {#- Language module providing the `t` translation method. -#} 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 52 | 53 | 54 |
    {{ section.title or lang.t("Parameters:") }} 30 |
      31 | {% for parameter in section.value %} 32 |
    • 33 | {{ parameter.name }} 34 | {% if parameter.annotation %} 35 | {% with expression = parameter.annotation, backlink_type = "used-by" %} 36 | ({% include "expression.html.jinja" with context %} 37 | {%- if parameter.default %}, {{ lang.t("default:") }} 38 | {% with expression = parameter.default, backlink_type = "used-by" %} 39 | {% include "expression.html.jinja" with context %} 40 | {% endwith %} 41 | {% endif %}) 42 | {% endwith %} 43 | {% endif %} 44 | – 45 |
      46 | {{ parameter.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 47 |
      48 |
      • 49 | {% endfor %} 50 |
    51 |
    55 | -------------------------------------------------------------------------------- /docs/.overrides/partials/comments.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/backlinks.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for backlinks. 2 | 3 | This template renders backlinks. 4 | 5 | Context: 6 | backlinks (Mapping[str, Iterable[str]]): The backlinks to render. 7 | config (dict): The configuration options. 8 | verbose_type (Mapping[str, str]): The verbose backlink types. 9 | default_crumb (BacklinkCrumb): A default, empty crumb. 10 | -#} 11 | 12 | {% block logs scoped %} 13 | {#- Logging block. 14 | 15 | This block can be used to log debug messages, deprecation messages, warnings, etc. 16 | -#} 17 | {% endblock logs %} 18 | 19 | {% macro render_crumb(crumb, last=false) %} 20 | 21 | {% if crumb.url and crumb.title %} 22 | {{ crumb.title | safe }} 23 | {% elif crumb.title %} 24 | {{ crumb.title | safe }} 25 | {% endif %} 26 | 27 | {% endmacro %} 28 | 29 | {% macro render_tree(tree) %} 30 | 42 | {% endmacro %} 43 | 44 | {% if config.backlinks %} 45 |
    46 | {% if config.backlinks == "tree" %} 47 | {% for backlink_type, backlink_list in backlinks | dictsort %} 48 | {{ verbose_type[backlink_type] }}: 49 | {{ render_tree(backlink_list|backlink_tree) }} 50 | {% endfor %} 51 | {% elif config.backlinks == "flat" %} 52 | {% for backlink_type, backlink_list in backlinks | dictsort %} 53 | {{ verbose_type[backlink_type] }}: 54 | 63 | {% endfor %} 64 | {% endif %} 65 |
    66 | {% endif %} 67 | -------------------------------------------------------------------------------- /config/ruff.toml: -------------------------------------------------------------------------------- 1 | target-version = "py39" 2 | line-length = 120 3 | 4 | [lint] 5 | exclude = [ 6 | "tests/fixtures/*.py", 7 | ] 8 | select = [ 9 | "A", "ANN", "ARG", 10 | "B", "BLE", 11 | "C", "C4", 12 | "COM", 13 | "D", "DTZ", 14 | "E", "ERA", "EXE", 15 | "F", "FBT", 16 | "G", 17 | "I", "ICN", "INP", "ISC", 18 | "N", 19 | "PGH", "PIE", "PL", "PLC", "PLE", "PLR", "PLW", "PT", "PYI", 20 | "Q", 21 | "RUF", "RSE", "RET", 22 | "S", "SIM", "SLF", 23 | "T", "T10", "T20", "TCH", "TID", "TRY", 24 | "UP", 25 | "W", 26 | "YTT", 27 | ] 28 | ignore = [ 29 | "A001", # Variable is shadowing a Python builtin 30 | "ANN101", # Missing type annotation for self 31 | "ANN102", # Missing type annotation for cls 32 | "ANN204", # Missing return type annotation for special method __str__ 33 | "ANN401", # Dynamically typed expressions (typing.Any) are disallowed 34 | "ARG005", # Unused lambda argument 35 | "C901", # Too complex 36 | "D105", # Missing docstring in magic method 37 | "D417", # Missing argument description in the docstring 38 | "E501", # Line too long 39 | "ERA001", # Commented out code 40 | "G004", # Logging statement uses f-string 41 | "PLR0911", # Too many return statements 42 | "PLR0912", # Too many branches 43 | "PLR0913", # Too many arguments to function call 44 | "PLR0915", # Too many statements 45 | "SLF001", # Private member accessed 46 | "TRY003", # Avoid specifying long messages outside the exception class 47 | ] 48 | 49 | [lint.per-file-ignores] 50 | "src/**/cli.py" = [ 51 | "T201", # Print statement 52 | ] 53 | "src/*/debug.py" = [ 54 | "T201", # Print statement 55 | ] 56 | "!src/*/*.py" = [ 57 | "D100", # Missing docstring in public module 58 | ] 59 | "!src/**.py" = [ 60 | "D101", # Missing docstring in public class 61 | "D103", # Missing docstring in public function 62 | ] 63 | "scripts/*.py" = [ 64 | "INP001", # File is part of an implicit namespace package 65 | "T201", # Print statement 66 | ] 67 | "tests/**.py" = [ 68 | "ARG005", # Unused lambda argument 69 | "FBT001", # Boolean positional arg in function definition 70 | "PLR2004", # Magic value used in comparison 71 | "S101", # Use of assert detected 72 | ] 73 | 74 | [lint.flake8-quotes] 75 | docstring-quotes = "double" 76 | 77 | [lint.flake8-tidy-imports] 78 | ban-relative-imports = "all" 79 | 80 | [lint.isort] 81 | known-first-party = ["mkdocstrings_handlers.python"] 82 | 83 | [lint.pydocstyle] 84 | convention = "google" 85 | 86 | [format] 87 | exclude = [ 88 | "tests/fixtures/*.py", 89 | ] 90 | docstring-code-format = true 91 | docstring-code-line-length = 80 92 | -------------------------------------------------------------------------------- /docs/css/mkdocstrings.css: -------------------------------------------------------------------------------- 1 | /* Indentation. */ 2 | div.doc-contents:not(.first) { 3 | padding-left: 25px; 4 | border-left: .05rem solid var(--md-typeset-table-color); 5 | } 6 | 7 | /* Mark external links as such. */ 8 | a.external::after, 9 | a.autorefs-external::after { 10 | /* https://primer.style/octicons/arrow-up-right-24 */ 11 | mask-image: url('data:image/svg+xml,'); 12 | -webkit-mask-image: url('data:image/svg+xml,'); 13 | content: ' '; 14 | 15 | display: inline-block; 16 | vertical-align: middle; 17 | position: relative; 18 | 19 | height: 1em; 20 | width: 1em; 21 | background-color: currentColor; 22 | } 23 | 24 | a.external:hover::after, 25 | a.autorefs-external:hover::after { 26 | background-color: var(--md-accent-fg-color); 27 | } 28 | 29 | /* Tree-like output for backlinks. */ 30 | .doc-backlink-list { 31 | --tree-clr: var(--md-default-fg-color); 32 | --tree-font-size: 1rem; 33 | --tree-item-height: 1; 34 | --tree-offset: 1rem; 35 | --tree-thickness: 1px; 36 | --tree-style: solid; 37 | display: grid; 38 | list-style: none !important; 39 | } 40 | 41 | .doc-backlink-list li > span:first-child { 42 | text-indent: .3rem; 43 | } 44 | .doc-backlink-list li { 45 | padding-inline-start: var(--tree-offset); 46 | border-left: var(--tree-thickness) var(--tree-style) var(--tree-clr); 47 | position: relative; 48 | margin-left: 0 !important; 49 | 50 | &:last-child { 51 | border-color: transparent; 52 | } 53 | &::before{ 54 | content: ''; 55 | position: absolute; 56 | top: calc(var(--tree-item-height) / 2 * -1 * var(--tree-font-size) + var(--tree-thickness)); 57 | left: calc(var(--tree-thickness) * -1); 58 | width: calc(var(--tree-offset) + var(--tree-thickness) * 2); 59 | height: calc(var(--tree-item-height) * var(--tree-font-size)); 60 | border-left: var(--tree-thickness) var(--tree-style) var(--tree-clr); 61 | border-bottom: var(--tree-thickness) var(--tree-style) var(--tree-clr); 62 | } 63 | &::after{ 64 | content: ''; 65 | position: absolute; 66 | border-radius: 50%; 67 | background-color: var(--tree-clr); 68 | top: calc(var(--tree-item-height) / 2 * 1rem); 69 | left: var(--tree-offset) ; 70 | translate: calc(var(--tree-thickness) * -1) calc(var(--tree-thickness) * -1); 71 | } 72 | } 73 | -------------------------------------------------------------------------------- /config/vscode/tasks.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": "2.0.0", 3 | "tasks": [ 4 | { 5 | "label": "changelog", 6 | "type": "process", 7 | "command": "scripts/make", 8 | "args": ["changelog"] 9 | }, 10 | { 11 | "label": "check", 12 | "type": "process", 13 | "command": "scripts/make", 14 | "args": ["check"] 15 | }, 16 | { 17 | "label": "check-quality", 18 | "type": "process", 19 | "command": "scripts/make", 20 | "args": ["check-quality"] 21 | }, 22 | { 23 | "label": "check-types", 24 | "type": "process", 25 | "command": "scripts/make", 26 | "args": ["check-types"] 27 | }, 28 | { 29 | "label": "check-docs", 30 | "type": "process", 31 | "command": "scripts/make", 32 | "args": ["check-docs"] 33 | }, 34 | { 35 | "label": "check-api", 36 | "type": "process", 37 | "command": "scripts/make", 38 | "args": ["check-api"] 39 | }, 40 | { 41 | "label": "clean", 42 | "type": "process", 43 | "command": "scripts/make", 44 | "args": ["clean"] 45 | }, 46 | { 47 | "label": "docs", 48 | "type": "process", 49 | "command": "scripts/make", 50 | "args": ["docs"] 51 | }, 52 | { 53 | "label": "docs-deploy", 54 | "type": "process", 55 | "command": "scripts/make", 56 | "args": ["docs-deploy"] 57 | }, 58 | { 59 | "label": "format", 60 | "type": "process", 61 | "command": "scripts/make", 62 | "args": ["format"] 63 | }, 64 | { 65 | "label": "release", 66 | "type": "process", 67 | "command": "scripts/make", 68 | "args": ["release", "${input:version}"] 69 | }, 70 | { 71 | "label": "setup", 72 | "type": "process", 73 | "command": "scripts/make", 74 | "args": ["setup"] 75 | }, 76 | { 77 | "label": "test", 78 | "type": "process", 79 | "command": "scripts/make", 80 | "args": ["test", "coverage"], 81 | "group": "test" 82 | }, 83 | { 84 | "label": "vscode", 85 | "type": "process", 86 | "command": "scripts/make", 87 | "args": ["vscode"] 88 | } 89 | ], 90 | "inputs": [ 91 | { 92 | "id": "version", 93 | "type": "promptString", 94 | "description": "Version" 95 | } 96 | ] 97 | } -------------------------------------------------------------------------------- /tests/helpers.py: -------------------------------------------------------------------------------- 1 | """Configuration for the pytest test suite.""" 2 | 3 | from __future__ import annotations 4 | 5 | from collections import ChainMap 6 | from contextlib import contextmanager 7 | from typing import TYPE_CHECKING, Any 8 | 9 | from markdown.core import Markdown 10 | from mkdocs.config.defaults import MkDocsConfig 11 | 12 | if TYPE_CHECKING: 13 | from collections.abc import Iterator 14 | from pathlib import Path 15 | 16 | import pytest 17 | from mkdocstrings import MkdocstringsPlugin 18 | 19 | from mkdocstrings_handlers.python import PythonHandler 20 | 21 | 22 | @contextmanager 23 | def mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Iterator[MkDocsConfig]: 24 | """Yield a MkDocs configuration object. 25 | 26 | Parameters: 27 | request: Pytest request fixture. 28 | tmp_path: Temporary path. 29 | 30 | Yields: 31 | MkDocs config. 32 | """ 33 | while hasattr(request, "_parent_request") and hasattr(request._parent_request, "_parent_request"): 34 | request = request._parent_request 35 | 36 | params = getattr(request, "param", {}) 37 | plugins = params.pop("plugins", [{"mkdocstrings": {}}]) 38 | 39 | conf = MkDocsConfig() 40 | conf_dict = { 41 | "site_name": "foo", 42 | "site_url": "https://example.org/", 43 | "site_dir": str(tmp_path), 44 | "plugins": plugins, 45 | **getattr(request, "param", {}), 46 | } 47 | # Re-create it manually as a workaround for https://github.com/mkdocs/mkdocs/issues/2289 48 | mdx_configs: dict[str, Any] = dict(ChainMap(*conf_dict.get("markdown_extensions", []))) 49 | 50 | conf.load_dict(conf_dict) 51 | assert conf.validate() == ([], []) 52 | 53 | conf["mdx_configs"] = mdx_configs 54 | conf["markdown_extensions"].insert(0, "toc") # Guaranteed to be added by MkDocs. 55 | 56 | conf = conf["plugins"]["mkdocstrings"].on_config(conf) 57 | conf = conf["plugins"]["autorefs"].on_config(conf) 58 | yield conf 59 | conf["plugins"]["mkdocstrings"].on_post_build(conf) 60 | 61 | 62 | def plugin(mkdocs_conf: MkDocsConfig) -> MkdocstringsPlugin: 63 | """Return a plugin instance. 64 | 65 | Parameters: 66 | mkdocs_conf: MkDocs configuration. 67 | 68 | Returns: 69 | mkdocstrings plugin instance. 70 | """ 71 | return mkdocs_conf["plugins"]["mkdocstrings"] 72 | 73 | 74 | def ext_markdown(mkdocs_conf: MkDocsConfig) -> Markdown: 75 | """Return a Markdown instance with MkdocstringsExtension. 76 | 77 | Parameters: 78 | mkdocs_conf: MkDocs configuration. 79 | 80 | Returns: 81 | A Markdown instance. 82 | """ 83 | return Markdown(extensions=mkdocs_conf["markdown_extensions"], extension_configs=mkdocs_conf["mdx_configs"]) 84 | 85 | 86 | def handler(plugin: MkdocstringsPlugin, ext_markdown: Markdown) -> PythonHandler: 87 | """Return a handler instance. 88 | 89 | Parameters: 90 | plugin: Plugin instance. 91 | 92 | Returns: 93 | A handler instance. 94 | """ 95 | handler = plugin.handlers.get_handler("python") 96 | handler._update_env(ext_markdown) 97 | return handler # type: ignore[return-value] 98 | -------------------------------------------------------------------------------- /tests/snapshots/signatures/separate_signature=True,show_signature_annotations=False,signature_crossrefs=False.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
    10 |

    11 | 12 | signature_package 13 | 14 |

    15 |
    16 |
    17 |
    18 |

    19 | 20 | Class 21 | 22 |

    23 |
    24 |

    25 | Docstring for 26 | 27 | Class 28 | 29 | . 30 |

    31 |
    32 |
    33 |

    34 | 35 | __init__ 36 | 37 |

    38 |
    39 | 
    __init__(a, b)
40 |
    41 |
    42 |
    43 |

    44 | Docstring for `Class. 45 | 46 | init 47 | 48 | . 49 |

    50 |
    51 |
    52 |
    53 |

    54 | 55 | method1 56 | 57 |

    58 |
    59 | 
    method1(a, b)
60 |
    61 |
    62 |
    63 |

    64 | Docstring for 65 | 66 | Class.method1 67 | 68 | . 69 |

    70 |
    71 |
    72 |
    73 |
    74 |
    75 |
    76 |

    77 | 78 | module_function 79 | 80 |

    81 |
    82 | 
    module_function(a, b)
83 |
    84 |
    85 |
    86 |

    87 | Docstring for 88 | 89 | module_function 90 | 91 | . 92 |

    93 |
    94 |
    95 |
    96 |
    97 |
    98 | -------------------------------------------------------------------------------- /tests/snapshots/signatures/separate_signature=True,show_signature_annotations=False,signature_crossrefs=True.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
    10 |

    11 | 12 | signature_package 13 | 14 |

    15 |
    16 |
    17 |
    18 |

    19 | 20 | Class 21 | 22 |

    23 |
    24 |

    25 | Docstring for 26 | 27 | Class 28 | 29 | . 30 |

    31 |
    32 |
    33 |

    34 | 35 | __init__ 36 | 37 |

    38 |
    39 | 
    __init__(a, b)
40 |
    41 |
    42 |
    43 |

    44 | Docstring for `Class. 45 | 46 | init 47 | 48 | . 49 |

    50 |
    51 |
    52 |
    53 |

    54 | 55 | method1 56 | 57 |

    58 |
    59 | 
    method1(a, b)
60 |
    61 |
    62 |
    63 |

    64 | Docstring for 65 | 66 | Class.method1 67 | 68 | . 69 |

    70 |
    71 |
    72 |
    73 |
    74 |
    75 |
    76 |

    77 | 78 | module_function 79 | 80 |

    81 |
    82 | 
    module_function(a, b)
83 |
    84 |
    85 |
    86 |

    87 | Docstring for 88 | 89 | module_function 90 | 91 | . 92 |

    93 |
    94 |
    95 |
    96 |
    97 |
    98 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=True.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |

    55 | 56 | Class 57 | 58 |

    59 |
    60 |

    61 | Docstring for 62 | 63 | Class 64 | 65 | . 66 |

    67 |
    68 |
    69 |
    70 |
    71 |
    72 |

    73 | 74 | Subclass 75 | 76 |

    77 |
    78 |

    79 | Bases: 80 | 81 | 82 | Class 83 | 84 | 85 |

    86 |

    87 | Docstring for 88 | 89 | Subclass 90 | 91 | . 92 |

    93 |
    94 |
    95 |
    96 |
    97 |
    98 |

    99 | 100 | 101 | module_function 102 | 103 | 104 | ( 105 | 106 | 107 | a 108 | 109 | 110 | , 111 | 112 | 113 | b 114 | 115 | 116 | ) 117 | 118 | 119 |

    120 |
    121 |

    122 | Docstring for 123 | 124 | module_function 125 | 126 | . 127 |

    128 |
    129 |
    130 |
    131 |
    132 |
    133 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=True.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |

    55 | 56 | Class 57 | 58 |

    59 |
    60 |

    61 | Docstring for 62 | 63 | Class 64 | 65 | . 66 |

    67 |
    68 |
    69 |
    70 |
    71 |
    72 |

    73 | 74 | Subclass 75 | 76 |

    77 |
    78 |

    79 | Bases: 80 | 81 | 82 | Class 83 | 84 | 85 |

    86 |

    87 | Docstring for 88 | 89 | Subclass 90 | 91 | . 92 |

    93 |
    94 |
    95 |
    96 |
    97 |
    98 |

    99 | 100 | 101 | module_function 102 | 103 | 104 | ( 105 | 106 | 107 | a 108 | 109 | 110 | , 111 | 112 | 113 | b 114 | 115 | 116 | ) 117 | 118 | 119 |

    120 |
    121 |

    122 | Docstring for 123 | 124 | module_function 125 | 126 | . 127 |

    128 |
    129 |
    130 |
    131 |
    132 |
    133 | -------------------------------------------------------------------------------- /tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=True.html: -------------------------------------------------------------------------------- 1 | 10 | 11 |
    12 |

    13 | 14 | members_package 15 | 16 |

    17 |
    18 |

    19 | Docstring for the package. 20 |

    21 |
    22 |
    23 |

    24 | 25 | 26 | module_attribute 27 | 28 | 29 | = 30 | 31 | 32 | 42 33 | 34 | 35 | 36 | 37 | 38 | module-attribute 39 | 40 | 41 | 42 |

    43 |
    44 |

    45 | Docstring for 46 | 47 | module_attribute 48 | 49 | . 50 |

    51 |
    52 |
    53 |
    54 |

    55 | 56 | Class 57 | 58 |

    59 |
    60 |

    61 | Docstring for 62 | 63 | Class 64 | 65 | . 66 |

    67 |
    68 |
    69 |
    70 |
    71 |
    72 |

    73 | 74 | Subclass 75 | 76 |

    77 |
    78 |

    79 | Bases: 80 | 81 | 82 | Class 83 | 84 | 85 |

    86 |

    87 | Docstring for 88 | 89 | Subclass 90 | 91 | . 92 |

    93 |
    94 |
    95 |
    96 |
    97 |
    98 |

    99 | 100 | 101 | module_function 102 | 103 | 104 | ( 105 | 106 | 107 | a 108 | 109 | 110 | , 111 | 112 | 113 | b 114 | 115 | 116 | ) 117 | 118 | 119 |

    120 |
    121 |

    122 | Docstring for 123 | 124 | module_function 125 | 126 | . 127 |

    128 |
    129 |
    130 |
    131 |
    132 |
    133 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/_internal/debug.py: -------------------------------------------------------------------------------- 1 | from __future__ import annotations 2 | 3 | import os 4 | import platform 5 | import sys 6 | from dataclasses import dataclass 7 | from importlib import metadata 8 | 9 | 10 | @dataclass 11 | class _Variable: 12 | """Dataclass describing an environment variable.""" 13 | 14 | name: str 15 | """Variable name.""" 16 | value: str 17 | """Variable value.""" 18 | 19 | 20 | @dataclass 21 | class _Package: 22 | """Dataclass describing a Python package.""" 23 | 24 | name: str 25 | """Package name.""" 26 | version: str 27 | """Package version.""" 28 | 29 | 30 | @dataclass 31 | class _Environment: 32 | """Dataclass to store environment information.""" 33 | 34 | interpreter_name: str 35 | """Python interpreter name.""" 36 | interpreter_version: str 37 | """Python interpreter version.""" 38 | interpreter_path: str 39 | """Path to Python executable.""" 40 | platform: str 41 | """Operating System.""" 42 | packages: list[_Package] 43 | """Installed packages.""" 44 | variables: list[_Variable] 45 | """Environment variables.""" 46 | 47 | 48 | def _interpreter_name_version() -> tuple[str, str]: 49 | if hasattr(sys, "implementation"): 50 | impl = sys.implementation.version 51 | version = f"{impl.major}.{impl.minor}.{impl.micro}" 52 | kind = impl.releaselevel 53 | if kind != "final": 54 | version += kind[0] + str(impl.serial) 55 | return sys.implementation.name, version 56 | return "", "0.0.0" 57 | 58 | 59 | def _get_version(dist: str = "mkdocstrings-python") -> str: 60 | """Get version of the given distribution. 61 | 62 | Parameters: 63 | dist: A distribution name. 64 | 65 | Returns: 66 | A version number. 67 | """ 68 | try: 69 | return metadata.version(dist) 70 | except metadata.PackageNotFoundError: 71 | return "0.0.0" 72 | 73 | 74 | def _get_debug_info() -> _Environment: 75 | """Get debug/environment information. 76 | 77 | Returns: 78 | Environment information. 79 | """ 80 | py_name, py_version = _interpreter_name_version() 81 | packages = ["mkdocstrings-python"] 82 | variables = ["PYTHONPATH", *[var for var in os.environ if var.startswith("MKDOCSTRINGS_PYTHON")]] 83 | return _Environment( 84 | interpreter_name=py_name, 85 | interpreter_version=py_version, 86 | interpreter_path=sys.executable, 87 | platform=platform.platform(), 88 | variables=[_Variable(var, val) for var in variables if (val := os.getenv(var))], # ty: ignore[invalid-argument-type] 89 | packages=[_Package(pkg, _get_version(pkg)) for pkg in packages], 90 | ) 91 | 92 | 93 | def _print_debug_info() -> None: 94 | """Print debug/environment information.""" 95 | info = _get_debug_info() 96 | print(f"- __System__: {info.platform}") 97 | print(f"- __Python__: {info.interpreter_name} {info.interpreter_version} ({info.interpreter_path})") 98 | print("- __Environment variables__:") 99 | for var in info.variables: 100 | print(f" - `{var.name}`: `{var.value}`") 101 | print("- __Installed packages__:") 102 | for pkg in info.packages: 103 | print(f" - `{pkg.name}` v{pkg.version}") 104 | 105 | 106 | if __name__ == "__main__": 107 | _print_debug_info() 108 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for "Classes" sections in docstrings. 2 | 3 | This template renders a list of documented classes in the format 4 | specified with the [`docstring_section_style`][] configuration option. 5 | 6 | Context: 7 | section (griffe.DocstringSectionAttributes): The section to render. 8 | -#} 9 | 10 | {% block logs scoped %} 11 | {#- Logging block. 12 | 13 | This block can be used to log debug messages, deprecation messages, warnings, etc. 14 | -#} 15 | {{ log.debug("Rendering classes section") }} 16 | {% endblock logs %} 17 | 18 | {% import "language.html.jinja" as lang with context %} 19 | {#- Language module providing the `t` translation method. -#} 20 | 21 | {% if config.docstring_section_style == "table" %} 22 | {% block table_style scoped %} 23 | {#- Block for the `table` section style. -#} 24 |

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

    25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | {% for class in section.value %} 34 | 35 | 36 | 41 | 42 | {% endfor %} 43 | 44 |
    {{ lang.t("Name") }}{{ lang.t("Description") }}
    {{ class.name }} 37 |
    38 | {{ class.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 39 |
    40 |
    45 | {% endblock table_style %} 46 | {% elif config.docstring_section_style == "list" %} 47 | {% block list_style scoped %} 48 | {#- Block for the `list` section style. -#} 49 |

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

    50 | 61 | {% endblock list_style %} 62 | {% elif config.docstring_section_style == "spacy" %} 63 | {% block spacy_style scoped %} 64 | {#- Block for the `spacy` section style. -#} 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | {% for class in section.value %} 74 | 75 | 76 | 81 | 82 | {% endfor %} 83 | 84 |
    {{ (section.title or lang.t("CLASS")).rstrip(":").upper() }}{{ lang.t("DESCRIPTION") }}
    {{ class.name }} 77 |
    78 | {{ class.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 79 |
    80 |
    85 | {% endblock spacy_style %} 86 | {% endif %} -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for "Modules" sections in docstrings. 2 | 3 | This template renders a list of documented modules in the format 4 | specified with the [`docstring_section_style`][] configuration option. 5 | 6 | Context: 7 | section (griffe.DocstringSectionAttributes): The section to render. 8 | -#} 9 | 10 | {% block logs scoped %} 11 | {#- Logging block. 12 | 13 | This block can be used to log debug messages, deprecation messages, warnings, etc. 14 | -#} 15 | {{ log.debug("Rendering modules section") }} 16 | {% endblock logs %} 17 | 18 | {% import "language.html.jinja" as lang with context %} 19 | {#- Language module providing the `t` translation method. -#} 20 | 21 | {% if config.docstring_section_style == "table" %} 22 | {% block table_style scoped %} 23 | {#- Block for the `table` section style. -#} 24 |

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

    25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | {% for module in section.value %} 34 | 35 | 36 | 41 | 42 | {% endfor %} 43 | 44 |
    {{ lang.t("Name") }}{{ lang.t("Description") }}
    {{ module.name }} 37 |
    38 | {{ module.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 39 |
    40 |
    45 | {% endblock table_style %} 46 | {% elif config.docstring_section_style == "list" %} 47 | {% block list_style scoped %} 48 | {#- Block for the `list` section style. -#} 49 |

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

    50 | 61 | {% endblock list_style %} 62 | {% elif config.docstring_section_style == "spacy" %} 63 | {% block spacy_style scoped %} 64 | {#- Block for the `spacy` section style. -#} 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | {% for module in section.value %} 74 | 75 | 76 | 81 | 82 | {% endfor %} 83 | 84 |
    {{ (section.title or lang.t("MODULE")).rstrip(":").upper() }}{{ lang.t("DESCRIPTION") }}
    {{ module.name }} 77 |
    78 | {{ module.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 79 |
    80 |
    85 | {% endblock spacy_style %} 86 | {% endif %} -------------------------------------------------------------------------------- /tests/snapshots/signatures/separate_signature=False,show_signature_annotations=False,signature_crossrefs=False.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
    10 |

    11 | 12 | signature_package 13 | 14 |

    15 |
    16 |
    17 |
    18 |

    19 | 20 | Class 21 | 22 |

    23 |
    24 |

    25 | Docstring for 26 | 27 | Class 28 | 29 | . 30 |

    31 |
    32 |
    33 |

    34 | 35 | 36 | __init__ 37 | 38 | 39 | ( 40 | 41 | 42 | a 43 | 44 | 45 | , 46 | 47 | 48 | b 49 | 50 | 51 | ) 52 | 53 | 54 |

    55 |
    56 |

    57 | Docstring for `Class. 58 | 59 | init 60 | 61 | . 62 |

    63 |
    64 |
    65 |
    66 |

    67 | 68 | 69 | method1 70 | 71 | 72 | ( 73 | 74 | 75 | a 76 | 77 | 78 | , 79 | 80 | 81 | b 82 | 83 | 84 | ) 85 | 86 | 87 |

    88 |
    89 |

    90 | Docstring for 91 | 92 | Class.method1 93 | 94 | . 95 |

    96 |
    97 |
    98 |
    99 |
    100 |
    101 |
    102 |

    103 | 104 | 105 | module_function 106 | 107 | 108 | ( 109 | 110 | 111 | a 112 | 113 | 114 | , 115 | 116 | 117 | b 118 | 119 | 120 | ) 121 | 122 | 123 |

    124 |
    125 |

    126 | Docstring for 127 | 128 | module_function 129 | 130 | . 131 |

    132 |
    133 |
    134 |
    135 |
    136 |
    137 | -------------------------------------------------------------------------------- /tests/snapshots/signatures/separate_signature=False,show_signature_annotations=False,signature_crossrefs=True.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
    10 |

    11 | 12 | signature_package 13 | 14 |

    15 |
    16 |
    17 |
    18 |

    19 | 20 | Class 21 | 22 |

    23 |
    24 |

    25 | Docstring for 26 | 27 | Class 28 | 29 | . 30 |

    31 |
    32 |
    33 |

    34 | 35 | 36 | __init__ 37 | 38 | 39 | ( 40 | 41 | 42 | a 43 | 44 | 45 | , 46 | 47 | 48 | b 49 | 50 | 51 | ) 52 | 53 | 54 |

    55 |
    56 |

    57 | Docstring for `Class. 58 | 59 | init 60 | 61 | . 62 |

    63 |
    64 |
    65 |
    66 |

    67 | 68 | 69 | method1 70 | 71 | 72 | ( 73 | 74 | 75 | a 76 | 77 | 78 | , 79 | 80 | 81 | b 82 | 83 | 84 | ) 85 | 86 | 87 |

    88 |
    89 |

    90 | Docstring for 91 | 92 | Class.method1 93 | 94 | . 95 |

    96 |
    97 |
    98 |
    99 |
    100 |
    101 |
    102 |

    103 | 104 | 105 | module_function 106 | 107 | 108 | ( 109 | 110 | 111 | a 112 | 113 | 114 | , 115 | 116 | 117 | b 118 | 119 | 120 | ) 121 | 122 | 123 |

    124 |
    125 |

    126 | Docstring for 127 | 128 | module_function 129 | 130 | . 131 |

    132 |
    133 |
    134 |
    135 |
    136 |
    137 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/docstring/type_aliases.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for "Type Aliases" sections in docstrings. 2 | 3 | This template renders a list of documented type aliases in the format 4 | specified with the [`docstring_section_style`][] configuration option. 5 | 6 | Context: 7 | section (griffe.DocstringSectionTypeAliases): The section to render. 8 | -#} 9 | 10 | {% block logs scoped %} 11 | {#- Logging block. 12 | 13 | This block can be used to log debug messages, deprecation messages, warnings, etc. 14 | -#} 15 | {{ log.debug("Rendering type aliases section") }} 16 | {% endblock logs %} 17 | 18 | {% import "language.html.jinja" as lang with context %} 19 | {#- Language module providing the `t` translation method. -#} 20 | 21 | {% if config.docstring_section_style == "table" %} 22 | {% block table_style scoped %} 23 | {#- Block for the `table` section style. -#} 24 |

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

    25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | {% for type_alias in section.value %} 34 | 35 | 36 | 41 | 42 | {% endfor %} 43 | 44 |
    {{ lang.t("Name") }}{{ lang.t("Description") }}
    {{ type_alias.name }} 37 |
    38 | {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 39 |
    40 |
    45 | {% endblock table_style %} 46 | {% elif config.docstring_section_style == "list" %} 47 | {% block list_style scoped %} 48 | {#- Block for the `list` section style. -#} 49 |

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

    50 | 61 | {% endblock list_style %} 62 | {% elif config.docstring_section_style == "spacy" %} 63 | {% block spacy_style scoped %} 64 | {#- Block for the `spacy` section style. -#} 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | {% for type_alias in section.value %} 74 | 75 | 76 | 81 | 82 | {% endfor %} 83 | 84 |
    {{ (section.title or lang.t("TYPE ALIAS")).rstrip(":").upper() }}{{ lang.t("DESCRIPTION") }}
    {{ type_alias.name }} 77 |
    78 | {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 79 |
    80 |
    85 | {% endblock spacy_style %} 86 | {% endif %} 87 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/type_parameters.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for type parameters. 2 | 3 | This template renders the type parameters of a generic obj. 4 | It iterates over the type parameters of the object to rebuild the signature. 5 | The signature is the list of type parameters of a generic object, including their names, default values, and bound or constraints. 6 | 7 | Context: 8 | obj (griffe.Object): The object to render. 9 | config (dict): The configuration options. 10 | -#} 11 | 12 | {%- if config.show_signature_type_parameters -%} 13 | {%- block logs scoped -%} 14 | {#- Logging block. 15 | 16 | This block can be used to log debug messages, deprecation messages, warnings, etc. 17 | -#} 18 | {{ log.debug("Rendering type parameters") }} 19 | {%- endblock logs -%} 20 | 21 | {%- with ns = namespace(annotation="", equal="=", default=False) -%} 22 | {%- if obj.is_generic -%} 23 | [ 24 | {%- for type_parameter in obj.type_parameters -%} 25 | {#- Prepare type bound or constraints. -#} 26 | {%- if config.show_signature_annotations and type_parameter.annotation is not none -%} 27 | {%- set ns.equal = " = " -%} 28 | {%- if config.separate_signature and config.signature_crossrefs -%} 29 | {%- with expression = type_parameter.annotation -%} 30 | {%- set ns.annotation -%}: {% include "expression.html.jinja" with context %}{%- endset -%} 31 | {%- endwith -%} 32 | {%- else -%} 33 | {%- set ns.annotation = ": " + type_parameter.annotation|safe -%} 34 | {%- endif -%} 35 | {%- else -%} 36 | {%- set ns.equal = "=" -%} 37 | {%- set ns.annotation = "" -%} 38 | {%- endif -%} 39 | 40 | {#- Prepare default value. -#} 41 | {%- if type_parameter.default is not none -%} 42 | {%- set ns.default = True -%} 43 | {%- else -%} 44 | {%- set ns.default = False -%} 45 | {%- endif -%} 46 | 47 | {#- Prepare name. -#} 48 | {%- set type_param_prefix -%} 49 | {%- if type_parameter.kind == "type-var-tuple" -%} 50 | * 51 | {%- elif type_parameter.kind == "param-spec" -%} 52 | ** 53 | {%- endif -%} 54 | {%- endset -%} 55 | 56 | {#- Render type parameter name with optional cross-reference to its heading. -#} 57 | {{ type_param_prefix }} 58 | {%- if config.separate_signature and config.type_parameter_headings and config.signature_crossrefs -%} 59 | {%- filter stash_crossref(length=type_parameter.name|length) -%} 60 | {{ type_parameter.name }} 61 | {%- endfilter -%} 62 | {%- else -%} 63 | {{ type_parameter.name }} 64 | {%- endif -%} 65 | 66 | {#- Render type parameter bound or constraints. -#} 67 | {{ ns.annotation }} 68 | 69 | {#- Render type parameter default value. -#} 70 | {%- if ns.default -%} 71 | {{ ns.equal }} 72 | {%- if config.signature_crossrefs and config.separate_signature -%} 73 | {%- with expression = type_parameter.default -%} 74 | {%- include "expression.html.jinja" with context -%} 75 | {%- endwith -%} 76 | {%- else -%} 77 | {{ type_parameter.default|safe }} 78 | {%- endif -%} 79 | {%- endif -%} 80 | 81 | {%- if not loop.last %}, {% endif -%} 82 | {%- endfor -%} 83 | ] 84 | {%- endif -%} 85 | 86 | {%- endwith -%} 87 | {%- endif -%} 88 | -------------------------------------------------------------------------------- /src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja: -------------------------------------------------------------------------------- 1 | {#- Template for docstrings. 2 | 3 | This template renders Python docstrings. 4 | Griffe parses docstrings into a list of sections, each with a `kind` and a `value`. 5 | This template can then iterate on these sections and render them according to the configuration. 6 | 7 | Context: 8 | docstring_sections (list[griffe.DocstringSection]): The list of docstring sections. 9 | config (dict): The configuration dictionary. 10 | heading_level (int): The heading level to use for Markdown conversion. 11 | html_id (str): The HTML ID to use for Markdown conversion. 12 | -#} 13 | 14 | {% if docstring_sections %} 15 | {% block logs scoped %} 16 | {#- Logging block. 17 | 18 | This block can be used to log debug messages, deprecation messages, warnings, etc. 19 | -#} 20 | {{ log.debug("Rendering docstring") }} 21 | {% endblock logs %} 22 | {% with autoref_hook = AutorefsHook(obj, config) %} 23 | {% for section in docstring_sections %} 24 | {% if config.show_docstring_description and section.kind.value == "text" %} 25 | {{ section.value|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} 26 | {% elif config.show_docstring_attributes and section.kind.value == "attributes" %} 27 | {% include "docstring/attributes.html.jinja" with context %} 28 | {% elif config.show_docstring_functions and section.kind.value == "functions" %} 29 | {% include "docstring/functions.html.jinja" with context %} 30 | {% elif config.show_docstring_classes and section.kind.value == "classes" %} 31 | {% include "docstring/classes.html.jinja" with context %} 32 | {% elif config.show_docstring_type_aliases and section.kind.value == "type aliases" %} 33 | {% include "docstring/type_aliases.html.jinja" with context %} 34 | {% elif config.show_docstring_modules and section.kind.value == "modules" %} 35 | {% include "docstring/modules.html.jinja" with context %} 36 | {% elif config.show_docstring_type_parameters and section.kind.value == "type parameters" %} 37 | {% include "docstring/type_parameters.html.jinja" with context %} 38 | {% elif config.show_docstring_parameters and section.kind.value == "parameters" %} 39 | {% include "docstring/parameters.html.jinja" with context %} 40 | {% elif config.show_docstring_other_parameters and section.kind.value == "other parameters" %} 41 | {% include "docstring/other_parameters.html.jinja" with context %} 42 | {% elif config.show_docstring_raises and section.kind.value == "raises" %} 43 | {% include "docstring/raises.html.jinja" with context %} 44 | {% elif config.show_docstring_warns and section.kind.value == "warns" %} 45 | {% include "docstring/warns.html.jinja" with context %} 46 | {% elif config.show_docstring_yields and section.kind.value == "yields" %} 47 | {% include "docstring/yields.html.jinja" with context %} 48 | {% elif config.show_docstring_receives and section.kind.value == "receives" %} 49 | {% include "docstring/receives.html.jinja" with context %} 50 | {% elif config.show_docstring_returns and section.kind.value == "returns" %} 51 | {% include "docstring/returns.html.jinja" with context %} 52 | {% elif config.show_docstring_examples and section.kind.value == "examples" %} 53 | {% include "docstring/examples.html.jinja" with context %} 54 | {% elif config.show_docstring_description and section.kind.value == "admonition" %} 55 | {% include "docstring/admonition.html.jinja" with context %} 56 | {% endif %} 57 | {% endfor %} 58 | {% endwith %} 59 | {% endif %} 60 | -------------------------------------------------------------------------------- /tests/snapshots/signatures/separate_signature=True,show_signature_annotations=True,signature_crossrefs=False.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
    10 |

    11 | 12 | signature_package 13 | 14 |

    15 |
    16 |
    17 |
    18 |

    19 | 20 | Class 21 | 22 |

    23 |
    24 |

    25 | Docstring for 26 | 27 | Class 28 | 29 | . 30 |

    31 |
    32 |
    33 |

    34 | 35 | __init__ 36 | 37 |

    38 |
    39 | 
    __init__(a: int, b: str) -> None
40 |
    41 |
    42 |
    43 |

    44 | Docstring for `Class. 45 | 46 | init 47 | 48 | . 49 |

    50 |
    51 |
    52 |
    53 |

    54 | 55 | method1 56 | 57 |

    58 |
    59 | 
    method1(a: int, b: str) -> None
60 |
    61 |
    62 |
    63 |

    64 | Docstring for 65 | 66 | Class.method1 67 | 68 | . 69 |

    70 |
    71 |
    72 |
    73 |
    74 |
    75 |
    76 |

    77 | 78 | module_function 79 | 80 |

    81 |
    82 | 
    module_function(a: int, b: str) -> None
83 |
    84 |
    85 |
    86 |

    87 | Docstring for 88 | 89 | module_function 90 | 91 | . 92 |

    93 |
    94 |
    95 |
    96 |
    97 |
    98 | -------------------------------------------------------------------------------- /tests/snapshots/overloads/overloads_only=False,separate_signature=True,show_overloads=False.html: -------------------------------------------------------------------------------- 1 | 8 | 9 |
    10 |

    11 | 12 | overloads_package 13 | 14 |

    15 |
    16 |
    17 |
    18 |

    19 | 20 | Class 21 | 22 |

    23 |
    24 |

    25 | Docstring for 26 | 27 | Class 28 | 29 | . 30 |

    31 |
    32 |
    33 |

    34 | 35 | bar 36 | 37 |

    38 |
    39 | 
    bar(a, b)
 40 |
    41 |
    42 |
    43 |

    44 | Docstring for 45 | 46 | Class.bar 47 | 48 | . 49 |

    50 |
    51 |
    52 |
    53 |

    54 | 55 | foo 56 | 57 |

    58 |
    59 | 
    foo(a, b)
 60 |
    61 |
    62 |
    63 |

    64 | Docstring for 65 | 66 | Class.foo 67 | 68 | . 69 |

    70 |
    71 |
    72 |
    73 |
    74 |
    75 |
    76 |

    77 | 78 | bar 79 | 80 |

    81 |
    82 | 
    bar(a, b)
 83 |
    84 |
    85 |
    86 |

    87 | Docstring for 88 | 89 | bar 90 | 91 | . 92 |

    93 |
    94 |
    95 |
    96 |

    97 | 98 | foo 99 | 100 |

    101 |
    102 | 
    foo(a, b)
103 |
    104 |
    105 |
    106 |

    107 | Docstring for 108 | 109 | foo 110 | 111 | . 112 |

    113 |
    114 |
    115 |
    116 |
    117 |
    118 | --------------------------------------------------------------------------------