mkdocstrings


Namemkdocstrings JSON
Version 0.24.0 PyPI version JSON
download
home_page
SummaryAutomatic documentation from sources, for MkDocs.
upload_time2023-11-14 17:46:20
maintainer
docs_urlNone
author
requires_python>=3.8
licenseISC
keywords mkdocs mkdocs-plugin docstrings autodoc documentation
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # mkdocstrings

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

Automatic documentation from sources, for [MkDocs](https://mkdocs.org/).
Come have a chat or ask questions on our [Gitter channel](https://gitter.im/mkdocstrings/community).

---

**[Features](#features)** - **[Requirements](#requirements)** - **[Installation](#installation)** - **[Quick usage](#quick-usage)**

![mkdocstrings_gif1](https://user-images.githubusercontent.com/3999221/77157604-fb807480-6aa1-11ea-99e0-d092371d4de0.gif)

## 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 [Crystal](https://mkdocstrings.github.io/crystal/) and [Python](https://mkdocstrings.github.io/python/) 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.

- ~~**Watch source code directories:**~~
  this feature was removed as it is now [built in MkDocs](https://www.mkdocs.org/user-guide/configuration/#watch). 

- **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/),
[Google](https://docs.kidger.site/jaxtyping/api/runtime-type-checking/),
[Jitsi](https://jitsi.github.io/jiwer/reference/alignment/),
[Microsoft](https://microsoft.github.io/presidio/api/analyzer_python/),
[Prefect](https://docs.prefect.io/2.10.12/api-ref/prefect/agent/),
[Pydantic](https://docs.pydantic.dev/dev-v2/api/main/),
[and more...](https://github.com/mkdocstrings/mkdocstrings/network/dependents)

## Installation

With `pip`:

```bash
pip install mkdocstrings
```

You can install support for specific languages using extras, for example:

```bash
pip install 'mkdocstrings[crystal,python]'
```

See the [available language handlers](https://mkdocstrings.github.io/handlers/overview/).

With `conda`:

```bash
conda install -c conda-forge mkdocstrings
```

## 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": "",
    "name": "mkdocstrings",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "",
    "keywords": "mkdocs mkdocs-plugin docstrings autodoc documentation",
    "author": "",
    "author_email": "Timoth\u00e9e Mazzucotelli <pawamoy@pm.me>",
    "download_url": "https://files.pythonhosted.org/packages/e3/d8/36487aa5f32f50dbfab72317280dacbeec07a3907caf67bc4a7d3da57e73/mkdocstrings-0.24.0.tar.gz",
    "platform": null,
    "description": "# mkdocstrings\n\n[![ci](https://github.com/mkdocstrings/mkdocstrings/workflows/ci/badge.svg)](https://github.com/mkdocstrings/mkdocstrings/actions?query=workflow%3Aci)\n[![documentation](https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat)](https://mkdocstrings.github.io/)\n[![pypi version](https://img.shields.io/pypi/v/mkdocstrings.svg)](https://pypi.org/project/mkdocstrings/)\n[![conda version](https://img.shields.io/conda/vn/conda-forge/mkdocstrings)](https://anaconda.org/conda-forge/mkdocstrings)\n[![gitpod](https://img.shields.io/badge/gitpod-workspace-blue.svg?style=flat)](https://gitpod.io/#https://github.com/mkdocstrings/mkdocstrings)\n[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#mkdocstrings:gitter.im)\n\nAutomatic documentation from sources, for [MkDocs](https://mkdocs.org/).\nCome have a chat or ask questions on our [Gitter channel](https://gitter.im/mkdocstrings/community).\n\n---\n\n**[Features](#features)** - **[Requirements](#requirements)** - **[Installation](#installation)** - **[Quick usage](#quick-usage)**\n\n![mkdocstrings_gif1](https://user-images.githubusercontent.com/3999221/77157604-fb807480-6aa1-11ea-99e0-d092371d4de0.gif)\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/)\n  for the [Crystal](https://mkdocstrings.github.io/crystal/) and [Python](https://mkdocstrings.github.io/python/) 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- ~~**Watch source code directories:**~~\n  this feature was removed as it is now [built in MkDocs](https://www.mkdocs.org/user-guide/configuration/#watch). \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[Google](https://docs.kidger.site/jaxtyping/api/runtime-type-checking/),\n[Jitsi](https://jitsi.github.io/jiwer/reference/alignment/),\n[Microsoft](https://microsoft.github.io/presidio/api/analyzer_python/),\n[Prefect](https://docs.prefect.io/2.10.12/api-ref/prefect/agent/),\n[Pydantic](https://docs.pydantic.dev/dev-v2/api/main/),\n[and more...](https://github.com/mkdocstrings/mkdocstrings/network/dependents)\n\n## Installation\n\nWith `pip`:\n\n```bash\npip install mkdocstrings\n```\n\nYou can install support for specific languages using extras, for example:\n\n```bash\npip install 'mkdocstrings[crystal,python]'\n```\n\nSee the [available language handlers](https://mkdocstrings.github.io/handlers/overview/).\n\nWith `conda`:\n\n```bash\nconda install -c conda-forge mkdocstrings\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.24.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": "",
            "digests": {
                "blake2b_256": "261d8e196854491b8bebe8be4f170734f9c33891da9294f7036896e434ae0d49",
                "md5": "db3b21920c785986cdbb25894ebe8dcb",
                "sha256": "f4908560c10f587326d8f5165d1908817b2e280bbf707607f601c996366a2264"
            },
            "downloads": -1,
            "filename": "mkdocstrings-0.24.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "db3b21920c785986cdbb25894ebe8dcb",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 28068,
            "upload_time": "2023-11-14T17:46:17",
            "upload_time_iso_8601": "2023-11-14T17:46:17.961362Z",
            "url": "https://files.pythonhosted.org/packages/26/1d/8e196854491b8bebe8be4f170734f9c33891da9294f7036896e434ae0d49/mkdocstrings-0.24.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "e3d836487aa5f32f50dbfab72317280dacbeec07a3907caf67bc4a7d3da57e73",
                "md5": "0465149ccb682ddd648d027c044062e5",
                "sha256": "222b1165be41257b494a9d29b14135d2b7ca43f38161d5b10caae03b87bd4f7e"
            },
            "downloads": -1,
            "filename": "mkdocstrings-0.24.0.tar.gz",
            "has_sig": false,
            "md5_digest": "0465149ccb682ddd648d027c044062e5",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 31341,
            "upload_time": "2023-11-14T17:46:20",
            "upload_time_iso_8601": "2023-11-14T17:46:20.123585Z",
            "url": "https://files.pythonhosted.org/packages/e3/d8/36487aa5f32f50dbfab72317280dacbeec07a3907caf67bc4a7d3da57e73/mkdocstrings-0.24.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-11-14 17:46:20",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "mkdocstrings",
    "github_project": "mkdocstrings",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "mkdocstrings"
}
        
Elapsed time: 0.15509s