Skip to content

Commit 61e4e29

Browse files
oprypinoprypin
authored
docs: Details about autorefs, reorganize nav, update links & more
* Document more about autorefs, warn about the breaking change. * Linkify *Features* on the home page. * Mention Crystal handler (+add CSS for external link). * Split out a "theming" page from "usage" page. * Linkify sections via *mkdocs-section-index* plugin. * Update links after the site has moved into an org. * Indent some examples into an admonition. * Change "`mkdocstrings`" and "MkDocstrings" to "*mkdocstrings*". * Some minor rewordings. * Fix internal links to be MkDocs-native instead of assuming `use_directory_urls`.
1 parent b576abb commit 61e4e29

12 files changed

Lines changed: 372 additions & 310 deletions

File tree

‎.github/ISSUE_TEMPLATE/question.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,4 @@ assignees: ''
1010
**Add detailed information, like**
1111
- project folder structure (`tree -L 2`)
1212
- `mkdocs.yml` configuration file contents
13-
- `mkdocstrings` version: [e.g. 0.10.2]
13+
- *mkdocstrings* version: [e.g. 0.10.2]

‎CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
1010
<small>[Compare with 0.13.6](https://github.com/pawamoy/mkdocstrings/compare/0.13.6...0.14.0)</small>
1111

1212
Special thanks to Oleh [@oprypin](https://github.com/oprypin) Prypin who did an amazing job (this is a euphemism)
13-
at improving MkDocstrings, fixing hard-to-fix bugs with clever solutions, implementing great new features
13+
at improving *mkdocstrings*, fixing hard-to-fix bugs with clever solutions, implementing great new features
1414
and refactoring the code for better performance and readability! Thanks Oleh!
1515

1616
### Bug Fixes

‎README.md‎

Lines changed: 47 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
# mkdocstrings
22

3-
[![ci](https://github.com/pawamoy/mkdocstrings/workflows/ci/badge.svg)](https://github.com/pawamoy/mkdocstrings/actions?query=workflow%3Aci)
4-
[![documentation](https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat)](https://pawamoy.github.io/mkdocstrings/)
3+
[![ci](https://github.com/mkdocstrings/mkdocstrings/workflows/ci/badge.svg)](https://github.com/mkdocstrings/mkdocstrings/actions?query=workflow%3Aci)
4+
[![documentation](https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat)](https://mkdocstrings.github.io/)
55
[![pypi version](https://img.shields.io/pypi/v/mkdocstrings.svg)](https://pypi.org/project/mkdocstrings/)
66
[![conda version](https://img.shields.io/conda/vn/conda-forge/mkdocstrings)](https://anaconda.org/conda-forge/mkdocstrings)
77
[![gitter](https://badges.gitter.im/join%20chat.svg)](https://gitter.im/mkdocstrings/community)
88

9-
Automatic documentation from sources, for MkDocs.
9+
Automatic documentation from sources, for [MkDocs](https://mkdocs.org/).
1010

1111
---
1212

@@ -22,71 +22,88 @@ Automatic documentation from sources, for MkDocs.
2222

2323
## Features
2424

25-
- **Language agnostic:** just like `mkdocs`, `mkdocstrings` is written in Python but is language-agnostic.
26-
It means you can use it for any language, as long as you implement a
27-
[`handler`](https://pawamoy.github.io/mkdocstrings/reference/handlers/__init__/) for it.
28-
Currently, we only have a [Python handler](https://pawamoy.github.io/mkdocstrings/reference/handlers/python/).
29-
Maybe you'd like to contribute another one :wink:?
30-
- **Multiple themes support:** each handler can offer multiple themes. Currently, we offer the
25+
- [**Language-agnostic:**](https://mkdocstrings.github.io/handlers/overview/)
26+
just like *MkDocs*, *mkdocstrings* is written in Python but is language-agnostic.
27+
It means you can use it with any programming language, as long as there is a
28+
[**handler**](https://mkdocstrings.github.io/reference/handlers/base/) for it.
29+
The [Python handler](https://mkdocstrings.github.io/handlers/python/) is built-in.
30+
[Others](https://mkdocstrings.github.io/handlers/overview/) are external.
31+
Maybe you'd like to add another one to the list? :wink:
32+
33+
- [**Multiple themes support:**](https://mkdocstrings.github.io/theming/)
34+
each handler can offer multiple themes. Currently, we offer the
3135
:star: [Material theme](https://squidfunk.github.io/mkdocs-material/) :star:
3236
as well as basic support for the ReadTheDocs theme for the Python handler.
33-
- **Cross-references to other objects:** `mkdocstrings` makes it possible to reference other headings from your
34-
Markdown files with the classic Markdown syntax: `[identifier][]` or `[title][identifier]`. This feature is language
35-
agnostic as well: you can cross-reference any heading that appear in your Markdown pages.
36-
If the handler for a particular language renders headings for documented objects, you'll be able to reference them!
37-
- **Inline injection in Markdown:** instead of generating Markdown files, `mkdocstrings` allows you to inject
37+
38+
- [**Cross-links across pages:**](https://mkdocstrings.github.io/usage/#cross-references)
39+
*mkdocstrings* makes it possible to reference headings in other Markdown files with the classic Markdown linking
40+
syntax: `[identifier][]` or `[title][identifier]` -- and you don't need to remember which exact page this object was
41+
on. This works for any heading that's produced by a *mkdocstrings* language handler, and you can opt to include
42+
*any* Markdown heading into the global referencing scheme.
43+
44+
**Note**: in versions prior to 0.15 *all* Markdown headers were included, but now you need to
45+
[opt in](https://mkdocstrings.github.io/usage/#cross-references).
46+
47+
- [**Inline injection in Markdown:**](https://mkdocstrings.github.io/usage/)
48+
instead of generating Markdown files, *mkdocstrings* allows you to inject
3849
documentation anywhere in your Markdown contents. The syntax is simple: `::: identifier` followed by a 4-spaces
3950
indented YAML block. The identifier and YAML configuration will be passed to the appropriate handler
4051
to collect and render documentation.
41-
- **Global and local configuration:** each handler can be configured globally in `mkdocs.yml`, and locally for each
52+
53+
- [**Global and local configuration:**](https://mkdocstrings.github.io/usage/#global-options)
54+
each handler can be configured globally in `mkdocs.yml`, and locally for each
4255
"autodoc" instruction.
43-
- **Watch source code directories:** you can tell `mkdocstrings` to add directories to be watched by `mkdocs` when
56+
57+
- [**Watch source code directories:**](https://mkdocstrings.github.io/usage/#watch-directories)
58+
you can tell *mkdocstrings* to add directories to be watched by *MkDocs* when
4459
serving the documentation, for auto-reload.
45-
- **Sane defaults:** you should be able to just drop the plugin in your configuration and enjoy your auto-generated docs.
60+
61+
- **Reasonable defaults:**
62+
you should be able to just drop the plugin in your configuration and enjoy your auto-generated docs.
4663

4764
### Python handler features
4865

4966
- **Data collection from source code**: collection of the object-tree and the docstrings is done by
5067
[`pytkdocs`](https://github.com/pawamoy/pytkdocs). The following features are possible thanks to it:
51-
- **Support for type annotations:** `pytkdocs` collects your type annotations and `mkdocstrings` uses them
68+
- **Support for type annotations:** `pytkdocs` collects your type annotations and *mkdocstrings* uses them
5269
to display parameters types or return types.
5370
- **Recursive documentation of Python objects:** just use the module dotted-path as identifier, and you get the full
5471
module docs. You don't need to inject documentation for each class, function, etc.
5572
- **Support for documented attribute:** attributes (variables) followed by a docstring (triple-quoted string) will
5673
be recognized by `pytkdocs` in modules, classes and even in `__init__` methods.
5774
- **Support for objects properties:** `pytkdocs` detects if a method is a `staticmethod`, a `classmethod`, etc.,
5875
it also detects if a property is read-only or writable, and more! These properties will be displayed
59-
next to the object signature by `mkdocstrings`.
76+
next to the object signature by *mkdocstrings*.
6077
- **Google-style sections support in docstrings:** `pytkdocs` understands `Arguments:`, `Raises:`
61-
and `Returns:` sections, and returns structured data for `mkdocstrings` to render them.
78+
and `Returns:` sections, and returns structured data for *mkdocstrings* to render them.
6279
- **reStructuredText-style sections support in docstrings:** `pytkdocs` understands all the
6380
[reStructuredText fields](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html?highlight=python%20domain#info-field-lists),
64-
and returns structured data for `mkdocstrings` to render them.
81+
and returns structured data for *mkdocstrings* to render them.
6582
*Note: only RST **style** is supported, not the whole markup.*
6683
- **Admonition support in docstrings:** blocks like `Note: ` or `Warning: ` will be transformed
6784
to their [admonition](https://squidfunk.github.io/mkdocs-material/extensions/admonition/) equivalent.
6885
*We do not support nested admonitions in docstrings!*
6986
- **Support for reStructuredText in docstrings:** `pytkdocs` can parse simple RST.
70-
- **Every object has a TOC entry:** we render a heading for each object, meaning `mkdocs` picks them into the Table
71-
of Contents, which is nicely display by the Material theme. Thanks to `mkdocstrings` cross-reference ability,
87+
- **Every object has a TOC entry:** we render a heading for each object, meaning *MkDocs* picks them into the Table
88+
of Contents, which is nicely display by the Material theme. Thanks to *mkdocstrings* cross-reference ability,
7289
you can even reference other objects within your docstrings, with the classic Markdown syntax:
7390
`[this object][package.module.object]` or directly with `[package.module.object][]`
74-
- **Source code display:** `mkdocstrings` can add a collapsible div containing the highlighted source code
91+
- **Source code display:** *mkdocstrings* can add a collapsible div containing the highlighted source code
7592
of the Python object.
7693

77-
To get an example of what is possible, check `mkdocstrings`'
78-
own [documentation](https://pawamoy.github.io/mkdocstrings), auto-generated from sources by itself of course,
94+
To get an example of what is possible, check *mkdocstrings*'
95+
own [documentation](https://mkdocstrings.github.io/), auto-generated from sources by itself of course,
7996
and the following GIF:
8097

8198
![mkdocstrings_gif2](https://user-images.githubusercontent.com/3999221/77157838-7184db80-6aa2-11ea-9f9a-fe77405202de.gif)
8299

83100
## Roadmap
84101

85-
See the [Feature Roadmap issue](https://github.com/pawamoy/mkdocstrings/issues/183) on the bugtracker.
102+
See the [Feature Roadmap issue](https://github.com/mkdocstrings/mkdocstrings/issues/183) on the bugtracker.
86103

87104
## Requirements
88105

89-
`mkdocstrings` requires Python 3.6 or above.
106+
*mkdocstrings* requires Python 3.6 or above.
90107

91108
<details>
92109
<summary>To install Python 3.6, I recommend using <a href="https://github.com/pyenv/pyenv"><code>pyenv</code></a>.</summary>
@@ -141,10 +158,10 @@ plugins:
141158
142159
In one of your markdown files:
143160
144-
```yaml
161+
```markdown
145162
# Reference
146163

147164
::: my_library.my_module.my_class
148165
```
149166
150-
See the [Usage](https://pawamoy.github.io/mkdocstrings/usage) section of the docs for more examples!
167+
See the [Usage](https://mkdocstrings.github.io/usage) section of the docs for more examples!

‎docs/css/mkdocstrings.css‎

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎docs/css/style.css‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
/* Indentation for mkdocstrings items. */
2+
div.doc-contents:not(.first) {
3+
padding-left: 25px;
4+
border-left: 4px solid rgba(230, 230, 230);
5+
margin-bottom: 80px;
6+
}
7+
8+
/* Mark external links as such (also in nav) */
9+
a.external:hover::after, a.md-nav__link[href^="https:"]:hover::after {
10+
/* https://primer.style/octicons/link-external-16 */
11+
background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill="rgb(233, 235, 252)" d="M10.604 1h4.146a.25.25 0 01.25.25v4.146a.25.25 0 01-.427.177L13.03 4.03 9.28 7.78a.75.75 0 01-1.06-1.06l3.75-3.75-1.543-1.543A.25.25 0 0110.604 1zM3.75 2A1.75 1.75 0 002 3.75v8.5c0 .966.784 1.75 1.75 1.75h8.5A1.75 1.75 0 0014 12.25v-3.5a.75.75 0 00-1.5 0v3.5a.25.25 0 01-.25.25h-8.5a.25.25 0 01-.25-.25v-8.5a.25.25 0 01.25-.25h3.5a.75.75 0 000-1.5h-3.5z"></path></svg>');
12+
height: 0.8em;
13+
width: 0.8em;
14+
margin-left: 0.2em;
15+
content: ' ';
16+
display: inline-block;
17+
}

‎docs/handlers/overview.md‎

Lines changed: 19 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ A handler is what makes it possible to collect and render documentation for a pa
44

55
## Available handlers
66

7-
- [Python](../python)
7+
- [Python](python.md)
8+
- <a class="external" href="https://mkdocstrings.github.io/crystal/">Crystal</a>
89

910
## Custom handlers
1011

@@ -14,23 +15,13 @@ thanks to namespace packages. For more information about namespace packages,
1415

1516
### Packaging
1617

17-
For MkDocstrings, a custom handler package would have the following structure:
18+
For *mkdocstrings*, a custom handler package would have the following structure:
1819

1920
```
2021
📁 your_repository
21-
└── 📁 mkdocstrings
22-
   └── 📁 handlers
23-
└── 📄 custom_handler.py
24-
```
25-
26-
Or with a `src` layout:
27-
28-
```
29-
📁 your_repository
30-
└── 📁 src
31-
└── 📁 mkdocstrings
32-
   └── 📁 handlers
33-
└── 📄 custom_handler.py
22+
└─╴📁 mkdocstrings
23+
  └─╴📁 handlers
24+
└─╴📄 custom_handler.py
3425
```
3526

3627
**Note the absence of `__init__.py` modules!**
@@ -89,22 +80,21 @@ your renderer.
8980

9081
### Usage
9182

92-
When a custom handler is installed,
93-
it is then available to MkDocstrings.
83+
When a custom handler is installed, it is then available to *mkdocstrings*.
9484
You can configure it as usual:
9585

96-
```yaml
97-
# mkdocs.yml
98-
plugins:
99-
- mkdocstrings:
100-
handlers:
101-
custom_handler:
102-
selection:
103-
some_config_option: "a"
104-
rendering:
105-
other_config_option: 0
106-
handler_config_option: yes
107-
```
86+
!!! example "mkdocs.yml"
87+
```yaml
88+
plugins:
89+
- mkdocstrings:
90+
handlers:
91+
custom_handler:
92+
selection:
93+
some_config_option: "a"
94+
rendering:
95+
other_config_option: 0
96+
handler_config_option: yes
97+
```
10898

10999
...and use it in your autodoc instructions:
110100

‎docs/handlers/python.md‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,7 @@ in [Napoleon's documentation](https://sphinxcontrib-napoleon.readthedocs.io/en/l
116116

117117
##### Sections
118118

119-
Docstrings sections are parsed by `pytkdocs` and rendered by MkDocstrings.
119+
Docstrings sections are parsed by `pytkdocs` and rendered by *mkdocstrings*.
120120
Supported sections are:
121121

122122
- `Arguments` (or `Args`, `Parameters`, `Params`)
@@ -217,7 +217,7 @@ in [Sphinx's documentation](https://sphinx-rtd-tutorial.readthedocs.io/en/latest
217217
218218
##### Sections
219219
220-
Docstrings directives are parsed by `pytkdocs` and rendered by MkDocstrings.
220+
Docstrings directives are parsed by `pytkdocs` and rendered by *mkdocstrings*.
221221
Supported directives are:
222222

223223
- `param` (or `parameter`, `arg`, `argument`, `key`, `keyword`)
@@ -301,21 +301,21 @@ You may want to to generate documentation for a package while its dependencies a
301301
The Python handler provides itself no builtin way to mock libraries,
302302
but you can use the `setup_commands` to mock them manually:
303303

304-
```yaml
305-
# mkdocs.yml
306-
plugins:
307-
- mkdocstrings:
308-
handlers:
309-
python:
310-
setup_commands:
311-
- import sys
312-
- from unittest.mock import MagicMock as mock
313-
- sys.modules["lib1"] = mock()
314-
- sys.modules["lib2"] = mock()
315-
- sys.modules["lib2.module1"] = mock()
316-
- sys.modules["lib2.module1.moduleB"] = mock()
317-
# etc
318-
```
304+
!!! example "mkdocs.yml"
305+
```yaml
306+
plugins:
307+
- mkdocstrings:
308+
handlers:
309+
python:
310+
setup_commands:
311+
- import sys
312+
- from unittest.mock import MagicMock as mock
313+
- sys.modules["lib1"] = mock()
314+
- sys.modules["lib2"] = mock()
315+
- sys.modules["lib2.module1"] = mock()
316+
- sys.modules["lib2.module1.moduleB"] = mock()
317+
# etc
318+
```
319319

320320
## Recommended style (Material)
321321

0 commit comments

Comments
 (0)