Skip to content
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
@@ -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 '&amp;nbsp;'>
<!ENTITY lsquo '&amp;lsquo;'>
<!ENTITY rsquo '&amp;rsquo;'>
<!ENTITY ldquo '&amp;ldquo;'>
<!ENTITY rdquo '&amp;rdquo;'>
<!ENTITY laquo '&amp;laquo;'>
<!ENTITY raquo '&amp;raquo;'>
<!ENTITY hellip '&amp;hellip;'>
<!ENTITY ndash '&amp;ndash;'>
<!ENTITY mdash '&amp;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 @@
"""
&nbsp;
&lsquo;
&rsquo;
&ldquo;
&rdquo;
&laquo;
&raquo;
&hellip;
&ndash;
&mdash;
"""
@@ -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())

No commit comments for this range