Repository files navigation

Automatic documentation from sources, forMkDocs.Come have a chat or ask questions on ourGitter channel.

Features -Installation -Quick usage

• Language-agnostic:just likeMkDocs,mkdocstrings is written in Python but is language-agnostic.It means you can use it with any programming language, as long as there is ahandler for it.We currently havehandlers for theC,Crystal,GitHub Actions,Python,MATLAB,TypeScript, andVBA languages,as well as forshell scripts/libraries.Maybe you'd like to add another one to the list? 😉

• Multiple themes support:each handler can offer multiple themes. Currently, we offer the:star:Material theme ⭐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 linkingsyntax:[identifier][] or[title][identifier] -- and you don't need to remember which exact page this object wason. This works for any heading that's produced by amkdocstrings language handler, and you can opt to includeany Markdown heading into the global referencing scheme.

  Note: in versions prior to 0.15all Markdown headers were included, but now you need toopt in.

• Cross-references across sites:similarly toSphinx's intersphinx extension,mkdocstrings can reference API items from other libraries, given they provide an inventory and you loadthat inventory in your MkDocs configuration.

• Inline injection in Markdown:instead of generating Markdown files,mkdocstrings allows you to injectdocumentation anywhere in your Markdown contents. The syntax is simple:::: identifier followed by a 4-spacesindented YAML block. The identifier and YAML configuration will be passed to the appropriate handlerto collect and render documentation.

• Global and local configuration:each handler can be configured globally inmkdocs.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.

mkdocstrings is used by well-known companies, projects and scientific teams:Ansible,Apache,FastAPI,Google,IBM,Jitsi,Microsoft,NVIDIA,Prefect,Pydantic,Textual,and more...

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

pip install'mkdocstrings[python]'

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

pip install mkdocstrings-python

This will give you more control over the accepted range of versions for the handlers themselves.

See theofficial language handlers.

Withconda:

conda install -c conda-forge mkdocstrings mkdocstrings-python

Inmkdocs.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 theUsage section of the docs for more examples!