Merge pull request #21 from mkdocstrings/issue-17-return-types

#17 Show return types

Author: rudolfbyker

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

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(...)

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:
@@ -177,23 +175,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`.

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,
                 ),
             )
 

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 %}

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__":

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=[