Merge branch 'master' into publish-workflow

.editorconfig

@@ -0,0 +1,5 @@
+[*]
+end_of_line = lf
+
+[*.cmd]
+end_of_line = crlf

.gitattributes

@@ -0,0 +1,9 @@
+# By default, convert line endings automatically.
+* text=auto
+
+# Declare files that will always have LF line endings on checkout.
+*.py text eol=lf
+*.sh text eol=lf
+
+# Declare files that will always have CRLF line endings on checkout.
+*.cmd text eol=crlf

.github/workflows/black.yml

@@ -1,9 +1,10 @@
-name: Lint
+name: Lint with Black
 
 on: [push, pull_request]
 
 jobs:
-  lint:
+  black:
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

.github/workflows/mypy.yml

@@ -0,0 +1,23 @@
+name: Lint with MyPy
+
+on: [push, pull_request]
+
+jobs:
+  mypy:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -c ci-constraints.txt . -r mypy-requirements.txt -r test-requirements.txt
+
+      - name: Run MyPy
+        run: |
+          mypy .

.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: Test
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+    timeout-minutes: 120
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        timeout-minutes: 10
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+        timeout-minutes: 10
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -c ci-constraints.txt -r test-requirements.txt .
+        timeout-minutes: 10
+
+      - name: Test
+        run: |
+          python -m unittest
+        timeout-minutes: 60

README.md

@@ -1,3 +1,51 @@
 # mkdocstrings-vba
 
 A VBA handler for [mkdocstrings](https://github.com/mkdocstrings/mkdocstrings).
+
+Since there is no official way of documenting VBA functions, we have opted for
+the [Google Docstring format](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) commonly used
+in Python projects. This is conveniently parsed by the [`griffe`](https://mkdocstrings.github.io/griffe) library which
+is also used by [`mkdocstrings[python]`](https://mkdocstrings.github.io/python/). The argument types and return types
+are taken from the
+VBA [Function](https://learn.microsoft.com/en-us/office/vba/language/reference/user-interface-help/function-statement)
+or [Sub](https://learn.microsoft.com/en-us/office/vba/language/reference/user-interface-help/sub-statement) signatures,
+which we parse using [regex](https://regular-expressions.info).
+
+## Examples
+
+See the [`examples`](examples) folder.
+
+To build an example site:
+
+1. `pip install mkdocstrings mkdocstrings-vba`
+2. `cd examples/example1`
+3. View the source code.
+4. `mkdocs build`
+5. cd `site/`
+6. View the results.
+
+## Running tests
+
+```shell
+pip install -r test-requirements.txt
+python -m unittest
+```
+
+This will run all tests. This includes
+- Unit tests from `tests/`.
+- Doctests from `mkdocstrings_vba/`.
+- Full builds from `examples/`.
+
+## Linting
+
+Fix code style using `black`:
+
+```shell
+black .
+```
+
+Check types using `mypy`:
+
+```shell
+mypy .
+```

ci-constraints.txt

@@ -0,0 +1,3 @@
+mkdocstrings==0.22.0
+griffe==0.34.0
+mkdocs-material==9.2.1

test/example1/mkdocs.yml → examples/example1/mkdocs.yml

@@ -6,4 +6,3 @@ plugins:
   - mkdocstrings:
       handlers:
         vba: { }
-        python: { }

test/example1/src/foo.bas → examples/example1/src/foo.bas

@@ -3,6 +3,7 @@ Attribute VB_Name = "foo"
 ' Like all other, it can be multiple lines
 '
 ' Examples:
+'
 '     >>> foo(bar)
 '     baz
 
@@ -18,7 +19,7 @@ Function fuzz_HotelEcho_helper( _
     ' Arguments:
     '     WS: The worksheet
     '     Name: The name
-    '     Description: The description
+    '     description: The description
     '
     ' Examples:
     '     >>> fuzz_HotelEcho_helper(sheet, "foo", "the sheet")

mkdocstrings_handlers/vba/__init__.py

@@ -1,5 +1,5 @@
 """This package implements a handler for the VBA language."""
 
-from mkdocstrings_handlers.vba.handler import get_handler
+from ._handler import get_handler
 
 __all__ = ["get_handler"]

mkdocstrings_handlers/vba/_crossref.py

@@ -0,0 +1,50 @@
+import re
+
+from markupsafe import Markup
+
+
+def do_crossref(path: str, brief: bool = True) -> Markup:
+    """Filter to create cross-references.
+
+    Parameters:
+        path: The path to link to.
+        brief: Show only the last part of the path, add the full path as hover.
+
+    Returns:
+        Markup text.
+    """
+    full_path = path
+    if brief:
+        path = full_path.split(".")[-1]
+    return Markup(
+        "<span data-autorefs-optional-hover={full_path}>{path}</span>"
+    ).format(full_path=full_path, path=path)
+
+
+def do_multi_crossref(text: str, code: bool = True) -> Markup:
+    """Filter to create cross-references.
+
+    Parameters:
+        text: The text to scan.
+        code: Whether to wrap the result in a code tag.
+
+    Returns:
+        Markup text.
+    """
+    group_number = 0
+    variables = {}
+
+    def repl(match: re.Match[str]) -> str:
+        nonlocal group_number
+        group_number += 1
+        path = match.group()
+        path_var = f"path{group_number}"
+        variables[path_var] = path
+        return (
+            f"<span data-autorefs-optional-hover={{{path_var}}}>{{{path_var}}}</span>"
+        )
+
+    text = re.sub(r"([\w.]+)", repl, text)
+    if code:
+        text = f"<code>{text}</code>"
+    return Markup(text).format(**variables)