|
| 1 | +# Customization |
| 2 | + |
| 3 | +It is possible to customize the output of the generated documentation with CSS |
| 4 | +and/or by overriding templates. |
| 5 | + |
| 6 | +## CSS classes |
| 7 | + |
| 8 | +The following CSS classes are used in the generated HTML: |
| 9 | + |
| 10 | +- `doc`: on all the following elements |
| 11 | +- `doc-children`: on `div`s containing the children of an object |
| 12 | +- `doc-object`: on `div`s containing an object |
| 13 | + - `doc-attribute`: on `div`s containing an attribute |
| 14 | + - `doc-class`: on `div`s containing a class |
| 15 | + - `doc-function`: on `div`s containing a function |
| 16 | + - `doc-module`: on `div`s containing a module |
| 17 | +- `doc-heading`: on objects headings |
| 18 | + - `doc-object-name`: on `span`s wrapping objects names/paths in the heading |
| 19 | + - `doc-KIND-name`: as above, specific to the kind of object (module, class, function, attribute) |
| 20 | +- `doc-contents`: on `div`s wrapping the docstring then the children (if any) |
| 21 | + - `first`: same, but only on the root object's contents `div` |
| 22 | +- `doc-labels`: on `span`s wrapping the object's labels |
| 23 | + - `doc-label`: on `small` elements containing a label |
| 24 | + - `doc-label-LABEL`: same, where `LABEL` is replaced by the actual label |
| 25 | + |
| 26 | +!!! example "Example with colorful labels" |
| 27 | + === "CSS" |
| 28 | + ```css |
| 29 | + .doc-label { border-radius: 15px; padding: 0 5px; } |
| 30 | + .doc-label-special { background-color: blue; color: white; } |
| 31 | + .doc-label-private { background-color: red; color: white; } |
| 32 | + .doc-label-property { background-color: green; color: white; } |
| 33 | + .doc-label-read-only { background-color: yellow; color: black; } |
| 34 | + ``` |
| 35 | + |
| 36 | + === "Result" |
| 37 | + <style> |
| 38 | + .lbl { border-radius: 15px; padding: 0 5px; } |
| 39 | + </style> |
| 40 | + <h3 style="margin: 0;"><span> |
| 41 | + <small class="lbl" style="background-color: blue; color: white !important;">special</small> |
| 42 | + <small class="lbl" style="background-color: red; color: white !important;">private</small> |
| 43 | + <small class="lbl" style="background-color: green; color: white !important;">property</small> |
| 44 | + <small class="lbl" style="background-color: yellow; color: black !important;">read-only</small> |
| 45 | + </span></h3> |
| 46 | + |
| 47 | + |
| 48 | +### Recommended style (Material) |
| 49 | + |
| 50 | +Here are some CSS rules for the |
| 51 | +[*Material for MkDocs*](https://squidfunk.github.io/mkdocs-material/) theme: |
| 52 | + |
| 53 | +```css |
| 54 | +/* Indentation. */ |
| 55 | +div.doc-contents:not(.first) { |
| 56 | + padding-left: 25px; |
| 57 | + border-left: .05rem solid var(--md-typeset-table-color); |
| 58 | +} |
| 59 | + |
| 60 | +/* Mark external links as such. */ |
| 61 | +a.autorefs-external::after { |
| 62 | + /* https://primer.style/octicons/arrow-up-right-24 */ |
| 63 | + background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="rgb(0, 0, 0)" d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>'); |
| 64 | + content: ' '; |
| 65 | + |
| 66 | + display: inline-block; |
| 67 | + position: relative; |
| 68 | + top: 0.1em; |
| 69 | + margin-left: 0.2em; |
| 70 | + margin-right: 0.1em; |
| 71 | + |
| 72 | + height: 1em; |
| 73 | + width: 1em; |
| 74 | + border-radius: 100%; |
| 75 | + background-color: var(--md-typeset-a-color); |
| 76 | +} |
| 77 | +a.autorefs-external:hover::after { |
| 78 | + background-color: var(--md-accent-fg-color); |
| 79 | +} |
| 80 | + |
| 81 | +``` |
| 82 | + |
| 83 | +### Recommended style (ReadTheDocs) |
| 84 | + |
| 85 | +Here are some CSS rules for the built-in *ReadTheDocs* theme: |
| 86 | + |
| 87 | +```css |
| 88 | +/* Indentation. */ |
| 89 | +div.doc-contents:not(.first) { |
| 90 | + padding-left: 25px; |
| 91 | + border-left: .05rem solid rgba(200, 200, 200, 0.2); |
| 92 | +} |
| 93 | +``` |
| 94 | + |
| 95 | +## Templates |
| 96 | + |
| 97 | +Templates are organized into the following tree: |
| 98 | + |
| 99 | +``` |
| 100 | +📁 theme/ |
| 101 | +├── 📄 attribute.html |
| 102 | +├── 📄 children.html |
| 103 | +├── 📄 class.html |
| 104 | +├── 📁 docstring/ |
| 105 | +│ ├── 📄 admonition.html |
| 106 | +│ ├── 📄 attributes.html |
| 107 | +│ ├── 📄 examples.html |
| 108 | +│ ├── 📄 other_parameters.html |
| 109 | +│ ├── 📄 parameters.html |
| 110 | +│ ├── 📄 raises.html |
| 111 | +│ ├── 📄 receives.html |
| 112 | +│ ├── 📄 returns.html |
| 113 | +│ ├── 📄 warns.html |
| 114 | +│ └── 📄 yields.html |
| 115 | +├── 📄 docstring.html |
| 116 | +├── 📄 expression.html |
| 117 | +├── 📄 function.html |
| 118 | +├── 📄 labels.html |
| 119 | +├── 📄 module.html |
| 120 | +└── 📄 signature.html |
| 121 | +``` |
| 122 | + |
| 123 | +See them [in the repository](https://github.com/mkdocstrings/python/tree/master/src/mkdocstrings_handlers/python/templates/). |
| 124 | +See the general *mkdocstrings* documentation to learn how to override them: https://mkdocstrings.github.io/theming/#templates. |
| 125 | + |
| 126 | +In preparation for Jinja2 blocks, which will improve customization, |
| 127 | +each one of these templates extends in fact a base version in `theme/_base`. Example: |
| 128 | + |
| 129 | +```html+jinja title="theme/docstring/admonition.html" |
| 130 | +{% extends "_base/docstring/admonition.html" %} |
| 131 | +``` |
| 132 | + |
| 133 | +```html+jinja title="theme/_base/docstring/admonition.html" |
| 134 | +{{ log.debug() }} |
| 135 | +<details class="{{ section.value.kind }}"> |
| 136 | + <summary>{{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }}</summary> |
| 137 | + {{ section.value.contents|convert_markdown(heading_level, html_id) }} |
| 138 | +</details> |
| 139 | +``` |
| 140 | + |
| 141 | +It means you will be able to customize only *parts* of a template |
| 142 | +without having to fully copy-paste it in your project: |
| 143 | + |
| 144 | +```jinja title="templates/theme/docstring.html" |
| 145 | +{% extends "_base/docstring.html" %} |
| 146 | +{% block contents %} |
| 147 | + {{ block.super }} |
| 148 | + Additional contents |
| 149 | +{% endblock contents %} |
| 150 | +``` |
| 151 | + |
| 152 | +WARNING: **Block-level customization is not ready yet. We welcome [suggestions](https://github.com/mkdocstrings/python/issues/new).** |
0 commit comments