Skip to content

Update mkdocstrings and griffe to the latest versions. #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 19, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Update mkdocstrings and griffe to the latest versions. Remove some un…
…necessary code from the Handler.
  • Loading branch information
rudolfbyker committed Sep 19, 2024
commit e3441fbcf3aad2138a58a569c6142406a40542c1
115 changes: 43 additions & 72 deletions mkdocstrings_handlers/vba/_handler.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,26 +5,21 @@
from __future__ import annotations

import copy
import posixpath
from collections import ChainMap
from pathlib import Path
from typing import (
Any,
BinaryIO,
Iterator,
Optional,
Tuple,
MutableMapping,
Dict,
Mapping,
Set,
Tuple,
)

from griffe.logger import patch_loggers
from griffe import patch_loggers
from markdown import Markdown
from mkdocs.exceptions import PluginError
from mkdocstrings.handlers.base import BaseHandler
from mkdocstrings.inventory import Inventory
from mkdocstrings.handlers.base import BaseHandler, CollectionError
from mkdocstrings.loggers import get_logger

from ._crossref import do_crossref, do_multi_crossref
Expand All @@ -49,14 +44,14 @@ def __init__(self, *, base_dir: Path, **kwargs: Any) -> None:
super().__init__(**kwargs)
self.base_dir = base_dir

domain: str = "vba"
name: str = "vba"
"""
The cross-documentation domain/language for this handler.
The handler's name.
"""

enable_inventory: bool = True
domain: str = "vba"
"""
Whether this handler is interested in enabling the creation of the `objects.inv` Sphinx inventory file.
The cross-documentation domain/language for this handler.
"""

fallback_theme = "material"
Expand All @@ -83,9 +78,7 @@ def __init__(self, *, base_dir: Path, **kwargs: Any) -> None:
"docstring_section_style": "table",
}
"""
The default rendering options.

See [`default_config`][mkdocstrings_handlers.vba.renderer.VbaRenderer.default_config].
The default handler configuration.

Option | Type | Description | Default
------ | ---- | ----------- | -------
Expand All @@ -107,32 +100,38 @@ def __init__(self, *, base_dir: Path, **kwargs: Any) -> None:
**`docstring_section_style`** | `str` | The style used to render docstring sections. Options: `table`, `list`, `spacy`. | `table`
"""

@classmethod
def load_inventory(
cls,
in_file: BinaryIO,
url: str,
base_url: Optional[str] = None,
**kwargs: Any,
) -> 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).
def collect(
self,
identifier: str,
config: MutableMapping[str, Any],
) -> VbaModuleInfo:
"""Collect the documentation tree given an identifier and selection options.

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.
identifier: Which VBA file (.bas or .cls) to collect from.
config: Selection options, used to alter the data collection.

Yields:
Tuples of (item identifier, item URL).
Raises:
CollectionError: When there was a problem collecting the documentation.

Returns:
The collected object tree.
"""
if base_url is None:
base_url = posixpath.dirname(url)
p = Path(self.base_dir, identifier)
if not p.exists():
raise CollectionError("File not found.")

with p.open("r") as f:
code = f.read()

for item in Inventory.parse_sphinx(in_file, domain_filter=("py",)).values():
yield item.name, posixpath.join(base_url, item.uri)
code = collapse_long_lines(code)

return VbaModuleInfo(
docstring=find_file_docstring(code),
source=code.splitlines(),
path=p,
procedures=list(find_procedures(code)),
)

def render(
self,
Expand Down Expand Up @@ -163,9 +162,6 @@ def render(
},
)

def get_anchors(self, data: VbaModuleInfo) -> Set[str]:
return {data.path.as_posix(), *(p.signature.name for p in data.procedures)}

def update_env(self, md: Markdown, config: Dict[Any, Any]) -> None:
super().update_env(md, config)
self.env.trim_blocks = True
Expand All @@ -175,38 +171,12 @@ def update_env(self, md: Markdown, config: Dict[Any, Any]) -> None:
self.env.filters["multi_crossref"] = do_multi_crossref
self.env.filters["order_members"] = do_order_members

def collect(
self,
identifier: str,
config: MutableMapping[str, Any],
) -> VbaModuleInfo:
"""Collect the documentation tree given an identifier and selection options.

Arguments:
identifier: Which VBA file (.bas or .cls) to collect from.
config: Selection options, used to alter the data collection.

Raises:
CollectionError: When there was a problem collecting the documentation.

Returns:
The collected object tree.
"""
p = Path(self.base_dir, identifier)
with p.open("r") as f:
code = f.read()

code = collapse_long_lines(code)

return VbaModuleInfo(
docstring=find_file_docstring(code),
source=code.splitlines(),
path=p,
procedures=list(find_procedures(code)),
)
def get_anchors(self, data: VbaModuleInfo) -> Tuple[str, ...]:
return data.path.as_posix(), *(p.signature.name for p in data.procedures)


def get_handler(
*,
theme: str,
custom_templates: str | None = None,
config_file_path: str | None = None,
Expand All @@ -229,11 +199,12 @@ def get_handler(
An instance of `VbaHandler`.
"""
return VbaHandler(
base_dir=Path(config_file_path or ".").parent,
base_dir=(
Path(config_file_path).resolve().parent
if config_file_path
else Path(".").resolve()
),
handler="vba",
theme=theme,
custom_templates=custom_templates,
config_file_path=config_file_path,
paths=paths,
locale=locale,
)
2 changes: 1 addition & 1 deletion mkdocstrings_handlers/vba/_sort.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
import sys
from typing import Any, Sequence

from griffe.dataclasses import Alias, Object
from griffe import Alias, Object
from mkdocstrings.handlers.base import CollectorItem


Expand Down
2 changes: 1 addition & 1 deletion mkdocstrings_handlers/vba/_types.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
from pathlib import Path
from typing import List, Optional

from griffe.dataclasses import Docstring
from griffe import Docstring


@dataclass
Expand Down
3 changes: 1 addition & 2 deletions mkdocstrings_handlers/vba/_util.py
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
import re
from typing import List, Generator

from griffe.dataclasses import Docstring, Function, Parameters, Parameter
from griffe.docstrings import Parser
from griffe import Docstring, Function, Parameters, Parameter, Parser

from ._regex import re_signature, re_arg
from ._types import (
Expand Down
6 changes: 3 additions & 3 deletions mypy-requirements.txt
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
mypy==1.5.1
types-setuptools
types-Markdown
mypy==1.11.2
types-setuptools==75.*
types-Markdown==3.*
4 changes: 2 additions & 2 deletions setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@
"setuptools_scm",
],
install_requires=[
"mkdocstrings>=0.22,<0.23",
"griffe>=0.34,<0.35",
"mkdocstrings>=0.26.1,<1",
"griffe>=1.3.1,<2",
"mkdocs-material>=9.2,<10",
],
include_package_data=True,
Expand Down
Loading