From 243e235742b0db4e483f701ad2e5cc0cf1a85b09 Mon Sep 17 00:00:00 2001 From: dolf Date: Thu, 19 Sep 2024 23:04:26 +0200 Subject: [PATCH 1/8] #17 Add more unit tests to check that the return type of VBA function signatures are parsed correctly. --- test/util/test_parse_signature.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/test/util/test_parse_signature.py b/test/util/test_parse_signature.py index 4547678..80a3a93 100644 --- a/test/util/test_parse_signature.py +++ b/test/util/test_parse_signature.py @@ -57,10 +57,20 @@ def test_1(self) -> None: ), ), ( - "Function Test(Optional d As Variant = Empty)", + "Public Property Get asdf() As String", + VbaSignatureInfo( + visibility="Public", + return_type="String", + procedure_type="Property Get", + name="asdf", + args=[], + ), + ), + ( + "Function Test(Optional d As Variant = Empty) As String", VbaSignatureInfo( visibility=None, - return_type=None, + return_type="String", procedure_type="Function", name="Test", args=[ From 93366dbdf8e2f9c991a3f0af1d2e7ec4565df4be Mon Sep 17 00:00:00 2001 From: dolf Date: Thu, 19 Sep 2024 23:15:31 +0200 Subject: [PATCH 2/8] Remove unused arguments from `get_handler`. --- mkdocstrings_handlers/vba/_handler.py | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/mkdocstrings_handlers/vba/_handler.py b/mkdocstrings_handlers/vba/_handler.py index afc716e..d4f2b48 100644 --- a/mkdocstrings_handlers/vba/_handler.py +++ b/mkdocstrings_handlers/vba/_handler.py @@ -177,23 +177,19 @@ def get_anchors(self, data: VbaModuleInfo) -> Tuple[str, ...]: def get_handler( *, - theme: str, + theme: str = "material", custom_templates: str | None = None, config_file_path: str | None = None, - paths: list[str] | None = None, - locale: str = "en", - **config: Any, + **kwargs: Any, ) -> VbaHandler: """ - Simply return an instance of `VbaHandler`. + Get a new `VbaHandler`. Arguments: theme: The theme to use when rendering contents. custom_templates: Directory containing custom templates. config_file_path: The MkDocs configuration file path. - paths: A list of paths to use as Griffe search paths. - locale: The locale to use when rendering content. - **config: Configuration passed to the handler. + kwargs: Extra keyword arguments that we don't use. Returns: An instance of `VbaHandler`. From 12681fbbd673eba7084b5ef0e6c9d3c56005f9d4 Mon Sep 17 00:00:00 2001 From: dolf Date: Thu, 19 Sep 2024 23:46:37 +0200 Subject: [PATCH 3/8] Pass keyword arguments instead of unpacking a dictionary. --- mkdocstrings_handlers/vba/_handler.py | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/mkdocstrings_handlers/vba/_handler.py b/mkdocstrings_handlers/vba/_handler.py index d4f2b48..af4b8ad 100644 --- a/mkdocstrings_handlers/vba/_handler.py +++ b/mkdocstrings_handlers/vba/_handler.py @@ -154,12 +154,10 @@ def render( ) return template.render( - **{ - "config": final_config, - "module": data, - "heading_level": heading_level, - "root": True, - }, + config=final_config, + module=data, + heading_level=heading_level, + root=True, ) def update_env(self, md: Markdown, config: Dict[Any, Any]) -> None: From bb14125a0e02b6a08c9e580db40c985c878a2630 Mon Sep 17 00:00:00 2001 From: dolf Date: Thu, 19 Sep 2024 23:51:30 +0200 Subject: [PATCH 4/8] #17 Assert that examples do not log warnings. --- test/test_examples.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/test/test_examples.py b/test/test_examples.py index c3f2241..d4a04b6 100644 --- a/test/test_examples.py +++ b/test/test_examples.py @@ -1,5 +1,6 @@ import unittest from contextlib import contextmanager +from logging import WARNING from pathlib import Path from tempfile import TemporaryDirectory from typing import Generator @@ -29,9 +30,10 @@ def tmp_build(config_file_path: Path) -> Generator[Path, None, None]: class TestExamples(unittest.TestCase): def test_example1(self) -> None: - with tmp_build(examples_dir.joinpath("example1", "mkdocs.yml")) as tmp_dir: - # TODO: Write assertions. For now, just check that it does not fail. - pass + with self.assertNoLogs(level=WARNING): + with tmp_build(examples_dir.joinpath("example1", "mkdocs.yml")) as tmp_dir: + # TODO: Write assertions. For now, just check that it does not fail. + pass if __name__ == "__main__": From a760d77bc64ebcde9d4aa3247a1ca5ce97073e30 Mon Sep 17 00:00:00 2001 From: dolf Date: Thu, 19 Sep 2024 23:51:50 +0200 Subject: [PATCH 5/8] #17 Add failing test. --- examples/example1/src/foo.bas | 3 +++ 1 file changed, 3 insertions(+) diff --git a/examples/example1/src/foo.bas b/examples/example1/src/foo.bas index 518e4d8..0fc0caa 100644 --- a/examples/example1/src/foo.bas +++ b/examples/example1/src/foo.bas @@ -21,6 +21,9 @@ Function fuzz_HotelEcho_helper( _ ' Name: The name ' description: The description ' + ' Returns: + ' A fancy ListObject + ' ' Examples: ' >>> fuzz_HotelEcho_helper(sheet, "foo", "the sheet") ' ListObject(...) From 877388ee5085c6ca28d48927ef86839d4aa1b0ff Mon Sep 17 00:00:00 2001 From: dolf Date: Fri, 20 Sep 2024 00:07:06 +0200 Subject: [PATCH 6/8] #17 Bugfix: Let Griffe know about our function return type. --- mkdocstrings_handlers/vba/_util.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mkdocstrings_handlers/vba/_util.py b/mkdocstrings_handlers/vba/_util.py index 640bcf9..6b8af72 100644 --- a/mkdocstrings_handlers/vba/_util.py +++ b/mkdocstrings_handlers/vba/_util.py @@ -162,7 +162,7 @@ def find_procedures(code: str) -> Generator[VbaProcedureInfo, None, None]: docstring_value = "\n".join(uncomment_lines(docstring_lines)) - # See https://mkdocstrings.github.io/griffe/usage/#using-griffe-as-a-docstring-parsing-library + # See https://mkdocstrings.github.io/griffe/guide/users/how-to/parse-docstrings/ docstring = Docstring( value=docstring_value, parser=Parser.google, @@ -180,6 +180,7 @@ def find_procedures(code: str) -> Generator[VbaProcedureInfo, None, None]: for arg in procedure["signature"].args ) ), + returns=procedure["signature"].return_type, ), ) From 81c4dbf284e9db45658dd8a3c8e4443b069cbd9a Mon Sep 17 00:00:00 2001 From: dolf Date: Fri, 20 Sep 2024 00:16:11 +0200 Subject: [PATCH 7/8] Fix heading levels in example1 --- examples/example1/docs/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/examples/example1/docs/index.md b/examples/example1/docs/index.md index beaebb5..689241d 100644 --- a/examples/example1/docs/index.md +++ b/examples/example1/docs/index.md @@ -4,8 +4,12 @@ ::: src/foo.bas handler: vba + options: + heading_level: 3 ## `bar/baz.bas` ::: src/bar/baz.bas handler: vba + options: + heading_level: 3 From 6ef364acc28e289a4285fd021b7f3937d8767f12 Mon Sep 17 00:00:00 2001 From: dolf Date: Fri, 20 Sep 2024 00:19:27 +0200 Subject: [PATCH 8/8] #17 Show the procedure visibility and type --- .../vba/templates/material/_base/procedure.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mkdocstrings_handlers/vba/templates/material/_base/procedure.html b/mkdocstrings_handlers/vba/templates/material/_base/procedure.html index 5fb6a89..c868bb9 100644 --- a/mkdocstrings_handlers/vba/templates/material/_base/procedure.html +++ b/mkdocstrings_handlers/vba/templates/material/_base/procedure.html @@ -13,10 +13,10 @@ toc_label=procedure.signature.name ~ "()") %} {% if config.separate_signature %} - {{ procedure.signature.name }}() + {{ procedure.signature.visibility }} {{ procedure.signature.procedure_type }} {{ procedure.signature.name }}() {% else %} {% filter highlight(language="vba", inline=True) %} - {{ procedure.signature.name }} + {{ procedure.signature.visibility }} {{ procedure.signature.procedure_type }} {{ procedure.signature.name }} {% include "signature.html" with context %} {% endfilter %} {% endif %}