diff --git a/CHANGELOG.md b/CHANGELOG.md index 2bba64b5..759281ed 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.6.3](https://github.com/mkdocstrings/python/releases/tag/0.6.3) - 2022-02-20 + +[Compare with 0.6.2](https://github.com/mkdocstrings/python/compare/0.6.2...0.6.3) + +### Bug Fixes +- Fix examples rendering ([a06a7e3](https://github.com/mkdocstrings/python/commit/a06a7e34c7017374c5bed41f4757ed86ae64cb2e) by Timothée Mazzucotelli). References: [mkdocstrings/griffe#46](https://github.com/mkdocstrings/griffe/issues/46) + + ## [0.6.2](https://github.com/mkdocstrings/python/releases/tag/0.6.2) - 2022-02-17 [Compare with 0.6.1](https://github.com/mkdocstrings/python/compare/0.6.1...0.6.2) diff --git a/README.md b/README.md index 3cb3b334..3cdd2c6d 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![documentation](https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat)](https://mkdocstrings.github.io/python/) [![pypi version](https://img.shields.io/pypi/v/python.svg)](https://pypi.org/project/python/) [![gitpod](https://img.shields.io/badge/gitpod-workspace-blue.svg?style=flat)](https://gitpod.io/#https://github.com/mkdocstrings/python) -[![gitter](https://badges.gitter.im/join%20chat.svg)](https://gitter.im/python/community) +[![gitter](https://badges.gitter.im/join%20chat.svg)](https://gitter.im/mkdocstrings/python) A Python handler for [mkdocstrings](https://github.com/mkdocstrings/mkdocstrings). diff --git a/docs/usage.md b/docs/usage.md index 363b7086..d9329414 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -88,6 +88,12 @@ both globally or per autodoc instruction. See the supported docstring sections on [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/). +!!! note + As Numpy-style is partially supported by the underlying parser, + you may experience problems in the building process if your docstring + has a `Methods` section in the class docstring + (see [#366](https://github.com/mkdocstrings/mkdocstrings/issues/366)). + #### Google-style admonitions With Google-style docstrings, any section that is not recognized will be transformed into its admonition equivalent. diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html index 0f96e1e1..8f6df880 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html @@ -1,9 +1,9 @@ {{ log.debug("Rendering examples section") }}

{{ section.title or "Examples:" }}

{% for section_type, sub_section in section.value %} - {% if section_type == "markdown" %} + {% if section_type.value == "text" %} {{ sub_section|convert_markdown(heading_level, html_id) }} - {% elif section_type == "examples" %} + {% elif section_type.value == "examples" %} {{ sub_section|highlight(language="python", linenums=False) }} {% endif %} {% endfor %} diff --git a/tests/conftest.py b/tests/conftest.py index b81fc562..ab919d29 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -84,3 +84,18 @@ def fixture_ext_markdown(plugin): A Markdown instance. """ return plugin.md + + +@pytest.fixture(name="renderer") +def fixture_renderer(plugin): + """Return a PythonRenderer instance. + + Parameters: + plugin: Pytest fixture: [tests.conftest.fixture_plugin][]. + + Returns: + A renderer instance. + """ + handler = plugin.handlers.get_handler("python") + handler.renderer._update_env(plugin.md, plugin.handlers._config) # noqa: WPS437 + return handler.renderer diff --git a/tests/test_collector.py b/tests/test_collector.py index cc8225b2..53544c77 100644 --- a/tests/test_collector.py +++ b/tests/test_collector.py @@ -1,4 +1,4 @@ -"""Tests for the handlers.python module.""" +"""Tests for the `collector` module.""" import pytest diff --git a/tests/test_renderer.py b/tests/test_renderer.py new file mode 100644 index 00000000..76f68b7c --- /dev/null +++ b/tests/test_renderer.py @@ -0,0 +1,33 @@ +"""Tests for the `renderer` module.""" + +import pytest +from griffe.docstrings.dataclasses import DocstringSection, DocstringSectionKind + + +@pytest.mark.parametrize( + "renderer", + [ + {"theme": "mkdocs"}, + {"theme": "readthedocs"}, + {"theme": {"name": "material"}}, + ], + indirect=["renderer"], +) +def test_render_docstring_examples_section(renderer): + """Assert docstrings' examples section can be rendered. + + Parameters: + renderer: A renderer instance (parametrized). + """ + section = DocstringSection( + DocstringSectionKind.examples, + value=[ + (DocstringSectionKind.text, "This is an example."), + (DocstringSectionKind.examples, ">>> print('Hello')\nHello"), + ], + ) + template = renderer.env.get_template("docstring/examples.html") + rendered = template.render(section=section) + assert "

This is an example.

" in rendered + assert "print" in rendered + assert "Hello" in rendered