Skip to main content

Automatic documentation from sources, for MkDocs.

Project description

mkdocstrings

ci documentation pypi version conda version gitter

Automatic documentation from sources, for MkDocs. Come have a chat or ask questions on our Gitter channel.


Features - Installation - Quick usage

mkdocstrings_gif1

Features

  • Language-agnostic: 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 for it. We currently have handlers for the C, Crystal, Python, TypeScript, and VBA languages, as well as for shell scripts/libraries. Maybe you'd like to add another one to the list? :wink:

  • Multiple themes support: each handler can offer multiple themes. Currently, we offer the :star: Material theme :star: as well as basic support for the ReadTheDocs and MkDocs themes for the Python handler.

  • Cross-references across pages: 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.

  • Cross-references across sites: similarly to Sphinx's intersphinx extension, 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: 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: 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, Apache, FastAPI, Google, Jitsi, Microsoft, Prefect, Pydantic, and more...

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. For example, to install it with Python support:

pip install 'mkdocstrings[python]'

Alternatively, you can directly install the language handlers themselves, which depend on mkdocstrings anyway:

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.


With conda:

conda install -c conda-forge mkdocstrings mkdocstrings-python

Quick usage

In mkdocs.yml:

site_name: "My Library"

theme:
  name: "material"

plugins:
- search
- mkdocstrings

In one of your markdown files:

# Reference

::: my_library.my_module.my_class

See the Usage section of the docs for more examples!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocstrings-0.27.0.tar.gz (94.8 kB view details)

Uploaded Source

Built Distribution

mkdocstrings-0.27.0-py3-none-any.whl (30.7 kB view details)

Uploaded Python 3

File details

Details for the file mkdocstrings-0.27.0.tar.gz.

File metadata

  • Download URL: mkdocstrings-0.27.0.tar.gz
  • Upload date:
  • Size: 94.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for mkdocstrings-0.27.0.tar.gz
Algorithm Hash digest
SHA256 16adca6d6b0a1f9e0c07ff0b02ced8e16f228a9d65a37c063ec4c14d7b76a657
MD5 615b82d682c9c9b88783b9e0ced1474c
BLAKE2b-256 e25a5de70538c2cefae7ac3a15b5601e306ef3717290cb2aab11d51cbbc2d1c0

See more details on using hashes here.

Provenance

File details

Details for the file mkdocstrings-0.27.0-py3-none-any.whl.

File metadata

File hashes

Hashes for mkdocstrings-0.27.0-py3-none-any.whl
Algorithm Hash digest
SHA256 6ceaa7ea830770959b55a16203ac63da24badd71325b96af950e59fd37366332
MD5 cab52139706539f48d57fdaadfc8411a
BLAKE2b-256 cd104c27c3063c2b3681a4b7942f8dbdeb4fa34fecb2c19b594e7345ebf4f86f

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page