diff --git a/CHANGELOG.md b/CHANGELOG.md index c2069f51..8cf8df1d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). +## [1.1.2](https://github.com/mkdocstrings/python/releases/tag/1.1.2) - 2023-06-04 + +[Compare with 1.1.1](https://github.com/mkdocstrings/python/compare/1.1.1...1.1.2) + +### Code Refactoring + +- Keep headings style consistent (CSS) ([92032e5](https://github.com/mkdocstrings/python/commit/92032e561861c3fc4e3fb0c6882bb076d0e6614d) by Timothée Mazzucotelli). + ## [1.1.1](https://github.com/mkdocstrings/python/releases/tag/1.1.1) - 2023-06-04 [Compare with 1.1.0](https://github.com/mkdocstrings/python/compare/1.1.0...1.1.1) diff --git a/docs/.glossary.md b/docs/.glossary.md index 2a273d7a..588674fb 100644 --- a/docs/.glossary.md +++ b/docs/.glossary.md @@ -7,5 +7,6 @@ [ReadTheDocs Sphinx theme]: https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html [Spacy's documentation]: https://spacy.io/api/doc/ [Black]: https://pypi.org/project/black/ +[Material for MkDocs]: https://squidfunk.github.io/mkdocs-material *[ToC]: Table of Contents diff --git a/docs/css/material.css b/docs/css/material.css index 98a7bed6..19c6b076 100644 --- a/docs/css/material.css +++ b/docs/css/material.css @@ -5,7 +5,7 @@ /* Custom admonition: preview */ :root { - --md-admonition-icon--preview: url('data:image/svg+xml;charset=utf-8,') + --md-admonition-icon--preview: url('data:image/svg+xml;charset=utf-8,'); } .md-typeset .admonition.preview, @@ -23,9 +23,4 @@ background-color: rgb(220, 139, 240); -webkit-mask-image: var(--md-admonition-icon--preview); mask-image: var(--md-admonition-icon--preview); -} - -/* Avoid breaking parameters name, etc. in documentation table cells. */ -td code { - word-break: normal !important; } \ No newline at end of file diff --git a/docs/usage/customization.md b/docs/usage/customization.md index 9caf6dbe..7fb0cae5 100644 --- a/docs/usage/customization.md +++ b/docs/usage/customization.md @@ -29,76 +29,41 @@ The following CSS classes are used in the generated HTML: //// tab | CSS ```css -.doc-label { border-radius: 15px; padding: 0 5px; } -.doc-label-special { background-color: blue; color: white; } -.doc-label-private { background-color: red; color: white; } -.doc-label-property { background-color: green; color: white; } -.doc-label-read-only { background-color: yellow; color: black; } +.doc-label { border-radius: 15px; padding: 2px 8px; font-weight: bold; } +.doc-label-special { background-color: #3330E4; color: white; } +.doc-label-private { background-color: #F637EC; color: white; } +.doc-label-property { background-color: #FBB454; color: black; } +.doc-label-read-only { background-color: #FAEA48; color: black; } ``` //// //// tab | Result -

- special - private - property - read-only -

+

+

+ special + private + property + read-only +

+

//// /// - -### Recommended style (Material) - -Here are some CSS rules for the -[*Material for MkDocs*](https://squidfunk.github.io/mkdocs-material/) theme: - -```css ---8<-- "docs/css/mkdocstrings.css" -``` - -### Recommended style (ReadTheDocs) - -Here are some CSS rules for the built-in *ReadTheDocs* theme: - -```css -/* Indentation. */ -div.doc-contents:not(.first) { - padding-left: 25px; - border-left: .05rem solid rgba(200, 200, 200, 0.2); -} -``` - ## Templates Templates are organized into the following tree: -```tree result="text" -theme/ - attribute.html - children.html - class.html - docstring/ - admonition.html - attributes.html - examples.html - other_parameters.html - parameters.html - raises.html - receives.html - returns.html - warns.html - yields.html - docstring.html - expression.html - function.html - labels.html - module.html - signature.html +```python exec="1" result="tree" +from pathlib import Path + +basedir = "src/mkdocstrings_handlers/python/templates/material" +print("theme/") +for filepath in sorted(path for path in Path(basedir).rglob("*") if "_base" not in str(path) and path.suffix != ".css"): + print(" " * (len(filepath.relative_to(basedir).parent.parts) + 1) + filepath.name + ("/" if filepath.is_dir() else "")) ``` See them [in the repository](https://github.com/mkdocstrings/python/tree/master/src/mkdocstrings_handlers/python/templates/). @@ -131,3 +96,29 @@ without having to fully copy-paste it into your project: ``` WARNING: **Block-level customization is not ready yet. We welcome [suggestions](https://github.com/mkdocstrings/python/issues/new).** + +## Style recommendations + + + +### Material + +Here are some CSS rules for the [Material for MkDocs] theme: + +```css +--8<-- "docs/css/mkdocstrings.css" +``` + + + +### ReadTheDocs + +Here are some CSS rules for the built-in ReadTheDocs theme: + +```css +/* Indentation. */ +div.doc-contents:not(.first) { + padding-left: 25px; + border-left: .05rem solid rgba(200, 200, 200, 0.2); +} +``` \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/material/style.css b/src/mkdocstrings_handlers/python/templates/material/style.css index 7ddabb94..f1da921a 100644 --- a/src/mkdocstrings_handlers/python/templates/material/style.css +++ b/src/mkdocstrings_handlers/python/templates/material/style.css @@ -1,9 +1,4 @@ -/* Don't capitalize names. */ -h5.doc-heading { - text-transform: none !important; -} - -/* Avoid breaking parameters name, etc. in table cells. */ +/* Avoid breaking parameter names, etc. in table cells. */ .doc-contents td code { word-break: normal !important; } @@ -28,4 +23,41 @@ h5.doc-heading { /* Defaults in Spacy table style. */ .doc-param-default { float: right; +} + +/* Keep headings consistent. */ +h1.doc-heading, +h2.doc-heading, +h3.doc-heading, +h4.doc-heading, +h5.doc-heading, +h6.doc-heading { + font-weight: 400; + line-height: 1.5; + color: inherit; + text-transform: none; +} + +h1.doc-heading { + font-size: 1.6rem; +} + +h2.doc-heading { + font-size: 1.2rem; +} + +h3.doc-heading { + font-size: 1.15rem; +} + +h4.doc-heading { + font-size: 1.10rem; +} + +h5.doc-heading { + font-size: 1.05rem; +} + +h6.doc-heading { + font-size: 1rem; } \ No newline at end of file