From b891ffe4173a35b125a25368cb6d34f8661b0d67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 6 Feb 2022 20:19:34 +0100 Subject: [PATCH 1/9] chore: We are ready to deploy docs --- duties.py | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/duties.py b/duties.py index f23da62d..3ad804dd 100644 --- a/duties.py +++ b/duties.py @@ -286,11 +286,7 @@ def docs_deploy(ctx): Arguments: ctx: The context instance (passed automatically). """ - ctx.run( - "echo 'Not ready yet! It would override mkdocstrings.github.io/python!' && false", - title="Deploying documentation", - nofail=True, - ) + ctx.run("mkdocs gh-deploy", title="Deploying documentation") @duty From fb6c8360caa42ffbcfa2a2f9db84560f379048ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 7 Feb 2022 17:43:28 +0100 Subject: [PATCH 2/9] docs: Improve landing page --- README.md | 36 +++++++++++++++++++++++++++++++++++- docs/usage.md | 6 +++--- 2 files changed, 38 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 38fbb568..7eb542c8 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,9 @@ A Python handler for [mkdocstrings](https://github.com/mkdocstrings/mkdocstrings). + +![mkdocstrings_python_gif](https://user-images.githubusercontent.com/3999221/77157838-7184db80-6aa2-11ea-9f9a-fe77405202de.gif) + ## Requirements Python for mkdocstrings requires Python 3.7 or above. @@ -54,4 +57,35 @@ You can also explicitely depend on the handler: dependencies = [ "mkdocstrings-python", ] -``` \ No newline at end of file +``` + +## Features + +- **Data collection from source code**: collection of the object-tree and the docstrings is done thanks to + [Griffe](https://github.com/mkdocstrings/griffe). + +- **Support for type annotations:** Griffe collects your type annotations and *mkdocstrings* uses them + to display parameters types or return types. It is even able to automatically add cross-references + to other objects from your API, from the standard library or from third-party libraries! + See [how to load inventories](https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories) to enable it. + +- **Recursive documentation of Python objects:** just use the module dotted-path as identifier, and you get the full + module docs. You don't need to inject documentation for each class, function, etc. + +- **Support for documented attributes:** attributes (variables) followed by a docstring (triple-quoted string) will + be recognized by Griffe in modules, classes and even in `__init__` methods. + +- **Multiple docstring-styles support:** common support for Google-style, Numpydoc-style, + and Sphinx-style docstrings. See [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/) on docstrings support. + +- **Admonition support in Google docstrings:** blocks like `Note:` or `Warning:` will be transformed + to their [admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) equivalent. + *We do not support nested admonitions in docstrings!* + +- **Every object has a TOC entry:** we render a heading for each object, meaning *MkDocs* picks them into the Table + of Contents, which is nicely display by the Material theme. Thanks to *mkdocstrings* cross-reference ability, + you can reference other objects within your docstrings, with the classic Markdown syntax: + `[this object][package.module.object]` or directly with `[package.module.object][]` + +- **Source code display:** *mkdocstrings* can add a collapsible div containing the highlighted source code + of the Python object. diff --git a/docs/usage.md b/docs/usage.md index fd9f203a..363b7086 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,9 +1,9 @@ -## Handler options - -!!! warning "This the documentation for the NEW, EXPERIMENTAL Python handler." +!!! warning "This is the documentation for the NEW, EXPERIMENTAL Python handler." To read the documentation for the LEGACY handler, go to the [legacy handler documentation](https://mkdocstrings.github.io/python-legacy). +## Handler options + Like every handler, the Python handler accepts the common [`selection`](#selection) and [`rendering`](#rendering) options, both as **global** and **local** options. From a282048bc14059949d0bf4e63ede734f6664917e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 7 Feb 2022 17:45:25 +0100 Subject: [PATCH 3/9] chore: Template upgrade --- .copier-answers.yml | 11 ++++++----- .github/ISSUE_TEMPLATE/bug_report.md | 2 +- README.md | 4 ++-- mkdocs.yml | 8 +------- pyproject.toml | 5 ++++- scripts/multirun.sh | 11 ++++++++++- tests/__init__.py | 2 +- 7 files changed, 25 insertions(+), 18 deletions(-) diff --git a/.copier-answers.yml b/.copier-answers.yml index a57431e6..f2e7c7ac 100644 --- a/.copier-answers.yml +++ b/.copier-answers.yml @@ -1,19 +1,20 @@ # Changes here will be overwritten by Copier -_commit: 0.8.1 +_commit: 0.9.0 _src_path: gh:pawamoy/copier-pdm author_email: pawamoy@pm.me -author_fullname: "Timoth\xE9e Mazzucotelli" +author_fullname: Timothée Mazzucotelli author_username: pawamoy copyright_date: '2021' -copyright_holder: "Timoth\xE9e Mazzucotelli" +copyright_holder: Timothée Mazzucotelli copyright_holder_email: pawamoy@pm.me copyright_license: ISC License project_description: A Python handler for mkdocstrings. -project_name: Python for mkdocstrings +project_name: mkdocstrings-python python_package_command_line_name: mkdocstrings-python python_package_distribution_name: mkdocstrings-python -python_package_import_name: mkdocstrings +python_package_import_name: mkdocstrings_handlers repository_name: python repository_namespace: mkdocstrings repository_provider: github.com use_precommit: false + diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 77abb0a8..ad93416e 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -24,7 +24,7 @@ A clear and concise description of what you expected to happen. If applicable, add screenshots to help explain your problem. **System (please complete the following information):** -- `Python for mkdocstrings` version: [e.g. 0.2.1] +- `mkdocstrings-python` version: [e.g. 0.2.1] - Python version: [e.g. 3.8] - OS: [Windows/Linux] diff --git a/README.md b/README.md index 7eb542c8..3cb3b334 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Python for mkdocstrings +# mkdocstrings-python [![ci](https://github.com/mkdocstrings/python/workflows/ci/badge.svg)](https://github.com/mkdocstrings/python/actions?query=workflow%3Aci) [![documentation](https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat)](https://mkdocstrings.github.io/python/) @@ -13,7 +13,7 @@ A Python handler for [mkdocstrings](https://github.com/mkdocstrings/mkdocstrings ## Requirements -Python for mkdocstrings requires Python 3.7 or above. +mkdocstrings-python requires Python 3.7 or above.
To install Python 3.7, I recommend using pyenv. diff --git a/mkdocs.yml b/mkdocs.yml index 0137f07c..e945e192 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: "Python for mkdocstrings" +site_name: "mkdocstrings-python" site_description: "A Python handler for mkdocstrings." site_url: "https://mkdocstrings.github.io/python" repo_url: "https://github.com/mkdocstrings/python" @@ -70,12 +70,6 @@ plugins: - coverage - section-index - mkdocstrings: - handlers: - python: - import: - - https://mkdocstrings.github.io/objects.inv - rendering: - show_submodules: no watch: - src/mkdocstrings_handlers diff --git a/pyproject.toml b/pyproject.toml index 462b077f..05c4c4e8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,6 +44,9 @@ Discussions = "https://github.com/mkdocstrings/python/discussions" Gitter = "https://gitter.im/python/community" Funding = "https://github.com/sponsors/mkdocstrings" +[project.scripts] +mkdocstrings-python = "mkdocstrings_handlers.cli:main" + [tool.pdm] version = {use_scm = true} includes = ["src/mkdocstrings_handlers"] @@ -109,5 +112,5 @@ multi_line_output = 3 force_single_line = false balanced_wrapping = true default_section = "THIRDPARTY" -known_first_party = "mkdocstrings" +known_first_party = "mkdocstrings_handlers" include_trailing_comma = true diff --git a/scripts/multirun.sh b/scripts/multirun.sh index 609dfd44..a55d1746 100755 --- a/scripts/multirun.sh +++ b/scripts/multirun.sh @@ -3,10 +3,19 @@ set -e PYTHON_VERSIONS="${PYTHON_VERSIONS-3.7 3.8 3.9 3.10 3.11}" +restore_previous_python_version() { + if pdm use -f "$1" &>/dev/null; then + echo "> Restored previous Python version: ${1##*/}" + fi +} + if [ -n "${PYTHON_VERSIONS}" ]; then + old_python_version="$(pdm config python.path)" + echo "> Currently selected Python version: ${old_python_version##*/}" + trap "restore_previous_python_version ${old_python_version}" EXIT for python_version in ${PYTHON_VERSIONS}; do if pdm use -f "python${python_version}" &>/dev/null; then - echo "> pdm run $@ (Python ${python_version})" + echo "> pdm run $@ (python${python_version})" pdm run "$@" else echo "> pdm use -f python${python_version}: Python interpreter not available?" >&2 diff --git a/tests/__init__.py b/tests/__init__.py index 9d29353a..4d444b8c 100644 --- a/tests/__init__.py +++ b/tests/__init__.py @@ -1,4 +1,4 @@ -"""Tests suite for `mkdocstrings`.""" +"""Tests suite for `mkdocstrings_handlers`.""" from pathlib import Path From 5e4a50af27a6afcf994bfdfe88cd160a31fb4246 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 7 Feb 2022 17:47:53 +0100 Subject: [PATCH 4/9] chore: Prevent Copier unwanted updates --- mkdocs.yml | 6 ++++++ pyproject.toml | 3 --- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index e945e192..1ff48e02 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,6 +70,12 @@ plugins: - coverage - section-index - mkdocstrings: + handlers: + python: + import: + - https://mkdocstrings.github.io/objects.inv + rendering: + show_submodules: no watch: - src/mkdocstrings_handlers diff --git a/pyproject.toml b/pyproject.toml index 05c4c4e8..7f7b5c29 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,9 +44,6 @@ Discussions = "https://github.com/mkdocstrings/python/discussions" Gitter = "https://gitter.im/python/community" Funding = "https://github.com/sponsors/mkdocstrings" -[project.scripts] -mkdocstrings-python = "mkdocstrings_handlers.cli:main" - [tool.pdm] version = {use_scm = true} includes = ["src/mkdocstrings_handlers"] From 3993b8e7fb4d96c3dc5b35dd4bee339ddae01dbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 7 Feb 2022 17:49:00 +0100 Subject: [PATCH 5/9] docs: Point navbar to mkdocstrings docs --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 1ff48e02..57abdb17 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,7 +18,7 @@ nav: - Contributing: contributing.md - Code of Conduct: code_of_conduct.md - Coverage report: coverage.md -- Author's website: https://pawamoy.github.io/ +- mkdocstrings: https://mkdocstrings.github.io/ theme: name: material From af9e80b6c8fd9841f89c942f09245d8dbb27b91b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 7 Feb 2022 17:50:43 +0100 Subject: [PATCH 6/9] style: Format --- src/mkdocstrings_handlers/python/__init__.py | 2 +- src/mkdocstrings_handlers/python/collector.py | 1 - src/mkdocstrings_handlers/python/handler.py | 2 +- src/mkdocstrings_handlers/python/renderer.py | 1 - 4 files changed, 2 insertions(+), 4 deletions(-) diff --git a/src/mkdocstrings_handlers/python/__init__.py b/src/mkdocstrings_handlers/python/__init__.py index dcccb5b2..4823a66f 100644 --- a/src/mkdocstrings_handlers/python/__init__.py +++ b/src/mkdocstrings_handlers/python/__init__.py @@ -2,4 +2,4 @@ from mkdocstrings_handlers.python.handler import get_handler -__all__ = ["get_handler"] +__all__ = ["get_handler"] # noqa: WPS410 diff --git a/src/mkdocstrings_handlers/python/collector.py b/src/mkdocstrings_handlers/python/collector.py index 2a2823c3..7065c56f 100644 --- a/src/mkdocstrings_handlers/python/collector.py +++ b/src/mkdocstrings_handlers/python/collector.py @@ -9,7 +9,6 @@ from griffe.collections import LinesCollection, ModulesCollection from griffe.docstrings.parsers import Parser from griffe.loader import GriffeLoader - from mkdocstrings.handlers.base import BaseCollector, CollectionError, CollectorItem from mkdocstrings.loggers import get_logger diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index b61f4c5e..b1018e7f 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -4,10 +4,10 @@ from typing import Any, BinaryIO, Iterator, Optional, Tuple from griffe.logger import patch_loggers - from mkdocstrings.handlers.base import BaseHandler from mkdocstrings.inventory import Inventory from mkdocstrings.loggers import get_logger + from mkdocstrings_handlers.python.collector import PythonCollector from mkdocstrings_handlers.python.renderer import PythonRenderer diff --git a/src/mkdocstrings_handlers/python/renderer.py b/src/mkdocstrings_handlers/python/renderer.py index 60beada7..2f4087fd 100644 --- a/src/mkdocstrings_handlers/python/renderer.py +++ b/src/mkdocstrings_handlers/python/renderer.py @@ -12,7 +12,6 @@ from griffe.dataclasses import Alias, Object from markdown import Markdown from markupsafe import Markup - from mkdocstrings.extension import PluginError from mkdocstrings.handlers.base import BaseRenderer, CollectorItem from mkdocstrings.loggers import get_logger From a65f6b108b8ed15a20e7756435c474d4220b0fb3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 7 Feb 2022 18:13:22 +0100 Subject: [PATCH 7/9] docs: Fix tabs --- mkdocs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 57abdb17..c705117e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,7 +54,8 @@ markdown_extensions: - pymdownx.snippets: check_paths: true - pymdownx.superfences -- pymdownx.tabbed +- pymdownx.tabbed: + alternate_style: true - pymdownx.tasklist - toc: permalink: "¤" From f526816ef1d499795c647e6fe184ba91c1d41b1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 8 Feb 2022 12:17:27 +0100 Subject: [PATCH 8/9] fix: Allow passing `null` as docstring style Issue #2: https://github.com/mkdocstrings/python/issues/2 --- src/mkdocstrings_handlers/python/collector.py | 5 +++-- tests/test_collector.py | 6 ++++++ 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/src/mkdocstrings_handlers/python/collector.py b/src/mkdocstrings_handlers/python/collector.py index 7065c56f..f552f90e 100644 --- a/src/mkdocstrings_handlers/python/collector.py +++ b/src/mkdocstrings_handlers/python/collector.py @@ -52,6 +52,7 @@ def collect(self, identifier: str, config: dict) -> CollectorItem: # noqa: WPS2 final_config = ChainMap(config, self.default_config) parser_name = final_config["docstring_style"] parser_options = final_config["docstring_options"] + parser = parser_name and Parser(parser_name) just_loaded = False module_name = identifier.split(".", 1)[0] @@ -59,7 +60,7 @@ def collect(self, identifier: str, config: dict) -> CollectorItem: # noqa: WPS2 just_loaded = True loader = GriffeLoader( extensions=load_extensions(final_config.get("extensions", [])), - docstring_parser=Parser(parser_name), + docstring_parser=parser, docstring_options=parser_options, modules_collection=self._modules_collection, lines_collection=self._lines_collection, @@ -79,7 +80,7 @@ def collect(self, identifier: str, config: dict) -> CollectorItem: # noqa: WPS2 raise CollectionError(f"{identifier} could not be found") from error if not just_loaded and doc_object.docstring is not None: - doc_object.docstring.parser = parser_name and Parser(parser_name) + doc_object.docstring.parser = parser doc_object.docstring.parser_options = parser_options return doc_object diff --git a/tests/test_collector.py b/tests/test_collector.py index 3f56437b..cc8225b2 100644 --- a/tests/test_collector.py +++ b/tests/test_collector.py @@ -23,3 +23,9 @@ def test_collect_module(): """Assert existing module can be collected.""" collector = PythonCollector() assert collector.collect("mkdocstrings", {}) + + +def test_collect_with_null_parser(): + """Assert we can pass `None` as parser when collecting.""" + collector = PythonCollector() + assert collector.collect("mkdocstrings", {"docstring_style": None}) From fe868aa1165e8c6602d92e8636886d623fd8c0dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 8 Feb 2022 12:18:04 +0100 Subject: [PATCH 9/9] chore: Prepare release 0.5.3 --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f7c13df9..c342ca15 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). +## [0.5.3](https://github.com/mkdocstrings/python/releases/tag/0.5.3) - 2022-02-08 + +[Compare with 0.5.2](https://github.com/mkdocstrings/python/compare/0.5.2...0.5.3) + +### Bug Fixes +- Allow passing `null` as docstring style ([f526816](https://github.com/mkdocstrings/python/commit/f526816ef1d499795c647e6fe184ba91c1d41b1b) by Timothée Mazzucotelli). [Issue #2](https://github.com/mkdocstrings/python/issues/2) + + ## [0.5.2](https://github.com/mkdocstrings/python/releases/tag/0.5.2) - 2022-02-05 [Compare with 0.5.1](https://github.com/mkdocstrings/python/compare/0.5.1...0.5.2)