# mkdocstrings
[](https://github.com/mkdocstrings/mkdocstrings/actions?query=workflow%3Aci)
[](https://mkdocstrings.github.io/)
[](https://pypi.org/project/mkdocstrings/)
[](https://anaconda.org/conda-forge/mkdocstrings)
[](https://app.gitter.im/#/room/#mkdocstrings:gitter.im)
Automatic documentation from sources, for [MkDocs](https://www.mkdocs.org/).
Come have a chat or ask questions on our [Gitter channel](https://gitter.im/mkdocstrings/community).
---
**[Features](#features)** - **[Installation](#installation)** - **[Quick usage](#quick-usage)**
## Features
- [**Language-agnostic:**](https://mkdocstrings.github.io/handlers/overview/)
just like *MkDocs*, *mkdocstrings* is written in Python but is language-agnostic.
It means you can use it with any programming language, as long as there is a
[**handler**](https://mkdocstrings.github.io/reference/handlers/base/) for it.
We currently have [handlers](https://mkdocstrings.github.io/handlers/overview/) for the
[C](https://mkdocstrings.github.io/c/),
[Crystal](https://mkdocstrings.github.io/crystal/),
[Python](https://mkdocstrings.github.io/python/),
[TypeScript](https://mkdocstrings.github.io/typescript/), and
[VBA](https://pypi.org/project/mkdocstrings-vba/) languages,
as well as for [shell scripts/libraries](https://mkdocstrings.github.io/shell/).
Maybe you'd like to add another one to the list? :wink:
- [**Multiple themes support:**](https://mkdocstrings.github.io/theming/)
each handler can offer multiple themes. Currently, we offer the
:star: [Material theme](https://squidfunk.github.io/mkdocs-material/) :star:
as well as basic support for the ReadTheDocs and MkDocs themes for the Python handler.
- [**Cross-references across pages:**](https://mkdocstrings.github.io/usage/#cross-references)
*mkdocstrings* makes it possible to reference headings in other Markdown files with the classic Markdown linking
syntax: `[identifier][]` or `[title][identifier]` -- and you don't need to remember which exact page this object was
on. This works for any heading that's produced by a *mkdocstrings* language handler, and you can opt to include
*any* Markdown heading into the global referencing scheme.
**Note**: in versions prior to 0.15 *all* Markdown headers were included, but now you need to
[opt in](https://mkdocstrings.github.io/usage/#cross-references-to-any-markdown-heading).
- [**Cross-references across sites:**](https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories)
similarly to [Sphinx's intersphinx extension](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html),
*mkdocstrings* can reference API items from other libraries, given they provide an inventory and you load
that inventory in your MkDocs configuration.
- [**Inline injection in Markdown:**](https://mkdocstrings.github.io/usage/)
instead of generating Markdown files, *mkdocstrings* allows you to inject
documentation anywhere in your Markdown contents. The syntax is simple: `::: identifier` followed by a 4-spaces
indented YAML block. The identifier and YAML configuration will be passed to the appropriate handler
to collect and render documentation.
- [**Global and local configuration:**](https://mkdocstrings.github.io/usage/#global-options)
each handler can be configured globally in `mkdocs.yml`, and locally for each
"autodoc" instruction.
- **Reasonable defaults:**
you should be able to just drop the plugin in your configuration and enjoy your auto-generated docs.
## Used by
*mkdocstrings* is used by well-known companies, projects and scientific teams:
[Ansible](https://molecule.readthedocs.io/configuration/),
[Apache](https://streampipes.apache.org/docs/docs/python/latest/reference/client/client/),
[FastAPI](https://fastapi.tiangolo.com/reference/fastapi/),
[Google](https://docs.kidger.site/jaxtyping/api/runtime-type-checking/),
[IBM](https://ds4sd.github.io/docling/api_reference/document_converter/),
[Jitsi](https://jitsi.github.io/jiwer/reference/alignment/),
[Microsoft](https://microsoft.github.io/presidio/api/analyzer_python/),
[NVIDIA](https://nvidia.github.io/bionemo-framework/API_reference/bionemo/core/api/),
[Prefect](https://docs.prefect.io/2.10.12/api-ref/prefect/agent/),
[Pydantic](https://docs.pydantic.dev/dev-v2/api/main/),
[Textual](https://textual.textualize.io/api/app/),
[and more...](https://github.com/mkdocstrings/mkdocstrings/network/dependents)
## Installation
The `mkdocstrings` package doesn't provide support for any language: it's just a common base for language handlers.
It means you likely want to install it with one or more official handlers, using [extras](https://packaging.python.org/en/latest/specifications/dependency-specifiers/#extras).
For example, to install it with Python support:
```bash
pip install 'mkdocstrings[python]'
```
Alternatively, you can directly install the language handlers themselves,
which depend on `mkdocstrings` anyway:
```bash
pip install mkdocstrings-python
```
This will give you more control over the accepted range of versions for the handlers themselves.
See the [official language handlers](https://mkdocstrings.github.io/handlers/overview/).
---
With `conda`:
```bash
conda install -c conda-forge mkdocstrings mkdocstrings-python
```
## Quick usage
In `mkdocs.yml`:
```yaml
site_name: "My Library"
theme:
name: "material"
plugins:
- search
- mkdocstrings
```
In one of your markdown files:
```markdown
# Reference
::: my_library.my_module.my_class
```
See the [Usage](https://mkdocstrings.github.io/usage) section of the docs for more examples!
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocstrings",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "mkdocs, mkdocs-plugin, docstrings, autodoc, documentation",
"author": null,
"author_email": "=?utf-8?q?Timoth=C3=A9e_Mazzucotelli?= <dev@pawamoy.fr>",
"download_url": "https://files.pythonhosted.org/packages/86/4b/70522427768a4637ffac376140f362dc3d159364fb64e698667e51053d57/mkdocstrings-0.28.0.tar.gz",
"platform": null,
"description": "# mkdocstrings\n\n[](https://github.com/mkdocstrings/mkdocstrings/actions?query=workflow%3Aci)\n[](https://mkdocstrings.github.io/)\n[](https://pypi.org/project/mkdocstrings/)\n[](https://anaconda.org/conda-forge/mkdocstrings)\n[](https://app.gitter.im/#/room/#mkdocstrings:gitter.im)\n\nAutomatic documentation from sources, for [MkDocs](https://www.mkdocs.org/).\nCome have a chat or ask questions on our [Gitter channel](https://gitter.im/mkdocstrings/community).\n\n---\n\n**[Features](#features)** - **[Installation](#installation)** - **[Quick usage](#quick-usage)**\n\n\n\n## Features\n\n- [**Language-agnostic:**](https://mkdocstrings.github.io/handlers/overview/)\n just like *MkDocs*, *mkdocstrings* is written in Python but is language-agnostic.\n It means you can use it with any programming language, as long as there is a\n [**handler**](https://mkdocstrings.github.io/reference/handlers/base/) for it.\n We currently have [handlers](https://mkdocstrings.github.io/handlers/overview/) for the\n [C](https://mkdocstrings.github.io/c/),\n [Crystal](https://mkdocstrings.github.io/crystal/),\n [Python](https://mkdocstrings.github.io/python/),\n [TypeScript](https://mkdocstrings.github.io/typescript/), and\n [VBA](https://pypi.org/project/mkdocstrings-vba/) languages,\n as well as for [shell scripts/libraries](https://mkdocstrings.github.io/shell/).\n Maybe you'd like to add another one to the list? :wink:\n\n- [**Multiple themes support:**](https://mkdocstrings.github.io/theming/)\n each handler can offer multiple themes. Currently, we offer the\n :star: [Material theme](https://squidfunk.github.io/mkdocs-material/) :star:\n as well as basic support for the ReadTheDocs and MkDocs themes for the Python handler.\n\n- [**Cross-references across pages:**](https://mkdocstrings.github.io/usage/#cross-references)\n *mkdocstrings* makes it possible to reference headings in other Markdown files with the classic Markdown linking\n syntax: `[identifier][]` or `[title][identifier]` -- and you don't need to remember which exact page this object was\n on. This works for any heading that's produced by a *mkdocstrings* language handler, and you can opt to include\n *any* Markdown heading into the global referencing scheme.\n\n **Note**: in versions prior to 0.15 *all* Markdown headers were included, but now you need to\n [opt in](https://mkdocstrings.github.io/usage/#cross-references-to-any-markdown-heading).\n\n- [**Cross-references across sites:**](https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories)\n similarly to [Sphinx's intersphinx extension](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html),\n *mkdocstrings* can reference API items from other libraries, given they provide an inventory and you load\n that inventory in your MkDocs configuration.\n\n- [**Inline injection in Markdown:**](https://mkdocstrings.github.io/usage/)\n instead of generating Markdown files, *mkdocstrings* allows you to inject\n documentation anywhere in your Markdown contents. The syntax is simple: `::: identifier` followed by a 4-spaces\n indented YAML block. The identifier and YAML configuration will be passed to the appropriate handler\n to collect and render documentation.\n\n- [**Global and local configuration:**](https://mkdocstrings.github.io/usage/#global-options)\n each handler can be configured globally in `mkdocs.yml`, and locally for each\n \"autodoc\" instruction.\n\n- **Reasonable defaults:**\n you should be able to just drop the plugin in your configuration and enjoy your auto-generated docs.\n\n## Used by\n\n*mkdocstrings* is used by well-known companies, projects and scientific teams:\n[Ansible](https://molecule.readthedocs.io/configuration/),\n[Apache](https://streampipes.apache.org/docs/docs/python/latest/reference/client/client/),\n[FastAPI](https://fastapi.tiangolo.com/reference/fastapi/),\n[Google](https://docs.kidger.site/jaxtyping/api/runtime-type-checking/),\n[IBM](https://ds4sd.github.io/docling/api_reference/document_converter/),\n[Jitsi](https://jitsi.github.io/jiwer/reference/alignment/),\n[Microsoft](https://microsoft.github.io/presidio/api/analyzer_python/),\n[NVIDIA](https://nvidia.github.io/bionemo-framework/API_reference/bionemo/core/api/),\n[Prefect](https://docs.prefect.io/2.10.12/api-ref/prefect/agent/),\n[Pydantic](https://docs.pydantic.dev/dev-v2/api/main/),\n[Textual](https://textual.textualize.io/api/app/),\n[and more...](https://github.com/mkdocstrings/mkdocstrings/network/dependents)\n\n## Installation\n\nThe `mkdocstrings` package doesn't provide support for any language: it's just a common base for language handlers.\nIt means you likely want to install it with one or more official handlers, using [extras](https://packaging.python.org/en/latest/specifications/dependency-specifiers/#extras).\nFor example, to install it with Python support:\n\n```bash\npip install 'mkdocstrings[python]'\n```\n\nAlternatively, you can directly install the language handlers themselves,\nwhich depend on `mkdocstrings` anyway:\n\n```bash\npip install mkdocstrings-python\n```\n\nThis will give you more control over the accepted range of versions for the handlers themselves.\n\nSee the [official language handlers](https://mkdocstrings.github.io/handlers/overview/).\n\n---\n\nWith `conda`:\n\n```bash\nconda install -c conda-forge mkdocstrings mkdocstrings-python\n```\n\n## Quick usage\n\nIn `mkdocs.yml`:\n\n```yaml\nsite_name: \"My Library\"\n\ntheme:\n name: \"material\"\n\nplugins:\n- search\n- mkdocstrings\n```\n\nIn one of your markdown files:\n\n```markdown\n# Reference\n\n::: my_library.my_module.my_class\n```\n\nSee the [Usage](https://mkdocstrings.github.io/usage) section of the docs for more examples!\n",
"bugtrack_url": null,
"license": "ISC",
"summary": "Automatic documentation from sources, for MkDocs.",
"version": "0.28.0",
"project_urls": {
"Changelog": "https://mkdocstrings.github.io/changelog",
"Discussions": "https://github.com/mkdocstrings/mkdocstrings/discussions",
"Documentation": "https://mkdocstrings.github.io",
"Funding": "https://github.com/sponsors/pawamoy",
"Gitter": "https://gitter.im/mkdocstrings/community",
"Homepage": "https://mkdocstrings.github.io",
"Issues": "https://github.com/mkdocstrings/mkdocstrings/issues",
"Repository": "https://github.com/mkdocstrings/mkdocstrings"
},
"split_keywords": [
"mkdocs",
" mkdocs-plugin",
" docstrings",
" autodoc",
" documentation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "75c3e5a319d4de0867c1b59ff22abb93bf898f9812e934ab75dcf7fe94e85bb6",
"md5": "53733f631910c56eb1e13ac7fb48badc",
"sha256": "84cf3dc910614781fe0fee46ce8006fde7df6cc7cca2e3f799895fb8a9170b39"
},
"downloads": -1,
"filename": "mkdocstrings-0.28.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "53733f631910c56eb1e13ac7fb48badc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 4700952,
"upload_time": "2025-02-03T16:01:37",
"upload_time_iso_8601": "2025-02-03T16:01:37.059156Z",
"url": "https://files.pythonhosted.org/packages/75/c3/e5a319d4de0867c1b59ff22abb93bf898f9812e934ab75dcf7fe94e85bb6/mkdocstrings-0.28.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "864b70522427768a4637ffac376140f362dc3d159364fb64e698667e51053d57",
"md5": "a98a5964c12bf88dabe9c71a748fb0e0",
"sha256": "df20afef1eafe36ba466ae20732509ecb74237653a585f5061937e54b553b4e0"
},
"downloads": -1,
"filename": "mkdocstrings-0.28.0.tar.gz",
"has_sig": false,
"md5_digest": "a98a5964c12bf88dabe9c71a748fb0e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 3392797,
"upload_time": "2025-02-03T16:01:40",
"upload_time_iso_8601": "2025-02-03T16:01:40.407750Z",
"url": "https://files.pythonhosted.org/packages/86/4b/70522427768a4637ffac376140f362dc3d159364fb64e698667e51053d57/mkdocstrings-0.28.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-03 16:01:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mkdocstrings",
"github_project": "mkdocstrings",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocstrings"
}
JSON
