diff --git a/.copier-answers.yml b/.copier-answers.yml index f8c074b7..35c682de 100644 --- a/.copier-answers.yml +++ b/.copier-answers.yml @@ -1,5 +1,5 @@ # Changes here will be overwritten by Copier -_commit: 0.15.7 +_commit: 0.15.8 _src_path: gh:pawamoy/copier-pdm author_email: pawamoy@pm.me author_fullname: Timothée Mazzucotelli diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8c0977e0..d3e0afb6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -51,8 +51,29 @@ jobs: - name: Check for breaking changes in the API run: pdm run duty check-api + exclude-test-jobs: + runs-on: ubuntu-latest + outputs: + jobs: ${{ steps.exclude-jobs.outputs.jobs }} + steps: + - id: exclude-jobs + run: | + if ${{ github.repository_owner == 'pawamoy-insiders' }}; then + echo 'jobs=[ + {"os": "macos-latest"}, + {"os": "windows-latest"}, + {"python-version": "3.8"}, + {"python-version": "3.9"}, + {"python-version": "3.10"}, + {"python-version": "3.11"} + ]' | tr -d '[:space:]' >> $GITHUB_OUTPUT + else + echo 'jobs=[]' >> $GITHUB_OUTPUT + fi + tests: + needs: exclude-test-jobs strategy: max-parallel: 4 matrix: @@ -66,6 +87,7 @@ jobs: - "3.9" - "3.10" - "3.11" + exclude: ${{ fromJSON(needs.exclude-test-jobs.outputs.jobs) }} runs-on: ${{ matrix.os }} diff --git a/.github/workflows/dists.yml b/.github/workflows/dists.yml index 13733a78..99758277 100644 --- a/.github/workflows/dists.yml +++ b/.github/workflows/dists.yml @@ -12,6 +12,8 @@ jobs: steps: - name: Checkout uses: actions/checkout@v3 + with: + fetch-depth: 0 - name: Setup Python uses: actions/setup-python@v3 - name: Install build diff --git a/CHANGELOG.md b/CHANGELOG.md index abf5e825..c2069f51 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,18 @@ 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.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) + +### Bug Fixes + +- Fix mkdocs and readthedocs themes support ([14f18b2](https://github.com/mkdocstrings/python/commit/14f18b219f67f9b6d154d4a52051d8d7d7c49348) by Timothée Mazzucotelli). + +### Code Refactoring + +- Improve display of paragraphs in docstring sections ([439f5e6](https://github.com/mkdocstrings/python/commit/439f5e6984fe94c28324ca57fbd1a52ef8f55b62) by Timothée Mazzucotelli). + ## [1.1.0](https://github.com/mkdocstrings/python/releases/tag/1.1.0) - 2023-05-25 [Compare with 1.0.0](https://github.com/mkdocstrings/python/compare/1.0.0...1.1.0) diff --git a/Makefile b/Makefile index 1b33c56b..cf75dae1 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,6 @@ .DEFAULT_GOAL := help SHELL := bash - -DUTY = $(shell [ -n "${VIRTUAL_ENV}" ] || echo pdm run) duty +DUTY := $(if $(VIRTUAL_ENV),,pdm run) duty args = $(foreach a,$($(subst -,_,$1)_args),$(if $(value $a),$a="$($a)")) check_quality_args = files diff --git a/docs/css/mkdocstrings.css b/docs/css/mkdocstrings.css index 559575fb..fe191c8c 100644 --- a/docs/css/mkdocstrings.css +++ b/docs/css/mkdocstrings.css @@ -8,19 +8,15 @@ div.doc-contents:not(.first) { a.external::after, a.autorefs-external::after { /* https://primer.style/octicons/arrow-up-right-24 */ - background-image: url('data:image/svg+xml,'); + mask-image: url('data:image/svg+xml,'); content: ' '; display: inline-block; vertical-align: middle; position: relative; - bottom: 0.1em; - margin-left: 0.2em; - margin-right: 0.1em; - height: 0.7em; - width: 0.7em; - border-radius: 100%; + height: 1em; + width: 1em; background-color: var(--md-typeset-a-color); } diff --git a/docs/schema.json b/docs/schema.json index 2d2a29f7..a34dc090 100644 --- a/docs/schema.json +++ b/docs/schema.json @@ -42,7 +42,7 @@ }, "paths": { "title": "Local absolute/relative paths (relative to mkdocs.yml) to search packages into.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#global-only-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#paths", "type": "array", "items": { "type": "string", @@ -51,7 +51,7 @@ }, "load_external_modules": { "title": "Load external modules to resolve aliases.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#global-only-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#load_external_modules", "type": "boolean", "default": false }, @@ -62,13 +62,17 @@ "properties": { "docstring_style": { "title": "The docstring style to use when parsing docstrings.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "enum": ["google", "numpy", "sphinx"], + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#docstring_style", + "enum": [ + "google", + "numpy", + "sphinx" + ], "default": "google" }, "docstring_options": { "title": "The options for the docstring parser.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#docstring_options", "default": null, "items": { "$ref": "https://raw.githubusercontent.com/mkdocstrings/griffe/master/docs/schema-docstrings-options.json" @@ -76,181 +80,188 @@ }, "show_root_heading": { "title": "Show the heading of the object at the root of the documentation tree.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_root_heading", "type": "boolean", "default": false }, "show_root_toc_entry": { "title": "If the root heading is not shown, at least add a ToC entry for it.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_root_toc_entry", "type": "boolean", "default": true }, "show_root_full_path": { "title": "Show the full Python path for the root object heading.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_root_full_path", "type": "boolean", "default": true }, "show_root_members_full_path": { "title": "Show the full Python path of the root members.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_root_members_full_path", "type": "boolean", "default": false }, "show_object_full_path": { "title": "Show the full Python path of every object.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_object_full_path", "type": "boolean", "default": false }, "show_category_heading": { "title": "When grouped by categories, show a heading for each category.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_category_heading", "type": "boolean", "default": false }, "show_if_no_docstring": { "title": "Show the object heading even if it has no docstring or children with docstrings.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_if_no_docstring", "type": "boolean", "default": false }, "show_signature": { "title": "Show methods and functions signatures.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#show_signature", "type": "boolean", "default": true }, "show_signature_annotations": { "title": "Show the type annotations in methods and functions signatures.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#show_signature_annotations", "type": "boolean", "default": false }, "separate_signature": { "title": "Whether to put the whole signature in a code block below the heading. If Black is installed, the signature is also formatted using it.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#separate_signature", "type": "boolean", "default": false }, "line_length": { "title": "Maximum line length when formatting code/signatures.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#line_length", "type": "integer", "default": 60 }, "merge_init_into_class": { "title": "Whether to merge the `__init__` method into the class' signature and docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#merge_init_into_class", "type": "boolean", "default": false }, "show_docstring_attributes": { "title": "Whether to display the \"Attributes\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_attributes", "type": "boolean", "default": true }, "show_docstring_description": { "title": "Whether to display the textual block (including admonitions) in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_description", "type": "boolean", "default": true }, "show_docstring_examples": { "title": "Whether to display the \"Examples\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_examples", "type": "boolean", "default": true }, "show_docstring_other_parameters": { "title": "Whether to display the \"Other Parameters\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_other_parameters", "type": "boolean", "default": true }, "show_docstring_parameters": { "title": "Whether to display the \"Parameters\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_parameters", "type": "boolean", "default": true }, "show_docstring_raises": { "title": "Whether to display the \"Raises\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_raises", "type": "boolean", "default": true }, "show_docstring_receives": { "title": "Whether to display the \"Receives\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_receives", "type": "boolean", "default": true }, "show_docstring_returns": { "title": "Whether to display the \"Returns\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_returns", "type": "boolean", "default": true }, "show_docstring_warns": { "title": "Whether to display the \"Warns\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_warns", "type": "boolean", "default": true }, "show_docstring_yields": { "title": "Whether to display the \"Yields\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_yields", "type": "boolean", "default": true }, "show_source": { "title": "Show the source code of this object.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/general/#show_source", "type": "boolean", "default": true }, "show_bases": { "title": "Show the base classes of a class.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/general/#show_bases", "type": "boolean", "default": true }, "show_submodules": { "title": "When rendering a module, show its submodules recursively.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#show_submodules", "type": "boolean", "default": false }, "group_by_category": { "title": "Group the object's children by categories: attributes, classes, functions, and modules.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#group_by_category", "type": "boolean", "default": true }, "heading_level": { "title": "The initial heading level to use.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#heading_level", "type": "integer", "default": 2 }, "members_order": { "title": "The members ordering to use.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "enum": ["alphabetical", "source"], + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#members_order", + "enum": [ + "alphabetical", + "source" + ], "default": "alphabetical" }, "docstring_section_style": { "title": "The style used to render docstring sections.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "enum": ["list", "spacy", "table"], + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#docstring_section_style", + "enum": [ + "list", + "spacy", + "table" + ], "default": "table" }, "members": { "title": "An explicit list of members to render.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#members", "type": [ "boolean", "array" @@ -259,22 +270,27 @@ }, "filters": { "title": "A list of filters applied to filter objects based on their name. A filter starting with `!` will exclude matching objects instead of including them. The `members` option takes precedence over `filters` (filters will still be applied recursively to lower members in the hierarchy).", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#filters", "type": "array", - "default": ["!^_[^_]"] + "default": [ + "!^_[^_]" + ] }, "annotations_path": { "title": "The verbosity for annotations path.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "enum": ["brief", "source"], + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#annotations_path", + "enum": [ + "brief", + "source" + ], "default": "brief" }, "preload_modules": { "title": "Pre-load modules. It permits to resolve aliases pointing to these modules (packages), and therefore render members of an object that are external to the given object (originating from another package).", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/general/#preload_modules", "type": "array", "items": { - "type":"string" + "type": "string" } } }, @@ -285,4 +301,4 @@ } }, "additionalProperties": false -} +} \ No newline at end of file diff --git a/docs/usage/customization.md b/docs/usage/customization.md index 99b33bd2..9caf6dbe 100644 --- a/docs/usage/customization.md +++ b/docs/usage/customization.md @@ -22,6 +22,7 @@ The following CSS classes are used in the generated HTML: - `doc-labels`: on `span`s wrapping the object's labels - `doc-label`: on `small` elements containing a label - `doc-label-LABEL`: same, where `LABEL` is replaced by the actual label +- `doc-md-description`: on `div`s containing HTML descriptions converted from Markdown docstrings /// admonition | Example with colorful labels type: example @@ -57,33 +58,7 @@ Here are some CSS rules for the [*Material for MkDocs*](https://squidfunk.github.io/mkdocs-material/) theme: ```css -/* Indentation. */ -div.doc-contents:not(.first) { - padding-left: 25px; - border-left: .05rem solid var(--md-typeset-table-color); -} - -/* Mark external links as such. */ -a.autorefs-external::after { - /* https://primer.style/octicons/arrow-up-right-24 */ - background-image: url('data:image/svg+xml,'); - content: ' '; - - display: inline-block; - vertical-align: middle; - position: relative; - bottom: 0.1em; - margin-left: 0.2em; - margin-right: 0.1em; - - height: 0.7em; - width: 0.7em; - border-radius: 100%; - background-color: var(--md-typeset-a-color); -} -a.autorefs-external:hover::after { - background-color: var(--md-accent-fg-color); -} +--8<-- "docs/css/mkdocstrings.css" ``` ### Recommended style (ReadTheDocs) diff --git a/scripts/gen_ref_nav.py b/scripts/gen_ref_nav.py index 97d8b5a7..69f6e3b9 100644 --- a/scripts/gen_ref_nav.py +++ b/scripts/gen_ref_nav.py @@ -5,6 +5,7 @@ import mkdocs_gen_files nav = mkdocs_gen_files.Nav() +mod_symbol = 'mod' for path in sorted(Path("src").rglob("*.py")): module_path = path.relative_to("src").with_suffix("") @@ -20,7 +21,8 @@ elif parts[-1].startswith("_"): continue - nav[parts] = doc_path.as_posix() + nav_parts = [f"{mod_symbol} {part}" for part in parts] + nav[tuple(nav_parts)] = doc_path.as_posix() with mkdocs_gen_files.open(full_doc_path, "w") as fd: ident = ".".join(parts) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html index 9a1409c0..20487f20 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html @@ -21,7 +21,11 @@ {% endwith %} {% endif %} - {{ attribute.description|convert_markdown(heading_level, html_id) }} + +
+ {{ attribute.description|convert_markdown(heading_level, html_id) }} +
+ {% endfor %} @@ -39,7 +43,10 @@ ({% include "expression.html" with context %}) {% endwith %} {% endif %} - – {{ attribute.description|convert_markdown(heading_level, html_id) }} + – +
+ {{ attribute.description|convert_markdown(heading_level, html_id) }} +
{% endfor %} @@ -58,7 +65,9 @@ {{ attribute.name }} - {{ attribute.description|convert_markdown(heading_level, html_id) }} +
+ {{ attribute.description|convert_markdown(heading_level, html_id) }} +

{% if attribute.annotation %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html index 4b9f7339..82fc493c 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html @@ -21,7 +21,11 @@ {% endwith %} {% endif %} - {{ parameter.description|convert_markdown(heading_level, html_id) }} + +

+ {{ parameter.description|convert_markdown(heading_level, html_id) }} +
+ {% endfor %} @@ -39,7 +43,10 @@ ({% include "expression.html" with context %}) {% endwith %} {% endif %} - – {{ parameter.description|convert_markdown(heading_level, html_id) }} + – +
+ {{ parameter.description|convert_markdown(heading_level, html_id) }} +
{% endfor %} @@ -58,7 +65,9 @@ {{ parameter.name }} - {{ parameter.description|convert_markdown(heading_level, html_id) }} +
+ {{ parameter.description|convert_markdown(heading_level, html_id) }} +

{% if parameter.annotation %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html index cc954596..b2b57509 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html @@ -22,7 +22,11 @@ {% endwith %} {% endif %} - {{ parameter.description|convert_markdown(heading_level, html_id) }} + +

+ {{ parameter.description|convert_markdown(heading_level, html_id) }} +
+ {% if parameter.default %} {% with expression = parameter.default %} @@ -49,7 +53,10 @@ ({% include "expression.html" with context %}) {% endwith %} {% endif %} - – {{ parameter.description|convert_markdown(heading_level, html_id) }} + – +
+ {{ parameter.description|convert_markdown(heading_level, html_id) }} +
{% endfor %} @@ -68,7 +75,9 @@ {{ parameter.name }} - {{ parameter.description|convert_markdown(heading_level, html_id) }} +
+ {{ parameter.description|convert_markdown(heading_level, html_id) }} +

{% if parameter.annotation %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html index 32ad3506..45832d1c 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html @@ -19,7 +19,11 @@ {% endwith %} {% endif %} - {{ raises.description|convert_markdown(heading_level, html_id) }} + +

+ {{ raises.description|convert_markdown(heading_level, html_id) }} +
+ {% endfor %} @@ -37,7 +41,9 @@ {% endwith %} – {% endif %} - {{ raises.description|convert_markdown(heading_level, html_id) }} +
+ {{ raises.description|convert_markdown(heading_level, html_id) }} +
{% endfor %} @@ -62,7 +68,9 @@ - {{ raises.description|convert_markdown(heading_level, html_id) }} +
+ {{ raises.description|convert_markdown(heading_level, html_id) }} +
{% endfor %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html index 7946329b..03b241cb 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html @@ -22,7 +22,11 @@ {% endwith %} {% endif %} - {{ receives.description|convert_markdown(heading_level, html_id) }} + +
+ {{ receives.description|convert_markdown(heading_level, html_id) }} +
+ {% endfor %} @@ -42,7 +46,10 @@ {% if receives.name %}){% endif %} {% endwith %} {% endif %} - – {{ receives.description|convert_markdown(heading_level, html_id) }} + – +
+ {{ receives.description|convert_markdown(heading_level, html_id) }} +
{% endfor %} @@ -71,7 +78,9 @@ {% endif %} - {{ receives.description|convert_markdown(heading_level, html_id) }} +
+ {{ receives.description|convert_markdown(heading_level, html_id) }} +
{% if receives.name and receives.annotation %}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html index 0d620d12..ad63db83 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html @@ -22,7 +22,11 @@ {% endwith %} {% endif %} - {{ returns.description|convert_markdown(heading_level, html_id) }} + +

+ {{ returns.description|convert_markdown(heading_level, html_id) }} +
+ {% endfor %} @@ -42,7 +46,10 @@ {% if returns.name %}){% endif %} {% endwith %} {% endif %} - – {{ returns.description|convert_markdown(heading_level, html_id) }} + – +
+ {{ returns.description|convert_markdown(heading_level, html_id) }} +
{% endfor %} @@ -71,7 +78,9 @@ {% endif %} - {{ returns.description|convert_markdown(heading_level, html_id) }} +
+ {{ returns.description|convert_markdown(heading_level, html_id) }} +
{% if returns.name and returns.annotation %}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html index e5a59a84..49ae4380 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html @@ -19,7 +19,11 @@ {% endwith %} {% endif %} - {{ warns.description|convert_markdown(heading_level, html_id) }} + +

+ {{ warns.description|convert_markdown(heading_level, html_id) }} +
+ {% endfor %} @@ -37,7 +41,9 @@ {% endwith %} – {% endif %} - {{ warns.description|convert_markdown(heading_level, html_id) }} +
+ {{ warns.description|convert_markdown(heading_level, html_id) }} +
{% endfor %} @@ -62,7 +68,9 @@ - {{ warns.description|convert_markdown(heading_level, html_id) }} +
+ {{ warns.description|convert_markdown(heading_level, html_id) }} +
{% endfor %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html index 22d6828f..93b3cfd2 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html @@ -22,7 +22,11 @@ {% endwith %} {% endif %} - {{ yields.description|convert_markdown(heading_level, html_id) }} + +
+ {{ yields.description|convert_markdown(heading_level, html_id) }} +
+ {% endfor %} @@ -42,7 +46,10 @@ {% if yields.name %}){% endif %} {% endwith %} {% endif %} - – {{ yields.description|convert_markdown(heading_level, html_id) }} + – +
+ {{ yields.description|convert_markdown(heading_level, html_id) }} +
{% endfor %} @@ -71,7 +78,9 @@ {% endif %} - {{ yields.description|convert_markdown(heading_level, html_id) }} +
+ {{ yields.description|convert_markdown(heading_level, html_id) }} +
{% if yields.name and yields.annotation %}

diff --git a/src/mkdocstrings_handlers/python/templates/material/style.css b/src/mkdocstrings_handlers/python/templates/material/style.css index 3b797587..7ddabb94 100644 --- a/src/mkdocstrings_handlers/python/templates/material/style.css +++ b/src/mkdocstrings_handlers/python/templates/material/style.css @@ -8,10 +8,10 @@ h5.doc-heading { word-break: normal !important; } -/* For pieces of Markdown rendered in table cells. */ -.doc-contents td p { - margin-top: 0 !important; - margin-bottom: 0 !important; +/* No line break before first paragraph of descriptions. */ +.doc-md-description, +.doc-md-description>p:first-child { + display: inline; } /* Max width for docstring sections tables. */ @@ -20,16 +20,12 @@ h5.doc-heading { display: table !important; width: 100%; } + .doc .md-typeset__table tr { display: table-row; } -/* Avoid line breaks in rendered fields. */ -.field-body p { - display: inline; -} - /* Defaults in Spacy table style. */ .doc-param-default { float: right; -} +} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/mkdocs/exceptions.html b/src/mkdocstrings_handlers/python/templates/mkdocs/exceptions.html deleted file mode 100644 index 677c867b..00000000 --- a/src/mkdocstrings_handlers/python/templates/mkdocs/exceptions.html +++ /dev/null @@ -1,7 +0,0 @@ -{{ log.debug() }} -

-
Exceptions:
- {% for exception in exceptions %} -
{{ ("`" + exception.annotation + "`: " + exception.description)|convert_markdown(heading_level, html_id) }}
- {% endfor %} -
diff --git a/src/mkdocstrings_handlers/python/templates/mkdocs/keyword_args.html b/src/mkdocstrings_handlers/python/templates/mkdocs/keyword_args.html deleted file mode 100644 index 16af0ea0..00000000 --- a/src/mkdocstrings_handlers/python/templates/mkdocs/keyword_args.html +++ /dev/null @@ -1,7 +0,0 @@ -{{ log.debug() }} -
-
Keyword arguments:
- {% for kwarg in kwargs %} -
{{ ("**" + kwarg.name + ":** " + ("`" + kwarg.annotation + "` – " if kwarg.annotation else "") + kwarg.description)|convert_markdown(heading_level, html_id) }}
- {% endfor %} -
diff --git a/src/mkdocstrings_handlers/python/templates/mkdocs/parameters.html b/src/mkdocstrings_handlers/python/templates/mkdocs/parameters.html deleted file mode 100644 index f745789b..00000000 --- a/src/mkdocstrings_handlers/python/templates/mkdocs/parameters.html +++ /dev/null @@ -1,7 +0,0 @@ -{{ log.debug() }} -
-
Arguments:
- {% for parameter in parameters %} -
{{ ("**" + parameter.name + ":** " + ("`" + parameter.annotation + "` – " if parameter.annotation else "") + parameter.description)|convert_markdown(heading_level, html_id) }}
- {% endfor %} -
diff --git a/src/mkdocstrings_handlers/python/templates/mkdocs/return.html b/src/mkdocstrings_handlers/python/templates/mkdocs/return.html deleted file mode 100644 index b38d61d1..00000000 --- a/src/mkdocstrings_handlers/python/templates/mkdocs/return.html +++ /dev/null @@ -1,5 +0,0 @@ -{{ log.debug() }} -
-
Returns:
-
{{ (("`" + return.annotation + "` – " if return.annotation else "") + return.description)|convert_markdown(heading_level, html_id) }}
-
diff --git a/src/mkdocstrings_handlers/python/templates/mkdocs/style.css b/src/mkdocstrings_handlers/python/templates/mkdocs/style.css deleted file mode 100644 index 9db45032..00000000 --- a/src/mkdocstrings_handlers/python/templates/mkdocs/style.css +++ /dev/null @@ -1,11 +0,0 @@ -.doc-contents { - padding-left: 20px; -} - -.doc-contents dd>p { - margin-bottom: 0.5rem; -} - -.doc-contents dl+dl { - margin-top: -0.5rem; -} diff --git a/src/mkdocstrings_handlers/python/templates/mkdocs/yield.html b/src/mkdocstrings_handlers/python/templates/mkdocs/yield.html deleted file mode 100644 index dad0f0e9..00000000 --- a/src/mkdocstrings_handlers/python/templates/mkdocs/yield.html +++ /dev/null @@ -1,5 +0,0 @@ -{{ log.debug() }} -
-
Yields:
-
{{ (("`" + yield.annotation + "` – " if yield.annotation else "") + yield.description)|convert_markdown(heading_level, html_id) }}
-
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html new file mode 100644 index 00000000..3ed566d5 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html @@ -0,0 +1,30 @@ +{{ log.debug() }} + + + + + + + + + + + +
{{ section.title or "Attributes:" }} +
    + {% for attribute in section.value %} +
  • + {{ attribute.name }} + {% if attribute.annotation %} + {% with expression = attribute.annotation %} + ({% include "expression.html" with context %}) + {% endwith %} + {% endif %} + – +
    + {{ attribute.description|convert_markdown(heading_level, html_id) }} +
    +
    • + {% endfor %} +
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html new file mode 100644 index 00000000..c5b4b039 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html @@ -0,0 +1,30 @@ +{{ log.debug() }} + + + + + + + + + + + +
{{ section.title or "Other parameters:" }} +
    + {% for parameter in section.value %} +
  • + {{ parameter.name }} + {% if parameter.annotation %} + {% with expression = parameter.annotation %} + ({% include "expression.html" with context %}) + {% endwith %} + {% endif %} + – +
    + {{ parameter.description|convert_markdown(heading_level, html_id) }} +
    +
    • + {% endfor %} +
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html new file mode 100644 index 00000000..b05733a7 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html @@ -0,0 +1,30 @@ +{{ log.debug() }} + + + + + + + + + + + +
{{ section.title or "Parameters:" }} +
    + {% for parameter in section.value %} +
  • + {{ parameter.name }} + {% if parameter.annotation %} + {% with expression = parameter.annotation %} + ({% include "expression.html" with context %}) + {% endwith %} + {% endif %} + – +
    + {{ parameter.description|convert_markdown(heading_level, html_id) }} +
    +
    • + {% endfor %} +
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html new file mode 100644 index 00000000..b744df22 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html @@ -0,0 +1,29 @@ +{{ log.debug() }} + + + + + + + + + + + +
{{ section.title or "Raises:" }} +
    + {% for raises in section.value %} +
  • + {% if raises.annotation %} + {% with expression = raises.annotation %} + {% include "expression.html" with context %} + {% endwith %} + {% endif %} + – +
    + {{ raises.description|convert_markdown(heading_level, html_id) }} +
    +
    • + {% endfor %} +
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html new file mode 100644 index 00000000..127bcd3c --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html @@ -0,0 +1,32 @@ +{{ log.debug() }} + + + + + + + + + + + +
{{ section.title or "Receives:" }} +
    + {% for receives in section.value %} +
  • + {% if receives.name %}{{ receives.name }}{% endif %} + {% if receives.annotation %} + {% with expression = receives.annotation %} + {% if receives.name %}({% endif %} + {% include "expression.html" with context %} + {% if receives.name %}){% endif %} + {% endwith %} + {% endif %} + – +
    + {{ receives.description|convert_markdown(heading_level, html_id) }} +
    +
    • + {% endfor %} +
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html new file mode 100644 index 00000000..92f29e31 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html @@ -0,0 +1,32 @@ +{{ log.debug() }} + + + + + + + + + + + +
{{ section.title or "Returns:" }} +
    + {% for returns in section.value %} +
  • + {% if returns.name %}{{ returns.name }}{% endif %} + {% if returns.annotation %} + {% with expression = returns.annotation %} + {% if returns.name %}({% endif %} + {% include "expression.html" with context %} + {% if returns.name %}){% endif %} + {% endwith %} + {% endif %} + – +
    + {{ returns.description|convert_markdown(heading_level, html_id) }} +
    +
    • + {% endfor %} +
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html new file mode 100644 index 00000000..12631784 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html @@ -0,0 +1,29 @@ +{{ log.debug() }} + + + + + + + + + + + +
{{ section.title or "Warns:" }} +
    + {% for warns in section.value %} +
  • + {% if warns.annotation %} + {% with expression = warns.annotation %} + {% include "expression.html" with context %} + {% endwith %} + {% endif %} + – +
    + {{ warns.description|convert_markdown(heading_level, html_id) }} +
    +
    • + {% endfor %} +
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html new file mode 100644 index 00000000..86e8ff7b --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html @@ -0,0 +1,32 @@ +{{ log.debug() }} + + + + + + + + + + + +
{{ section.title or "Yields:" }} +
    + {% for yields in section.value %} +
  • + {% if yields.name %}{{ yields.name }}{% endif %} + {% if yields.annotation %} + {% with expression = yields.annotation %} + {% if yields.name %}({% endif %} + {% include "expression.html" with context %} + {% if yields.name %}){% endif %} + {% endwith %} + {% endif %} + – +
    + {{ yields.description|convert_markdown(heading_level, html_id) }} +
    +
    • + {% endfor %} +
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/exceptions.html b/src/mkdocstrings_handlers/python/templates/readthedocs/exceptions.html deleted file mode 100644 index 715bdaf9..00000000 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/exceptions.html +++ /dev/null @@ -1,19 +0,0 @@ -{{ log.debug() }} - - - - - - - - - - - -
Exceptions: -
    - {% for exception in exceptions %} -
  • {{ ("`" + exception.annotation + "` – " + exception.description)|convert_markdown(heading_level, html_id) }}
    • - {% endfor %} -
-
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/other_parameters.html b/src/mkdocstrings_handlers/python/templates/readthedocs/other_parameters.html deleted file mode 100644 index 3c15308e..00000000 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/other_parameters.html +++ /dev/null @@ -1,19 +0,0 @@ -{{ log.debug() }} - - - - - - - - - - - -
Keyword arguments: -
    - {% for kwarg in kwargs %} -
  • {{ ("**" + kwarg.name + "**" + (" (`" + kwarg.annotation + "`)" if kwarg.annotation else "") + " – " + kwarg.description)|convert_markdown(heading_level, html_id) }}
    • - {% endfor %} -
-
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/parameters.html b/src/mkdocstrings_handlers/python/templates/readthedocs/parameters.html deleted file mode 100644 index 197a411e..00000000 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/parameters.html +++ /dev/null @@ -1,19 +0,0 @@ -{{ log.debug() }} - - - - - - - - - - - -
Parameters: -
    - {% for parameter in parameters %} -
  • {{ ("**" + parameter.name + "**" + (" (`" + parameter.annotation + "`)" if parameter.annotation else "") + " – " + parameter.description)|convert_markdown(heading_level, html_id) }}
    • - {% endfor %} -
-
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/returns.html b/src/mkdocstrings_handlers/python/templates/readthedocs/returns.html deleted file mode 100644 index 74bf65bb..00000000 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/returns.html +++ /dev/null @@ -1,17 +0,0 @@ -{{ log.debug() }} - - - - - - - - - - - -
Returns: -
    -
  • {{ ((("`" + return.annotation + "` – ") if return.annotation else "") + return.description)|convert_markdown(heading_level, html_id) }}
    • -
-
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/style.css b/src/mkdocstrings_handlers/python/templates/readthedocs/style.css index 2cafca81..e1ec823b 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/style.css +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/style.css @@ -3,10 +3,10 @@ word-break: normal !important; } -/* For pieces of Markdown rendered in table cells. */ -.doc-contents td p { - margin-top: 0 !important; - margin-bottom: 0 !important; +/* No line break before first paragraph of descriptions. */ +.doc-md-description, +.doc-md-description>p:first-child { + display: inline; } /* Avoid breaking code headings. */ @@ -18,10 +18,39 @@ .doc-contents .field-name { min-width: 100px; } -.doc-contents .field-name, .field-body { + +/* Other curious-spacing fixes. */ +.doc-contents .field-name, +.doc-contents .field-body { border: none !important; padding: 0 !important; } + +.doc-contents p { + margin: 1em 0 1em; +} + .doc-contents .field-list { margin: 0 !important; } + +.doc-contents pre { + padding: 0 !important; +} + +.doc-contents .wy-table-responsive { + margin-bottom: 0 !important; +} + +.doc-contents td.code { + padding: 0 !important; +} + +.doc-contents td.linenos { + padding: 0 8px !important; +} + +.doc-children, +footer { + margin-top: 20px; +} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/yields.html b/src/mkdocstrings_handlers/python/templates/readthedocs/yields.html deleted file mode 100644 index 7591f62c..00000000 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/yields.html +++ /dev/null @@ -1,17 +0,0 @@ -{{ log.debug() }} - - - - - - - - - - - -
Yields: -
    -
  • {{ ((("`" + yield.annotation + "` – ") if yield.annotation else "") + yield.description)|convert_markdown(heading_level, html_id) }}
    • -
-