"]
-license = "ISC License"
+authors = [{name = "Timothée Mazzucotelli", email = "pawamoy@pm.me"}]
+license = {file = "LICENSE"}
readme = "README.md"
-repository = "https://github.com/mkdocstrings/mkdocstrings"
-homepage = "https://github.com/mkdocstrings/mkdocstrings"
+requires-python = ">=3.6"
keywords = ["mkdocs", "mkdocs-plugin", "docstrings", "autodoc", "documentation"]
-packages = [ { include = "mkdocstrings", from = "src" } ]
-include = [
- "README.md",
- "pyproject.toml"
+dynamic = ["version", "classifiers"]
+classifiers = [
+ "Development Status :: 4 - Beta",
+ "License :: OSI Approved :: ISC License (ISCL)",
+ "Typing :: Typed",
+]
+dependencies = [
+ "Jinja2>=2.11.1,<4.0",
+ "Markdown~=3.3",
+ "MarkupSafe>=1.1,<3.0",
+ "mkdocs~=1.2",
+ "mkdocs-autorefs>=0.1,<0.4",
+ "pymdown-extensions>=6.3,<9.0",
+ "pytkdocs>=0.2.0,<0.13.0",
]
-[tool.poetry.dependencies]
-python = "^3.6"
-Jinja2 = "^2.11"
-Markdown = "^3.3"
-MarkupSafe = "^1.1"
-mkdocs = "^1.1"
-mkdocs-autorefs = "^0.1"
-pymdown-extensions = ">=6.3, <9.0"
-pytkdocs = ">=0.2.0, <0.12.0"
-
-[tool.poetry.dev-dependencies]
-autoflake = "^1.4"
-black = "^20.8b1"
-duty = "^0.6.0"
-flakehell = "^0.9.0"
-flake8-black = "^0.2.1"
-flake8-builtins = "^1.5.3"
-flake8-tidy-imports = "^4.2.1"
-flake8-variables-names = "^0.0.4"
-flake8-pytest-style = "^1.3.0"
-git-changelog = "^0.4.2"
-httpx = "^0.16.1"
-isort = {version = "^5.7.0", extras = ["pyproject"]}
-jinja2-cli = "^0.7.0"
-mkdocs-coverage = "^0.2.1"
-mkdocs-gen-files = {version = "^0.3.0", markers = "python_version>='3.7'"}
-mkdocs-material = "^6.2.7"
-mkdocs-section-index = "^0.2.3"
-mypy = "^0.782"
-pytest = "^6.2.2"
-pytest-cov = "^2.11.1"
-pytest-randomly = "^3.5.0"
-pytest-sugar = "^0.9.4"
-pytest-xdist = "^2.2.0"
-toml = "^0.10.2"
-darglint = "^1.5.8"
-flake8-bandit = "^2.1.2"
-flake8-bugbear = "^20.11.1"
-flake8-comprehensions = "^3.3.1"
-flake8-docstrings = "^1.5.0"
-flake8-string-format = "^0.3.0"
-pep8-naming = "^0.11.1"
+[project.urls]
+Homepage = "https://mkdocstrings.github.io"
+Documentation = "https://mkdocstrings.github.io"
+Changelog = "https://mkdocstrings.github.io/changelog"
+Repository = "https://github.com/mkdocstrings/mkdocstrings"
+Issues = "https://github.com/mkdocstrings/mkdocstrings/issues"
+Discussions = "https://github.com/mkdocstrings/mkdocstrings/discussions"
+Gitter = "https://gitter.im/mkdocstrings/community"
+Funding = "https://github.com/sponsors/mkdocstrings"
-[tool.poetry.plugins."mkdocs.plugins"]
+[project.entry-points."mkdocs.plugins"]
mkdocstrings = "mkdocstrings.plugin:MkdocstringsPlugin"
+
+[project.optional-dependencies]
+[tool.pdm]
+package-dir = "src"
+includes = ["src/mkdocstrings"]
+
+[tool.pdm.dev-dependencies]
+duty = ["duty~=0.6"]
+docs = [
+ "mkdocs-coverage~=0.2; python_version >= '3.7'",
+ "mkdocs-gen-files~=0.3; python_version >= '3.7'",
+ "mkdocs-literate-nav~=0.4; python_version >= '3.7'",
+ "mkdocs-material~=7.1; python_version >= '3.7'",
+ "mkdocs-section-index~=0.3; python_version >= '3.7'",
+ "toml~=0.10; python_version >= '3.7'",
+]
+format = [
+ "autoflake~=1.4",
+ "black~=20.8b1",
+ "isort~=5.8",
+]
+maintain = [
+ # TODO: remove this section when git-changelog is more powerful
+ "git-changelog~=0.4",
+]
+quality = [
+ "darglint~=1.7",
+ "flake8-bandit~=2.1",
+ "flake8-black~=0.2",
+ "flake8-bugbear~=21.3",
+ "flake8-builtins~=1.5",
+ "flake8-comprehensions~=3.4",
+ "flake8-docstrings~=1.6",
+ "flake8-pytest-style~=1.4",
+ "flake8-string-format~=0.3",
+ "flake8-tidy-imports~=4.2",
+ "flake8-variables-names~=0.0",
+ "pep8-naming~=0.11",
+ "wps-light~=0.15",
+]
+tests = [
+ "pygments~=2.10", # python 3.6
+ "pytest~=6.2",
+ "pytest-cov~=2.11",
+ "pytest-randomly~=3.6",
+ "pytest-sugar~=0.9",
+ "pytest-xdist~=2.2",
+]
+typing = ["mypy~=0.812"]
+
[tool.black]
line-length = 120
exclude = "tests/fixtures"
diff --git a/scripts/multirun.sh b/scripts/multirun.sh
index b483defa..4ca6e2ce 100755
--- a/scripts/multirun.sh
+++ b/scripts/multirun.sh
@@ -1,22 +1,17 @@
#!/usr/bin/env bash
set -e
-PYTHON_VERSIONS="${PYTHON_VERSIONS:-3.6 3.7 3.8 3.9}"
+PYTHON_VERSIONS="${PYTHON_VERSIONS-3.6 3.7 3.8 3.9}"
if [ -n "${PYTHON_VERSIONS}" ]; then
for python_version in ${PYTHON_VERSIONS}; do
- if output=$(poetry env use "${python_version}" 2>&1); then
- if echo "${output}" | grep -q ^Creating; then
- echo "> Environment for Python ${python_version} not created, skipping" >&2
- poetry env remove "${python_version}" &>/dev/null || true
- else
- echo "> poetry run $@ (Python ${python_version})"
- poetry run "$@"
- fi
+ if pdm use -f "${python_version}" &>/dev/null; then
+ echo "> pdm run $@ (Python ${python_version})"
+ pdm run "$@"
else
- echo "> poetry env use ${python_version}: Python version not available?" >&2
+ echo "> pdm use -f ${python_version}: Python version not available?" >&2
fi
done
else
- poetry run "$@"
+ pdm run "$@"
fi
diff --git a/scripts/setup.sh b/scripts/setup.sh
index a626b257..cfddbac7 100755
--- a/scripts/setup.sh
+++ b/scripts/setup.sh
@@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -e
-PYTHON_VERSIONS="${PYTHON_VERSIONS:-3.6 3.7 3.8 3.9}"
+PYTHON_VERSIONS="${PYTHON_VERSIONS-3.6 3.7 3.8 3.9}"
install_with_pipx() {
if ! command -v "$1" &>/dev/null; then
@@ -12,21 +12,17 @@ install_with_pipx() {
fi
}
-install_with_pipx poetry
+install_with_pipx pdm
if [ -n "${PYTHON_VERSIONS}" ]; then
for python_version in ${PYTHON_VERSIONS}; do
- if output=$(poetry env use "${python_version}" 2>&1); then
- if echo "${output}" | grep -q ^Creating; then
- echo "> Created environment for Python ${python_version}"
- else
- echo "> Using Python ${python_version} environment"
- fi
- poetry install
+ if pdm use -f "${python_version}" &>/dev/null; then
+ echo "> Using Python ${python_version} environment"
+ pdm install
else
- echo "> poetry env use ${python_version}: Python version not available?" >&2
+ echo "> pdm use -f ${python_version}: Python version not available?" >&2
fi
done
else
- poetry install
-fi
\ No newline at end of file
+ pdm install
+fi
diff --git a/src/mkdocstrings/extension.py b/src/mkdocstrings/extension.py
index c9f42e6d..afe59708 100644
--- a/src/mkdocstrings/extension.py
+++ b/src/mkdocstrings/extension.py
@@ -23,7 +23,7 @@
"""
import re
from collections import ChainMap
-from typing import Mapping, MutableSequence, Sequence, Tuple
+from typing import Mapping, MutableSequence, Tuple
from xml.etree.ElementTree import Element
import yaml
@@ -35,13 +35,13 @@
from markdown.treeprocessors import Treeprocessor
from mkdocs_autorefs.plugin import AutorefsPlugin
-from mkdocstrings.handlers.base import CollectionError, CollectorItem, Handlers
+from mkdocstrings.handlers.base import BaseHandler, CollectionError, CollectorItem, Handlers
from mkdocstrings.loggers import get_logger
try:
from mkdocs.exceptions import PluginError # New in MkDocs 1.2
except ImportError:
- PluginError = SystemExit
+ PluginError = SystemExit # noqa: WPS440
log = get_logger(__name__)
@@ -79,7 +79,7 @@ def __init__(
self._autorefs = autorefs
self._updated_env = False
- def test(self, parent: Element, block: str) -> bool:
+ def test(self, parent: Element, block: str) -> bool: # type: ignore
"""Match our autodoc instructions.
Arguments:
@@ -117,15 +117,26 @@ def run(self, parent: Element, blocks: MutableSequence[str]) -> None:
heading_level = match["heading"].count("#")
log.debug(f"Matched '::: {identifier}'")
- html, headings = self._process_block(identifier, block, heading_level)
+ html, handler = self._process_block(identifier, block, heading_level)
el = Element("div", {"class": "mkdocstrings"})
# The final HTML is inserted as opaque to subsequent processing, and only revealed at the end.
el.text = self.md.htmlStash.store(html)
# So we need to duplicate the headings directly (and delete later), just so 'toc' can pick them up.
+ headings = handler.renderer.get_headings()
el.extend(headings)
for heading in headings:
- self._autorefs.register_anchor(self._autorefs.current_page, heading.attrib["id"])
+ page = self._autorefs.current_page
+ anchor = heading.attrib["id"]
+ self._autorefs.register_anchor(page, anchor)
+
+ if "data-role" in heading.attrib:
+ self._handlers.inventory.register(
+ name=anchor,
+ domain=handler.domain,
+ role=heading.attrib["data-role"],
+ uri=f"{page}#{anchor}",
+ )
parent.append(el)
@@ -135,7 +146,7 @@ def run(self, parent: Element, blocks: MutableSequence[str]) -> None:
# list for future processing.
blocks.insert(0, the_rest)
- def _process_block(self, identifier: str, yaml_block: str, heading_level: int = 0) -> Tuple[str, Sequence[Element]]:
+ def _process_block(self, identifier: str, yaml_block: str, heading_level: int = 0) -> Tuple[str, BaseHandler]:
"""Process an autodoc block.
Arguments:
@@ -148,7 +159,7 @@ def _process_block(self, identifier: str, yaml_block: str, heading_level: int =
TemplateNotFound: When a template used for rendering could not be found.
Returns:
- Rendered HTML and the list of heading elements encoutered.
+ Rendered HTML and the handler that was used.
"""
config = yaml.safe_load(yaml_block) or {}
handler_name = self._handlers.get_handler_name(config)
@@ -172,7 +183,7 @@ def _process_block(self, identifier: str, yaml_block: str, heading_level: int =
if not self._updated_env:
log.debug("Updating renderer's env")
- handler.renderer._update_env(self.md, self._config) # noqa: W0212 (protected member OK)
+ handler.renderer._update_env(self.md, self._config) # noqa: WPS437 (protected member OK)
self._updated_env = True
log.debug("Rendering templates")
@@ -185,7 +196,7 @@ def _process_block(self, identifier: str, yaml_block: str, heading_level: int =
)
raise
- return (rendered, handler.renderer.get_headings())
+ return (rendered, handler)
def get_item_configs(handler_config: dict, config: dict) -> Tuple[Mapping, Mapping]:
diff --git a/src/mkdocstrings/handlers/base.py b/src/mkdocstrings/handlers/base.py
index 2a95e775..f496e7ed 100644
--- a/src/mkdocstrings/handlers/base.py
+++ b/src/mkdocstrings/handlers/base.py
@@ -11,7 +11,7 @@
import importlib
from abc import ABC, abstractmethod
from pathlib import Path
-from typing import Any, Dict, Iterable, Optional, Sequence
+from typing import Any, Dict, Iterable, List, Optional, Sequence
from xml.etree.ElementTree import Element, tostring
from jinja2 import Environment, FileSystemLoader
@@ -24,6 +24,7 @@
IdPrependingTreeprocessor,
MkdocstringsInnerExtension,
)
+from mkdocstrings.inventory import Inventory
from mkdocstrings.loggers import get_template_logger
CollectorItem = Any
@@ -95,7 +96,7 @@ def __init__(self, directory: str, theme: str, custom_templates: Optional[str] =
for path in paths:
css_path = path / "style.css"
if css_path.is_file():
- self.extra_css += "\n" + css_path.read_text(encoding="utf-8")
+ self.extra_css += "\n" + css_path.read_text(encoding="utf-8") # noqa: WPS601
break
if custom_templates is not None:
@@ -103,14 +104,14 @@ def __init__(self, directory: str, theme: str, custom_templates: Optional[str] =
self.env = Environment(
autoescape=True,
- loader=FileSystemLoader(paths),
+ loader=FileSystemLoader(paths), # type: ignore
auto_reload=False, # Editing a template in the middle of a build is not useful.
) # type: ignore
self.env.filters["any"] = do_any
self.env.globals["log"] = get_template_logger()
- self._headings = []
- self._md = None # To be populated in `update_env`.
+ self._headings: List[Element] = []
+ self._md: Markdown = None # type: ignore # To be populated in `update_env`.
@abstractmethod
def render(self, data: CollectorItem, config: dict) -> str:
@@ -163,6 +164,7 @@ def do_heading(
content: str,
heading_level: int,
*,
+ role: Optional[str] = None,
hidden: bool = False,
toc_label: Optional[str] = None,
**attributes: str,
@@ -172,6 +174,7 @@ def do_heading(
Arguments:
content: The HTML within the heading.
heading_level: The level of heading (e.g. 3 -> `h3`).
+ role: An optional role for the object bound to this heading.
hidden: If True, only register it for the table of contents, don't render anything.
toc_label: The title to use in the table of contents ('data-toc-label' attribute).
attributes: Any extra HTML attributes of the heading.
@@ -182,8 +185,10 @@ def do_heading(
# First, produce the "fake" heading, for ToC only.
el = Element(f"h{heading_level}", attributes)
if toc_label is None:
- toc_label = content.unescape() if isinstance(el, Markup) else content
+ toc_label = content.unescape() if isinstance(el, Markup) else content # type: ignore
el.set("data-toc-label", toc_label)
+ if role:
+ el.set("data-role", role)
self._headings.append(el)
if hidden:
@@ -285,8 +290,16 @@ class BaseHandler:
Inherit from this class to implement a handler.
It's usually just a combination of a collector and a renderer, but you can make it as complex as you need.
+
+ Attributes:
+ domain: The cross-documentation domain/language for this handler.
+ enable_inventory: Whether this handler is interested in enabling the creation
+ of the `objects.inv` Sphinx inventory file.
"""
+ domain: str = "default"
+ enable_inventory: bool = False
+
def __init__(self, collector: BaseCollector, renderer: BaseRenderer) -> None:
"""Initialize the object.
@@ -314,6 +327,7 @@ def __init__(self, config: dict) -> None:
"""
self._config = config
self._handlers: Dict[str, BaseHandler] = {}
+ self.inventory: Inventory = Inventory(project=self._config["site_name"])
def get_anchor(self, identifier: str) -> Optional[str]:
"""Return the canonical HTML anchor for the identifier, if any of the seen handlers can collect it.
@@ -329,9 +343,8 @@ def get_anchor(self, identifier: str) -> Optional[str]:
anchor = handler.renderer.get_anchor(handler.collector.collect(identifier, {}))
except CollectionError:
continue
- else:
- if anchor is not None:
- return anchor
+ if anchor is not None:
+ return anchor
return None
def get_handler_name(self, config: dict) -> str:
@@ -343,10 +356,10 @@ def get_handler_name(self, config: dict) -> str:
Returns:
The name of the handler to use.
"""
- config = self._config["mkdocstrings"]
+ global_config = self._config["mkdocstrings"]
if "handler" in config:
return config["handler"]
- return config["default_handler"]
+ return global_config["default_handler"]
def get_handler_config(self, name: str) -> dict:
"""Return the global configuration of the given handler.
@@ -382,7 +395,7 @@ def get_handler(self, name: str, handler_config: Optional[dict] = None) -> BaseH
if handler_config is None:
handler_config = self.get_handler_config(name)
module = importlib.import_module(f"mkdocstrings.handlers.{name}")
- self._handlers[name] = module.get_handler(
+ self._handlers[name] = module.get_handler( # type: ignore
self._config["theme_name"],
self._config["mkdocstrings"]["custom_templates"],
**handler_config,
diff --git a/src/mkdocstrings/handlers/python.py b/src/mkdocstrings/handlers/python.py
index a9e63786..0aab09ac 100644
--- a/src/mkdocstrings/handlers/python.py
+++ b/src/mkdocstrings/handlers/python.py
@@ -5,15 +5,19 @@
import json
import os
+import posixpath
import sys
import traceback
from collections import ChainMap
from subprocess import PIPE, Popen # noqa: S404 (what other option, more secure that PIPE do we have? sockets?)
-from typing import Any, List, Optional
+from typing import Any, BinaryIO, Callable, Iterator, List, Optional, Tuple
from markdown import Markdown
+from markupsafe import Markup
+from mkdocstrings.extension import PluginError
from mkdocstrings.handlers.base import BaseCollector, BaseHandler, BaseRenderer, CollectionError, CollectorItem
+from mkdocstrings.inventory import Inventory
from mkdocstrings.loggers import get_logger
log = get_logger(__name__)
@@ -43,8 +47,10 @@ class PythonRenderer(BaseRenderer):
"show_if_no_docstring": False,
"show_signature_annotations": False,
"show_source": True,
+ "show_bases": True,
"group_by_category": True,
"heading_level": 2,
+ "members_order": "alphabetical",
}
"""The default rendering options.
@@ -59,8 +65,10 @@ class PythonRenderer(BaseRenderer):
**`show_if_no_docstring`** | `bool` | Show the object heading even if it has no docstring or children with docstrings. | `False`
**`show_signature_annotations`** | `bool` | Show the type annotations in methods and functions signatures. | `False`
**`show_source`** | `bool` | Show the source code of this object. | `True`
+ **`show_bases`** | `bool` | Show the base classes of a class. | `True`
**`group_by_category`** | `bool` | Group the object's children by categories: attributes, classes, functions, methods, and modules. | `True`
**`heading_level`** | `int` | The initial heading level to use. | `2`
+ **`members_order`** | `str` | The members ordering to use. Options: `alphabetical` - order by the members names, `source` - order members as they appear in the source file. | `alphabetical`
""" # noqa: E501
def render(self, data: CollectorItem, config: dict) -> str: # noqa: D102 (ignore missing docstring)
@@ -72,6 +80,16 @@ def render(self, data: CollectorItem, config: dict) -> str: # noqa: D102 (ignor
# of the rendering recursion. Therefore, it's easier to use it as a plain value
# than as an item in a dictionary.
heading_level = final_config["heading_level"]
+ members_order = final_config["members_order"]
+
+ if members_order == "alphabetical":
+ sort_function = _sort_key_alphabetical
+ elif members_order == "source":
+ sort_function = _sort_key_source
+ else:
+ raise PluginError(f"Unknown members_order '{members_order}', choose between 'alphabetical' and 'source'.")
+
+ sort_object(data, sort_function=sort_function)
return template.render(
**{"config": final_config, data["category"]: data, "heading_level": heading_level, "root": True},
@@ -85,6 +103,12 @@ def update_env(self, md: Markdown, config: dict) -> None: # noqa: D102 (ignore
self.env.trim_blocks = True
self.env.lstrip_blocks = True
self.env.keep_trailing_newline = False
+ self.env.filters["brief_xref"] = self.do_brief_xref
+
+ def do_brief_xref(self, path: str) -> Markup:
+ """Filter to create cross-reference with brief text and full identifier as hover text."""
+ brief = path.split(".")[-1]
+ return Markup("{brief}").format(path=path, brief=brief)
class PythonCollector(BaseCollector):
@@ -152,7 +176,6 @@ def __init__(self, setup_commands: Optional[List[str]] = None) -> None:
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,
@@ -236,7 +259,39 @@ def teardown(self) -> None:
class PythonHandler(BaseHandler):
- """The Python handler class, nothing specific here."""
+ """The Python handler class.
+
+ Attributes:
+ domain: The cross-documentation domain/language for this handler.
+ enable_inventory: Whether this handler is interested in enabling the creation
+ of the `objects.inv` Sphinx inventory file.
+ """
+
+ domain: str = "py" # to match Sphinx's default domain
+ enable_inventory: bool = True
+
+ @classmethod
+ def load_inventory(
+ cls, in_file: BinaryIO, url: str, base_url: Optional[str] = None, **kwargs
+ ) -> Iterator[Tuple[str, str]]:
+ """Yield items and their URLs from an inventory file streamed from `in_file`.
+
+ This implements mkdocstrings' `load_inventory` "protocol" (see plugin.py).
+
+ Arguments:
+ in_file: The binary file-like object to read the inventory from.
+ url: The URL that this file is being streamed from (used to guess `base_url`).
+ base_url: The URL that this inventory's sub-paths are relative to.
+ **kwargs: Ignore additional arguments passed from the config.
+
+ Yields:
+ Tuples of (item identifier, item URL).
+ """
+ if base_url is None:
+ base_url = posixpath.dirname(url)
+
+ for item in Inventory.parse_sphinx(in_file, domain_filter=("py",)).values(): # noqa: WPS526
+ yield item.name, posixpath.join(base_url, item.uri)
def get_handler(
@@ -282,3 +337,36 @@ def rebuild_category_lists(obj: dict) -> None:
obj["children"] = [child for _, child in obj["children"].items()]
for child in obj["children"]:
rebuild_category_lists(child)
+
+
+def sort_object(obj: CollectorItem, sort_function: Callable[[CollectorItem], Any]) -> None:
+ """Sort the collected object's children.
+
+ Sorts the object's children list, then each category separately, and then recurses into each.
+
+ Arguments:
+ obj: The collected object, as a dict. Note that this argument is mutated.
+ sort_function: The sort key function used to determine the order of elements.
+ """
+ obj["children"].sort(key=sort_function)
+
+ for category in ("attributes", "classes", "functions", "methods", "modules"):
+ obj[category].sort(key=sort_function)
+
+ for child in obj["children"]:
+ sort_object(child, sort_function=sort_function)
+
+
+def _sort_key_alphabetical(item: CollectorItem) -> Any:
+ """Return a sort key for 'alphabetical' sorting of CollectorItems."""
+ # chr(sys.maxunicode) is a string that contains the final unicode
+ # character, so if 'name' isn't found on the object, the item will go to
+ # the end of the list.
+ return item.get("name", chr(sys.maxunicode))
+
+
+def _sort_key_source(item: CollectorItem) -> Any:
+ """Return a sort key for 'source' sorting of CollectorItems."""
+ # if 'line_start' isn't found on the object, the item will go to
+ # the start of the list.
+ return item.get("source", {}).get("line_start", -1)
diff --git a/src/mkdocstrings/handlers/rendering.py b/src/mkdocstrings/handlers/rendering.py
index ed9049ba..e8383cf2 100644
--- a/src/mkdocstrings/handlers/rendering.py
+++ b/src/mkdocstrings/handlers/rendering.py
@@ -3,7 +3,7 @@
import copy
import re
import textwrap
-from typing import List, Optional
+from typing import Any, Dict, List, Optional
from xml.etree.ElementTree import Element
from markdown import Markdown
@@ -43,8 +43,8 @@ def __init__(self, md: Markdown):
Arguments:
md: The Markdown instance to read configs from.
"""
- config = {}
- for ext in md.registeredExtensions:
+ config: Dict[str, Any] = {}
+ for ext in md.registeredExtensions: # type: ignore
if isinstance(ext, HighlightExtension) and (ext.enabled or not config):
config = ext.getConfigs()
break # This one takes priority, no need to continue looking
@@ -52,7 +52,7 @@ def __init__(self, md: Markdown):
config = ext.getConfigs()
config["language_prefix"] = config["lang_prefix"]
self._css_class = config.pop("css_class", "highlight")
- super().__init__(**{k: v for k, v in config.items() if k in self._highlight_config_keys})
+ super().__init__(**{name: opt for name, opt in config.items() if name in self._highlight_config_keys})
def highlight( # noqa: W0221 (intentionally different params, we're extending the functionality)
self,
@@ -83,7 +83,7 @@ def highlight( # noqa: W0221 (intentionally different params, we're extending t
src = textwrap.dedent(src)
kwargs.setdefault("css_class", self._css_class)
- old_linenums = self.linenums
+ old_linenums = self.linenums # type: ignore
if linenums is not None:
self.linenums = linenums
try:
@@ -185,7 +185,7 @@ def run(self, root: Element):
el = copy.copy(el)
# 'toc' extension's first pass (which we require to build heading stubs/ids) also edits the HTML.
# Undo the permalink edit so we can pass this heading to the outer pass of the 'toc' extension.
- if len(el) > 0 and el[-1].get("class") == self.md.treeprocessors["toc"].permalink_class:
+ if len(el) > 0 and el[-1].get("class") == self.md.treeprocessors["toc"].permalink_class: # noqa: WPS507
del el[-1]
self.headings.append(el)
diff --git a/src/mkdocstrings/inventory.py b/src/mkdocstrings/inventory.py
new file mode 100644
index 00000000..9a59d2b4
--- /dev/null
+++ b/src/mkdocstrings/inventory.py
@@ -0,0 +1,132 @@
+"""Module responsible for the objects inventory."""
+
+# Credits to Brian Skinn and the sphobjinv project:
+# https://github.com/bskinn/sphobjinv
+
+import re
+import zlib
+from textwrap import dedent
+from typing import BinaryIO, Collection, List, Optional
+
+
+class InventoryItem:
+ """Inventory item."""
+
+ def __init__(
+ self, name: str, domain: str, role: str, uri: str, priority: str = "1", dispname: Optional[str] = None
+ ):
+ """Initialize the object.
+
+ Arguments:
+ name: The item name.
+ domain: The item domain, like 'python' or 'crystal'.
+ role: The item role, like 'class' or 'method'.
+ uri: The item URI.
+ priority: The item priority. It can help for inventory suggestions.
+ dispname: The item display name.
+ """
+ self.name: str = name
+ self.domain: str = domain
+ self.role: str = role
+ self.uri: str = uri
+ self.priority: str = priority
+ self.dispname: str = dispname or name
+
+ def format_sphinx(self) -> str:
+ """Format this item as a Sphinx inventory line.
+
+ Returns:
+ A line formatted for an `objects.inv` file.
+ """
+ dispname = self.dispname
+ if dispname == self.name:
+ dispname = "-"
+ uri = self.uri
+ if uri.endswith(self.name):
+ uri = uri[: -len(self.name)] + "$"
+ return f"{self.name} {self.domain}:{self.role} {self.priority} {uri} {dispname}"
+
+ sphinx_item_regex = re.compile(r"^(.+?)\s+(\S+):(\S+)\s+(-?\d+)\s+(\S+)\s+(.*)$")
+
+ @classmethod
+ def parse_sphinx(cls, line: str) -> "InventoryItem":
+ """Parse a line from a Sphinx v2 inventory file and return an `InventoryItem` from it."""
+ match = cls.sphinx_item_regex.search(line)
+ if not match:
+ raise ValueError(line)
+ name, domain, role, priority, uri, dispname = match.groups()
+ if uri.endswith("$"):
+ uri = uri[:-1] + name
+ if dispname == "-":
+ dispname = name
+ return cls(name, domain, role, uri, priority, dispname)
+
+
+class Inventory(dict):
+ """Inventory of collected and rendered objects."""
+
+ def __init__(self, items: Optional[List[InventoryItem]] = None, project: str = "project", version: str = "0.0.0"):
+ """Initialize the object.
+
+ Arguments:
+ items: A list of items.
+ project: The project name.
+ version: The project version.
+ """
+ super().__init__()
+ items = items or []
+ for item in items:
+ self[item.name] = item
+ self.project = project
+ self.version = version
+
+ def register(self, *args, **kwargs):
+ """Create and register an item.
+
+ Arguments:
+ *args: Arguments passed to [InventoryItem][mkdocstrings.inventory.InventoryItem].
+ **kwargs: Keyword arguments passed to [InventoryItem][mkdocstrings.inventory.InventoryItem].
+ """
+ item = InventoryItem(*args, **kwargs)
+ self[item.name] = item
+
+ def format_sphinx(self) -> bytes:
+ """Format this inventory as a Sphinx `objects.inv` file.
+
+ Returns:
+ The inventory as bytes.
+ """
+ header = (
+ dedent(
+ f"""
+ # Sphinx inventory version 2
+ # Project: {self.project}
+ # Version: {self.version}
+ # The remainder of this file is compressed using zlib.
+ """
+ )
+ .lstrip()
+ .encode("utf8")
+ )
+
+ lines = [item.format_sphinx().encode("utf8") for item in self.values()]
+ return header + zlib.compress(b"\n".join(lines) + b"\n", 9)
+
+ @classmethod
+ def parse_sphinx(cls, in_file: BinaryIO, *, domain_filter: Collection[str] = ()) -> "Inventory":
+ """Parse a Sphinx v2 inventory file and return an `Inventory` from it.
+
+ Arguments:
+ in_file: The binary file-like object to read from.
+ domain_filter: A collection of domain values to allow (and filter out all other ones).
+
+ Returns:
+ An `Inventory` containing the collected `InventoryItem`s.
+ """
+ for _ in range(4):
+ in_file.readline()
+ lines = zlib.decompress(in_file.read()).splitlines()
+ items = [InventoryItem.parse_sphinx(line.decode("utf8")) for line in lines]
+ if domain_filter:
+ items = [item for item in items if item.domain in domain_filter]
+ return cls(items)
diff --git a/src/mkdocstrings/plugin.py b/src/mkdocstrings/plugin.py
index 054cd2e0..4e693473 100644
--- a/src/mkdocstrings/plugin.py
+++ b/src/mkdocstrings/plugin.py
@@ -12,10 +12,14 @@
during the [`on_serve` event hook](https://www.mkdocs.org/user-guide/plugins/#on_serve).
"""
+import collections
+import functools
+import gzip
import os
-from typing import Callable, Optional, Tuple
+from concurrent import futures
+from typing import Any, BinaryIO, Callable, Iterable, List, Mapping, Optional, Tuple
+from urllib import request
-from livereload import Server
from mkdocs.config import Config
from mkdocs.config.config_options import Type as MkType
from mkdocs.plugins import BasePlugin
@@ -33,6 +37,9 @@
RENDERING_OPTS_KEY: str = "rendering"
"""The name of the rendering parameter in YAML configuration blocks."""
+InventoryImportType = List[Tuple[str, Mapping[str, Any]]]
+InventoryLoaderType = Callable[..., Iterable[Tuple[str, str]]]
+
class MkdocstringsPlugin(BasePlugin):
"""An `mkdocs` plugin.
@@ -40,6 +47,7 @@ class MkdocstringsPlugin(BasePlugin):
This plugin defines the following event hooks:
- `on_config`
+ - `on_env`
- `on_post_build`
- `on_serve`
@@ -52,6 +60,7 @@ class MkdocstringsPlugin(BasePlugin):
("handlers", MkType(dict, default={})),
("default_handler", MkType(str, default="python")),
("custom_templates", MkType(str, default=None)),
+ ("enable_inventory", MkType(bool, default=None)),
)
"""
The configuration options of `mkdocstrings`, written in `mkdocs.yml`.
@@ -105,7 +114,7 @@ def handlers(self) -> Handlers:
raise RuntimeError("The plugin hasn't been initialized with a config yet")
return self._handlers
- def on_serve(self, server: Server, builder: Callable = None, **kwargs) -> Server: # noqa: W0613 (unused arguments)
+ def on_serve(self, server, builder: Callable, **kwargs): # noqa: W0613 (unused arguments)
"""Watch directories.
Hook for the [`on_serve` event](https://www.mkdocs.org/user-guide/plugins/#on_serve).
@@ -117,18 +126,10 @@ def on_serve(self, server: Server, builder: Callable = None, **kwargs) -> Server
server: The `livereload` server instance.
builder: The function to build the site.
kwargs: Additional arguments passed by MkDocs.
-
- Returns:
- The server instance.
"""
- if builder is None:
- # The builder parameter was added in mkdocs v1.1.1.
- # See issue https://github.com/mkdocs/mkdocs/issues/1952.
- builder = list(server.watcher._tasks.values())[0]["func"] # noqa: W0212 (protected member)
for element in self.config["watch"]:
log.debug(f"Adding directory '{element}' to watcher")
server.watch(element, builder)
- return server
def on_config(self, config: Config, **kwargs) -> Config: # noqa: W0613 (unused arguments)
"""Instantiate our Markdown extension.
@@ -155,7 +156,15 @@ def on_config(self, config: Config, **kwargs) -> Config: # noqa: W0613 (unused
else:
theme_name = config["theme"].name
+ to_import: InventoryImportType = []
+ for handler_name, conf in self.config["handlers"].items():
+ for import_item in conf.pop("import", ()):
+ if isinstance(import_item, str):
+ import_item = {"url": import_item}
+ to_import.append((handler_name, import_item))
+
extension_config = {
+ "site_name": config["site_name"],
"theme_name": theme_name,
"mdx": config["markdown_extensions"],
"mdx_configs": config["mdx_configs"],
@@ -163,7 +172,7 @@ def on_config(self, config: Config, **kwargs) -> Config: # noqa: W0613 (unused
}
self._handlers = Handlers(extension_config)
- try:
+ try: # noqa: WPS229
# If autorefs plugin is explicitly enabled, just use it.
autorefs = config["plugins"]["autorefs"]
log.debug(f"Picked up existing autorefs instance {autorefs!r}")
@@ -174,15 +183,61 @@ def on_config(self, config: Config, **kwargs) -> Config: # noqa: W0613 (unused
config["plugins"]["autorefs"] = autorefs
log.debug(f"Added a subdued autorefs instance {autorefs!r}")
# Add collector-based fallback in either case.
- autorefs.get_fallback_anchor = self._handlers.get_anchor
+ autorefs.get_fallback_anchor = self.handlers.get_anchor
- mkdocstrings_extension = MkdocstringsExtension(extension_config, self._handlers, autorefs)
+ mkdocstrings_extension = MkdocstringsExtension(extension_config, self.handlers, autorefs)
config["markdown_extensions"].append(mkdocstrings_extension)
config["extra_css"].insert(0, self.css_filename) # So that it has lower priority than user files.
+ self._inv_futures = []
+ if to_import:
+ inv_loader = futures.ThreadPoolExecutor(4)
+ for handler_name, import_item in to_import: # noqa: WPS440
+ future = inv_loader.submit(
+ self._load_inventory, self.get_handler(handler_name).load_inventory, **import_item
+ )
+ self._inv_futures.append(future)
+ inv_loader.shutdown(wait=False)
+
return config
+ @property
+ def inventory_enabled(self) -> bool:
+ """Tell if the inventory is enabled or not.
+
+ Returns:
+ Whether the inventory is enabled.
+ """
+ inventory_enabled = self.config["enable_inventory"]
+ if inventory_enabled is None:
+ inventory_enabled = any(handler.enable_inventory for handler in self.handlers.seen_handlers)
+ return inventory_enabled
+
+ def on_env(self, env, config: Config, **kwargs):
+ """Extra actions that need to happen after all Markdown rendering and before HTML rendering.
+
+ Hook for the [`on_env` event](https://www.mkdocs.org/user-guide/plugins/#on_env).
+
+ - Write mkdocstrings' extra files into the site dir.
+ - Gather results from background inventory download tasks.
+ """
+ if self._handlers:
+ css_content = "\n".join(handler.renderer.extra_css for handler in self.handlers.seen_handlers)
+ write_file(css_content.encode("utf-8"), os.path.join(config["site_dir"], self.css_filename))
+
+ if self.inventory_enabled:
+ log.debug("Creating inventory file objects.inv")
+ inv_contents = self.handlers.inventory.format_sphinx()
+ write_file(inv_contents, os.path.join(config["site_dir"], "objects.inv"))
+
+ if self._inv_futures:
+ log.debug(f"Waiting for {len(self._inv_futures)} inventory download(s)")
+ futures.wait(self._inv_futures, timeout=30)
+ for page, identifier in collections.ChainMap(*(fut.result() for fut in self._inv_futures)).items():
+ config["plugins"]["autorefs"].register_url(page, identifier)
+ self._inv_futures = []
+
def on_post_build(self, config: Config, **kwargs) -> None: # noqa: W0613,R0201 (unused arguments, cannot be static)
"""Teardown the handlers.
@@ -199,12 +254,12 @@ def on_post_build(self, config: Config, **kwargs) -> None: # noqa: W0613,R0201
config: The MkDocs config object.
kwargs: Additional arguments passed by MkDocs.
"""
- if self._handlers:
- css_content = "\n".join(handler.renderer.extra_css for handler in self.handlers.seen_handlers)
- write_file(css_content.encode("utf-8"), os.path.join(config["site_dir"], self.css_filename))
+ for future in self._inv_futures:
+ future.cancel()
+ if self._handlers:
log.debug("Tearing handlers down")
- self._handlers.teardown()
+ self.handlers.teardown()
def get_handler(self, handler_name: str) -> BaseHandler:
"""Get a handler by its name. See [mkdocstrings.handlers.base.Handlers.get_handler][].
@@ -216,3 +271,26 @@ def get_handler(self, handler_name: str) -> BaseHandler:
An instance of a subclass of [`BaseHandler`][mkdocstrings.handlers.base.BaseHandler].
"""
return self.handlers.get_handler(handler_name)
+
+ @classmethod
+ @functools.lru_cache(maxsize=None)
+ def _load_inventory(cls, loader: InventoryLoaderType, url: str, **kwargs) -> Mapping[str, str]:
+ """Download and process inventory files using a handler.
+
+ Arguments:
+ loader: A function returning a sequence of pairs (identifier, url).
+ url: The URL to download and process.
+ kwargs: Extra arguments to pass to the loader.
+
+ Returns:
+ A mapping from identifier to absolute URL.
+ """
+ log.debug(f"Downloading inventory from {url!r}")
+ req = request.Request(url, headers={"Accept-Encoding": "gzip", "User-Agent": "mkdocstrings/0.15.0"})
+ with request.urlopen(req) as resp: # noqa: S310 (URL audit OK: comes from a checked-in config)
+ content: BinaryIO = resp
+ if "gzip" in resp.headers.get("content-encoding", ""):
+ content = gzip.GzipFile(fileobj=resp) # type: ignore[assignment]
+ result = dict(loader(content, url=url, **kwargs))
+ log.debug(f"Loaded inventory from {url!r}: {len(result)} items")
+ return result
diff --git a/src/mkdocstrings/py.typed b/src/mkdocstrings/py.typed
new file mode 100644
index 00000000..e69de29b
diff --git a/src/mkdocstrings/templates/python/material/attribute.html b/src/mkdocstrings/templates/python/material/attribute.html
index 4b742509..b40518a9 100644
--- a/src/mkdocstrings/templates/python/material/attribute.html
+++ b/src/mkdocstrings/templates/python/material/attribute.html
@@ -17,6 +17,7 @@
{% endif %}
{% filter heading(heading_level,
+ role="data" if obj == module else "attr",
id=html_id,
class="doc doc-heading",
toc_label=attribute.name) %}
@@ -35,6 +36,7 @@
{% else %}
{% if config.show_root_toc_entry %}
{% filter heading(heading_level,
+ role="data" if obj == module else "attr",
id=html_id,
toc_label=attribute.path,
hidden=True) %}
diff --git a/src/mkdocstrings/templates/python/material/attributes.html b/src/mkdocstrings/templates/python/material/attributes.html
index 0c935472..02a2935b 100644
--- a/src/mkdocstrings/templates/python/material/attributes.html
+++ b/src/mkdocstrings/templates/python/material/attributes.html
@@ -12,7 +12,7 @@
{% for attribute in attributes %}
{{ attribute.name }} |
- {{ attribute.annotation }} |
+ {% if attribute.annotation %}{{ attribute.annotation }}{% endif %} |
{{ attribute.description|convert_markdown(heading_level, html_id) }} |
{% endfor %}
diff --git a/src/mkdocstrings/templates/python/material/children.html b/src/mkdocstrings/templates/python/material/children.html
index 967ad493..7bc56c2d 100644
--- a/src/mkdocstrings/templates/python/material/children.html
+++ b/src/mkdocstrings/templates/python/material/children.html
@@ -17,7 +17,7 @@
{% filter heading(heading_level, id=html_id ~ "-attributes") %}Attributes{% endfilter %}
{% endif %}
{% with heading_level = heading_level + extra_level %}
- {% for attribute in obj.attributes|sort(attribute="name") %}
+ {% for attribute in obj.attributes %}
{% include "attribute.html" with context %}
{% endfor %}
{% endwith %}
@@ -26,7 +26,7 @@
{% filter heading(heading_level, id=html_id ~ "-classes") %}Classes{% endfilter %}
{% endif %}
{% with heading_level = heading_level + extra_level %}
- {% for class in obj.classes|sort(attribute="name") %}
+ {% for class in obj.classes %}
{% include "class.html" with context %}
{% endfor %}
{% endwith %}
@@ -35,7 +35,7 @@
{% filter heading(heading_level, id=html_id ~ "-functions") %}Functions{% endfilter %}
{% endif %}
{% with heading_level = heading_level + extra_level %}
- {% for function in obj.functions|sort(attribute="name") %}
+ {% for function in obj.functions %}
{% include "function.html" with context %}
{% endfor %}
{% endwith %}
@@ -44,7 +44,7 @@
{% filter heading(heading_level, id=html_id ~ "-methods") %}Methods{% endfilter %}
{% endif %}
{% with heading_level = heading_level + extra_level %}
- {% for method in obj.methods|sort(attribute="name") %}
+ {% for method in obj.methods %}
{% include "method.html" with context %}
{% endfor %}
{% endwith %}
@@ -53,7 +53,7 @@
{% filter heading(heading_level, id=html_id ~ "-modules") %}Modules{% endfilter %}
{% endif %}
{% with heading_level = heading_level + extra_level %}
- {% for module in obj.modules|sort(attribute="name") %}
+ {% for module in obj.modules %}
{% include "module.html" with context %}
{% endfor %}
{% endwith %}
@@ -62,7 +62,7 @@
{% else %}
- {% for child in obj.children|sort(attribute="name") %}
+ {% for child in obj.children %}
{% if child.category == "attribute" %}
{% with attribute = child %}
{% include "attribute.html" with context %}
diff --git a/src/mkdocstrings/templates/python/material/class.html b/src/mkdocstrings/templates/python/material/class.html
index b3e33f84..62a70f57 100644
--- a/src/mkdocstrings/templates/python/material/class.html
+++ b/src/mkdocstrings/templates/python/material/class.html
@@ -17,11 +17,19 @@
{% endif %}
{% filter heading(heading_level,
+ role="class",
id=html_id,
class="doc doc-heading",
toc_label=class.name) %}
- {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
+
+ {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
+ {% if config.show_bases and class.bases and class.bases != ['object'] %}
+ ({% for base in class.bases -%}
+ {{ base|brief_xref() }}{% if not loop.last %}, {% endif %}
+ {% endfor %})
+ {% endif %}
+
{% with properties = class.properties %}
{% include "properties.html" with context %}
@@ -32,6 +40,7 @@
{% else %}
{% if config.show_root_toc_entry %}
{% filter heading(heading_level,
+ role="class",
id=html_id,
toc_label=class.path,
hidden=True) %}
diff --git a/src/mkdocstrings/templates/python/material/function.html b/src/mkdocstrings/templates/python/material/function.html
index 5ac592b9..6f8e6c77 100644
--- a/src/mkdocstrings/templates/python/material/function.html
+++ b/src/mkdocstrings/templates/python/material/function.html
@@ -17,6 +17,7 @@
{% endif %}
{% filter heading(heading_level,
+ role="function",
id=html_id,
class="doc doc-heading",
toc_label=function.name ~ "()") %}
@@ -35,6 +36,7 @@
{% else %}
{% if config.show_root_toc_entry %}
{% filter heading(heading_level,
+ role="function",
id=html_id,
toc_label=function.path,
hidden=True) %}
diff --git a/src/mkdocstrings/templates/python/material/method.html b/src/mkdocstrings/templates/python/material/method.html
index 19e9a530..807009e5 100644
--- a/src/mkdocstrings/templates/python/material/method.html
+++ b/src/mkdocstrings/templates/python/material/method.html
@@ -17,6 +17,7 @@
{% endif %}
{% filter heading(heading_level,
+ role="method",
id=html_id,
class="doc doc-heading",
toc_label=method.name ~ "()") %}
@@ -35,6 +36,7 @@
{% else %}
{% if config.show_root_toc_entry %}
{% filter heading(heading_level,
+ role="method",
id=html_id,
toc_label=method.path,
hidden=True) %}
diff --git a/src/mkdocstrings/templates/python/material/module.html b/src/mkdocstrings/templates/python/material/module.html
index bff6fdcf..ba8f4eac 100644
--- a/src/mkdocstrings/templates/python/material/module.html
+++ b/src/mkdocstrings/templates/python/material/module.html
@@ -17,6 +17,7 @@
{% endif %}
{% filter heading(heading_level,
+ role="module",
id=html_id,
class="doc doc-heading",
toc_label=module.name) %}
@@ -32,6 +33,7 @@
{% else %}
{% if config.show_root_toc_entry %}
{% filter heading(heading_level,
+ role="module",
id=html_id,
toc_label=module.path,
hidden=True) %}
diff --git a/src/mkdocstrings/templates/python/material/parameters.html b/src/mkdocstrings/templates/python/material/parameters.html
index 8ff69147..321318e0 100644
--- a/src/mkdocstrings/templates/python/material/parameters.html
+++ b/src/mkdocstrings/templates/python/material/parameters.html
@@ -13,7 +13,7 @@
{% for parameter in parameters %}
{{ parameter.name }} |
- {{ parameter.annotation }} |
+ {% if parameter.annotation %}{{ parameter.annotation }}{% endif %} |
{{ parameter.description|convert_markdown(heading_level, html_id) }} |
{% if parameter.default %}{{ parameter.default }}{% else %}required{% endif %} |
diff --git a/src/mkdocstrings/templates/python/material/return.html b/src/mkdocstrings/templates/python/material/return.html
index cb108a1b..f4282491 100644
--- a/src/mkdocstrings/templates/python/material/return.html
+++ b/src/mkdocstrings/templates/python/material/return.html
@@ -9,7 +9,7 @@
- {{ return.annotation }} |
+ {% if return.annotation %}{{ return.annotation }}{% endif %} |
{{ return.description|convert_markdown(heading_level, html_id) }} |
diff --git a/src/mkdocstrings/templates/python/mkdocs/exceptions.html b/src/mkdocstrings/templates/python/mkdocs/exceptions.html
new file mode 100644
index 00000000..f5b592f5
--- /dev/null
+++ b/src/mkdocstrings/templates/python/mkdocs/exceptions.html
@@ -0,0 +1,7 @@
+{{ log.debug() }}
+
+ - Exceptions:
+ {% for exception in exceptions %}
+
- {{ ("`" + exception.annotation + "`: " + exception.description)|convert_markdown(heading_level, html_id) }}
+ {% endfor %}
+
diff --git a/src/mkdocstrings/templates/python/mkdocs/parameters.html b/src/mkdocstrings/templates/python/mkdocs/parameters.html
new file mode 100644
index 00000000..39db7ea3
--- /dev/null
+++ b/src/mkdocstrings/templates/python/mkdocs/parameters.html
@@ -0,0 +1,7 @@
+{{ log.debug() }}
+
+ - Parameters:
+ {% for parameter in parameters %}
+
- {{ ("**" + parameter.name + ":** " + ("`" + parameter.annotation + "` – " if parameter.annotation else "") + parameter.description)|convert_markdown(heading_level, html_id) }}
+ {% endfor %}
+
diff --git a/src/mkdocstrings/templates/python/mkdocs/return.html b/src/mkdocstrings/templates/python/mkdocs/return.html
new file mode 100644
index 00000000..270823c4
--- /dev/null
+++ b/src/mkdocstrings/templates/python/mkdocs/return.html
@@ -0,0 +1,5 @@
+{{ log.debug() }}
+
+ - Returns:
+
- {{ (("`" + return.annotation + "` – " if return.annotation else "") + return.description)|convert_markdown(heading_level, html_id) }}
+
diff --git a/src/mkdocstrings/templates/python/mkdocs/style.css b/src/mkdocstrings/templates/python/mkdocs/style.css
new file mode 100644
index 00000000..9db45032
--- /dev/null
+++ b/src/mkdocstrings/templates/python/mkdocs/style.css
@@ -0,0 +1,11 @@
+.doc-contents {
+ padding-left: 20px;
+}
+
+.doc-contents dd>p {
+ margin-bottom: 0.5rem;
+}
+
+.doc-contents dl+dl {
+ margin-top: -0.5rem;
+}
diff --git a/src/mkdocstrings/templates/python/readthedocs/parameters.html b/src/mkdocstrings/templates/python/readthedocs/parameters.html
index 5ae18219..197a411e 100644
--- a/src/mkdocstrings/templates/python/readthedocs/parameters.html
+++ b/src/mkdocstrings/templates/python/readthedocs/parameters.html
@@ -10,7 +10,7 @@
{% for parameter in parameters %}
- - {{ ("**" + parameter.name + "** (`" + parameter.annotation + "`) – " + parameter.description)|convert_markdown(heading_level, html_id) }}
+ - {{ ("**" + parameter.name + "**" + (" (`" + parameter.annotation + "`)" if parameter.annotation else "") + " – " + parameter.description)|convert_markdown(heading_level, html_id) }}
{% endfor %}
|
diff --git a/src/mkdocstrings/templates/python/readthedocs/return.html b/src/mkdocstrings/templates/python/readthedocs/return.html
index f30b9a25..7e45ecaf 100644
--- a/src/mkdocstrings/templates/python/readthedocs/return.html
+++ b/src/mkdocstrings/templates/python/readthedocs/return.html
@@ -9,7 +9,7 @@
Returns: |
- - {{ ("`" + return.annotation + "` – " + return.description)|convert_markdown(heading_level, html_id) }}
+ - {{ (("`" + return.annotation + "` – ") if return.annotation else "") + return.description)|convert_markdown(heading_level, html_id) }}
|
diff --git a/tests/test_extension.py b/tests/test_extension.py
index e2e92903..3d4a5294 100644
--- a/tests/test_extension.py
+++ b/tests/test_extension.py
@@ -1,4 +1,5 @@
"""Tests for the extension module."""
+import re
import sys
from collections import ChainMap
from textwrap import dedent
@@ -7,14 +8,23 @@
from markdown import Markdown
from mkdocs import config
+try:
+ from mkdocs.config.defaults import get_schema
+except ImportError:
+
+ def get_schema(): # noqa: WPS440
+ """Fallback for old versions of MkDocs."""
+ return config.DEFAULT_SCHEMA
+
@pytest.fixture(name="ext_markdown")
def fixture_ext_markdown(request, tmp_path):
"""Yield a Markdown instance with MkdocstringsExtension, with config adjustments."""
- conf = config.Config(schema=config.DEFAULT_SCHEMA)
+ conf = config.Config(schema=get_schema())
conf_dict = {
"site_name": "foo",
+ "site_url": "https://example.org/",
"site_dir": str(tmp_path),
"plugins": [{"mkdocstrings": {"default_handler": "python"}}],
**getattr(request, "param", {}),
@@ -82,8 +92,7 @@ def test_keeps_preceding_text(ext_markdown):
def test_reference_inside_autodoc(ext_markdown):
"""Assert cross-reference Markdown extension works correctly."""
output = ext_markdown.convert("::: tests.fixtures.cross_reference")
- snippet = 'Link to something.Else.'
- assert snippet in output
+ assert re.search(r"Link to <.*something\.Else.*>something\.Else<.*>\.", output)
@pytest.mark.skipif(sys.version_info < (3, 8), reason="typing.Literal requires Python 3.8")
@@ -152,3 +161,9 @@ def test_no_double_toc(ext_markdown, expect_permalink):
},
{"level": 1, "id": "bb", "name": "bb", "children": []},
]
+
+
+def test_use_custom_handler(ext_markdown):
+ """Assert that we use the custom handler declared in an individual autodoc instruction."""
+ with pytest.raises(ModuleNotFoundError):
+ ext_markdown.convert("::: tests.fixtures.headings\n handler: not_here")
diff --git a/tests/test_inventory.py b/tests/test_inventory.py
new file mode 100644
index 00000000..471ed941
--- /dev/null
+++ b/tests/test_inventory.py
@@ -0,0 +1,51 @@
+"""Tests for the inventory module."""
+
+import sys
+from io import BytesIO
+from os.path import join
+
+import pytest
+from mkdocs.commands.build import build
+from mkdocs.config import load_config
+
+from mkdocstrings.inventory import Inventory, InventoryItem
+
+sphinx = pytest.importorskip("sphinx.util.inventory", reason="Sphinx is not installed")
+
+
+@pytest.mark.parametrize(
+ "our_inv",
+ [
+ Inventory(),
+ Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url")]),
+ Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url#object_path")]),
+ Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url#other_anchor")]),
+ ],
+)
+def test_sphinx_load_inventory_file(our_inv):
+ """Perform the 'live' inventory load test."""
+ buffer = BytesIO(our_inv.format_sphinx())
+ sphinx_inv = sphinx.InventoryFile.load(buffer, "", join)
+
+ sphinx_inv_length = sum(len(sphinx_inv[key]) for key in sphinx_inv)
+ assert sphinx_inv_length == len(our_inv.values())
+
+ for item in our_inv.values():
+ assert item.name in sphinx_inv[f"{item.domain}:{item.role}"]
+
+
+@pytest.mark.skipif(sys.version_info < (3, 7), reason="using plugins that require Python 3.7")
+def test_sphinx_load_mkdocstrings_inventory_file():
+ """Perform the 'live' inventory load test on mkdocstrings own inventory."""
+ mkdocs_config = load_config()
+ build(mkdocs_config)
+ own_inv = mkdocs_config["plugins"]["mkdocstrings"].handlers.inventory
+
+ with open("site/objects.inv", "rb") as fp:
+ sphinx_inv = sphinx.InventoryFile.load(fp, "", join)
+
+ sphinx_inv_length = sum(len(sphinx_inv[key]) for key in sphinx_inv)
+ assert sphinx_inv_length == len(own_inv.values())
+
+ for item in own_inv.values():
+ assert item.name in sphinx_inv[f"{item.domain}:{item.role}"]
diff --git a/tests/test_plugin.py b/tests/test_plugin.py
deleted file mode 100644
index 3bdad73c..00000000
--- a/tests/test_plugin.py
+++ /dev/null
@@ -1,16 +0,0 @@
-"""Tests for the plugin module."""
-
-import sys
-
-import pytest
-from mkdocs.commands.build import build
-from mkdocs.config.base import load_config
-
-
-@pytest.mark.skipif(sys.version_info < (3, 7), reason="using plugins that require Python 3.7")
-@pytest.mark.xfail(sys.version_info >= (3, 9), reason="pytkdocs is failing on Python 3.9")
-def test_plugin(tmp_path):
- """Build our own documentation."""
- config = load_config()
- config["site_dir"] = tmp_path
- build(config)
diff --git a/tests/test_python_handler.py b/tests/test_python_handler.py
new file mode 100644
index 00000000..315b5760
--- /dev/null
+++ b/tests/test_python_handler.py
@@ -0,0 +1,86 @@
+"""Tests for the handlers.python module."""
+
+from copy import deepcopy
+
+from mkdocstrings.handlers.python import ( # noqa: WPS450
+ _sort_key_alphabetical,
+ _sort_key_source,
+ rebuild_category_lists,
+ sort_object,
+)
+
+
+def test_members_order():
+ """Assert that members sorting functions work correctly."""
+ subcategories = {key: [] for key in ("attributes", "classes", "functions", "methods", "modules")}
+ categories = {"children": {}, **subcategories}
+ collected = {
+ "name": "root",
+ "children": {
+ "b": {"name": "b", "source": {"line_start": 0}, **categories},
+ "a": {"name": "a", **categories},
+ "z": {"name": "z", "source": {"line_start": 100}, **categories},
+ "no_name": {"source": {"line_start": 10}, **categories},
+ "c": {
+ "name": "c",
+ "source": {"line_start": 30},
+ "children": {
+ "z": {"name": "z", "source": {"line_start": 200}, **categories},
+ "a": {"name": "a", "source": {"line_start": 20}, **categories},
+ },
+ **subcategories,
+ },
+ },
+ "attributes": ["b", "c", "no_name", "z", "a"],
+ "classes": [],
+ "functions": [],
+ "methods": [],
+ "modules": [],
+ }
+ rebuild_category_lists(collected)
+ alphebetical = deepcopy(collected)
+ sort_object(alphebetical, _sort_key_alphabetical)
+
+ rebuilt_categories = {"children": [], **subcategories}
+ assert (
+ alphebetical["children"]
+ == alphebetical["attributes"]
+ == [
+ {"name": "a", **rebuilt_categories},
+ {"name": "b", "source": {"line_start": 0}, **rebuilt_categories},
+ {
+ "name": "c",
+ "source": {"line_start": 30},
+ "children": [
+ {"name": "a", "source": {"line_start": 20}, **rebuilt_categories},
+ {"name": "z", "source": {"line_start": 200}, **rebuilt_categories},
+ ],
+ **subcategories,
+ },
+ {"name": "z", "source": {"line_start": 100}, **rebuilt_categories},
+ {"source": {"line_start": 10}, **rebuilt_categories},
+ ]
+ )
+
+ source = deepcopy(collected)
+ sort_object(source, _sort_key_source)
+
+ assert (
+ source["children"]
+ == source["attributes"]
+ == [
+ {"name": "a", **rebuilt_categories},
+ {"name": "b", "source": {"line_start": 0}, **rebuilt_categories},
+ {"source": {"line_start": 10}, **rebuilt_categories},
+ {
+ "name": "c",
+ "source": {"line_start": 30},
+ "children": [
+ {"name": "a", "source": {"line_start": 20}, **rebuilt_categories},
+ {"name": "z", "source": {"line_start": 200}, **rebuilt_categories},
+ ],
+ **subcategories,
+ },
+ {"name": "z", "source": {"line_start": 100}, **rebuilt_categories},
+ ]
+ )