Permalink
Comparing changes
Choose two branches to see what’s changed or to start a new pull request.
If you need to, you can also .
Open a pull request
Create a new pull request by comparing changes across two branches. If you need to, you can also .
- 8 commits
- 13 files changed
- 0 comments
- 2 contributors
Commits on Jun 16, 2020
Commits on Jun 27, 2020
fix #132: Allow running mkdocs from non-default interpreter
Commits on Jul 07, 2020
Unified
Split
Showing
with
87 additions
and 12 deletions.
- +1 −1 .copier-answers.yml
- +1 −1 .github/workflows/ci.yml
- +9 −0 CHANGELOG.md
- +1 −2 Makefile
- +1 −0 config/flake8.ini
- +23 −1 docs/handlers/python.md
- +1 −1 pyproject.toml
- +16 −1 src/mkdocstrings/extension.py
- +1 −1 src/mkdocstrings/handlers/python.py
- 0 tests/fixtures/.gitkeep
- +12 −0 tests/fixtures/html_escaped_sequences.py
- +17 −0 tests/test_extension.py
- +4 −4 tests/test_plugin.py
| @@ -1,5 +1,5 @@ | ||
| # Changes here will be overwritten by Copier | ||
| _commit: 5fbfbfa | ||
| _commit: 309bc30 | ||
| _src_path: gh:pawamoy/copier-poetry | ||
| author_email: pawamoy@pm.me | ||
| author_fullname: "Timoth\xE9e Mazzucotelli" | ||
| @@ -56,7 +56,7 @@ jobs: | ||
| strategy: | ||
| max-parallel: 6 | ||
| matrix: | ||
| os: [ubuntu-latest] | ||
| os: [ubuntu-latest, macos-latest, windows-latest] | ||
| python-version: [3.6,3.7,3.8] | ||
|
|
||
| runs-on: ${{ matrix.os }} | ||
| @@ -5,6 +5,15 @@ 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). | ||
|
|
||
| <!-- insertion marker --> | ||
| ## [v0.12.1](https://github.com/pawamoy/mkdocstrings/releases/tag/v0.12.1) - 2020-07-07 | ||
|
|
||
| <small>[Compare with v0.12.0](https://github.com/pawamoy/mkdocstrings/compare/v0.12.0...v0.12.1)</small> | ||
|
|
||
| ### Bug Fixes | ||
| - Fix HTML-escaped sequence parsing as XML ([db297f1](https://github.com/pawamoy/mkdocstrings/commit/db297f19013fc402eeff1f2827057a959e481c66) by Timothée Mazzucotelli). | ||
| - Allow running mkdocs from non-default interpreter ([283dd7b](https://github.com/pawamoy/mkdocstrings/commit/283dd7b83eeba675a16d96d2e829851c1273a625) by Jared Khan). | ||
|
|
||
|
|
||
| ## [v0.12.0](https://github.com/pawamoy/mkdocstrings/releases/tag/v0.12.0) - 2020-06-14 | ||
|
|
||
| <small>[Compare with v0.11.4](https://github.com/pawamoy/mkdocstrings/compare/v0.11.4...v0.12.0)</small> | ||
| @@ -24,8 +24,7 @@ check-dependencies: ## Check for vulnerabilities in dependencies. | ||
| SAFETY="pipx run safety"; \ | ||
| fi; \ | ||
| fi; \ | ||
| poetry run pip freeze 2>/dev/null | \ | ||
| grep -iv 'mkdocstrings' | \ | ||
| poetry export -f requirements.txt --without-hashes | \ | ||
| poetry run failprint --no-pty -t "Checking dependencies" -- $$SAFETY check --stdin --full-report | ||
|
|
||
| .PHONY: check-docs | ||
| @@ -8,3 +8,4 @@ ignore = | ||
| S101 ;Use of assert detected. The enclosed code will be removed when compiling to optimised byte code. | ||
| ban-relative-imports = true | ||
| docstring-convention = google | ||
| exclude = fixtures | ||
| @@ -213,7 +213,7 @@ Type annotations are read both in the code and in the docstrings. | ||
| show_root_heading: no | ||
| show_root_toc_entry: no | ||
|
|
||
| ### Finding modules | ||
| ## Finding modules | ||
|
|
||
| In order for `pytkdocs` to find your packages and modules, | ||
| you should take advantage of the usual Python loading mechanisms: | ||
| @@ -263,6 +263,28 @@ plugins: | ||
| # or sys.path.insert(0, "src") | ||
| ``` | ||
|
|
||
| ## Mocking libraries | ||
|
|
||
| You may want to to generate documentation for a package while its dependencies are not available. | ||
| The Python handler provides itself no builtin way to mock libraries, | ||
| but you can use the `setup_commands` to mock them manually: | ||
|
|
||
| ```yaml | ||
| # mkdocs.yml | ||
| plugins: | ||
| - mkdocstrings: | ||
| handlers: | ||
| python: | ||
| setup_commands: | ||
| - import sys | ||
| - from unittest.mock import MagicMock as mock | ||
| - sys.modules["lib1"] = mock() | ||
| - sys.modules["lib2"] = mock() | ||
| - sys.modules["lib2.module1"] = mock() | ||
| - sys.modules["lib2.module1.moduleB"] = mock() | ||
| # etc | ||
| ``` | ||
|
|
||
| ## Recommended style (Material) | ||
|
|
||
| Here are some CSS rules for the *Material for MkDocs* theme: | ||
| @@ -4,7 +4,7 @@ build-backend = "poetry.masonry.api" | ||
|
|
||
| [tool.poetry] | ||
| name = "mkdocstrings" | ||
| version = "0.12.0" | ||
| version = "0.12.1" | ||
| description = "Automatic documentation from sources, for MkDocs." | ||
| authors = ["Timothée Mazzucotelli <pawamoy@pm.me>"] | ||
| license = "ISC License" | ||
| @@ -41,6 +41,21 @@ | ||
| log = logging.getLogger(f"mkdocs.plugins.{__name__}") | ||
| log.addFilter(warning_filter) | ||
|
|
||
| ENTITIES = """ | ||
| <!DOCTYPE html [ | ||
| <!ENTITY nbsp '&nbsp;'> | ||
| <!ENTITY lsquo '&lsquo;'> | ||
| <!ENTITY rsquo '&rsquo;'> | ||
| <!ENTITY ldquo '&ldquo;'> | ||
| <!ENTITY rdquo '&rdquo;'> | ||
| <!ENTITY laquo '&laquo;'> | ||
| <!ENTITY raquo '&raquo;'> | ||
| <!ENTITY hellip '&hellip;'> | ||
| <!ENTITY ndash '&ndash;'> | ||
| <!ENTITY mdash '&mdash;'> | ||
| ]> | ||
| """ | ||
|
|
||
|
|
||
| def atomic_brute_cast(tree: Element) -> Element: | ||
| """ | ||
| @@ -165,7 +180,7 @@ def run(self, parent: Element, blocks: Element) -> None: | ||
|
|
||
| log.debug("mkdocstrings.extension: Loading HTML back into XML tree") | ||
| try: | ||
| as_xml = XML(rendered) | ||
| as_xml = XML(ENTITIES + rendered) | ||
| except ParseError as error: | ||
| message = f"mkdocstrings.extension: {error}" | ||
| if "mismatched tag" in str(error): | ||
| @@ -148,7 +148,7 @@ def __init__(self, setup_commands: Optional[List[str]] = None) -> None: | ||
| ] | ||
| cmd = [sys.executable, "-c", "; ".join(commands)] | ||
| else: | ||
| cmd = ["pytkdocs", "--line-by-line"] | ||
| cmd = [sys.executable, "-m", "pytkdocs", "--line-by-line"] | ||
|
|
||
| self.process = Popen( # noqa: S603,S607 (we trust the input, and we don't want to use the absolute path) | ||
| cmd, universal_newlines=True, stderr=PIPE, stdout=PIPE, stdin=PIPE, bufsize=-1, env=env, | ||
Empty file.
| @@ -0,0 +1,12 @@ | ||
| """ | ||
| | ||
| ‘ | ||
| ’ | ||
| “ | ||
| ” | ||
| « | ||
| » | ||
| … | ||
| – | ||
| — | ||
| """ |
| @@ -0,0 +1,17 @@ | ||
| """Tests for the extension module.""" | ||
|
|
||
| from markdown import Markdown | ||
|
|
||
| from mkdocstrings.extension import MkdocstringsExtension | ||
|
|
||
|
|
||
| def test_render_html_escaped_sequences(): | ||
| """Assert HTML-escaped sequences are correctly parsed as XML.""" | ||
| config = { | ||
| "theme_name": "material", | ||
| "mdx": [], | ||
| "mdx_configs": {}, | ||
| "mkdocstrings": {"default_handler": "python", "custom_templates": None, "watch": [], "handlers": {}}, | ||
| } | ||
| md = Markdown(extensions=[MkdocstringsExtension(config)]) | ||
| md.convert("::: tests.fixtures.html_escaped_sequences") |
| @@ -1,8 +1,8 @@ | ||
| """Tests for the plugin module.""" | ||
| from mkdocs.commands.build import build | ||
| from mkdocs.config.base import load_config | ||
|
|
||
|
|
||
| def test_plugin(): | ||
| """Very basic test.""" | ||
| from mkdocstrings import plugin | ||
|
|
||
| assert plugin | ||
| """Build our own documentation.""" | ||
| build(load_config()) |