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/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) diff --git a/README.md b/README.md index 38fbb568..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/) @@ -8,9 +8,12 @@ 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. +mkdocstrings-python requires Python 3.7 or above.
To install Python 3.7, I recommend using pyenv. @@ -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. 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 diff --git a/mkdocs.yml b/mkdocs.yml index 0137f07c..c705117e 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" @@ -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 @@ -54,7 +54,8 @@ markdown_extensions: - pymdownx.snippets: check_paths: true - pymdownx.superfences -- pymdownx.tabbed +- pymdownx.tabbed: + alternate_style: true - pymdownx.tasklist - toc: permalink: "¤" diff --git a/pyproject.toml b/pyproject.toml index 462b077f..7f7b5c29 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -109,5 +109,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/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..f552f90e 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 @@ -53,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] @@ -60,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, @@ -80,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/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 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 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})