Merge pull request #359 from machow/fix-griffe-compat

fix: support griffe v1, and backwards compat to v0.37.0

Author: machow

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
       fail-fast: false
       matrix:
         # Checks based on python versions ---
-        python-version: ['3.9', '3.10']
+        python-version: ["3.9", "3.10"]
         requirements: [""]
 
         include:
@@ -43,7 +43,11 @@ jobs:
           REQUIREMENTS: ${{ matrix.requirements }}
       - name: Run tests
         run: |
-          pytest
+          pytest --cov
+      - name: Upload results to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
 
   pre-commit:
     name: "pre-commit checks"
@@ -55,8 +59,8 @@ jobs:
           python-version: "${{ matrix.python-version }}"
       - name: Install dev dependencies
         run: |
-            python -m pip install --upgrade pip
-            python -m pip install ".[dev]"
+          python -m pip install --upgrade pip
+          python -m pip install ".[dev]"
       - uses: pre-commit/[email protected]
 
   release-pypi:
@@ -94,13 +98,10 @@ jobs:
           python -m pip install shiny shinylive
           python -m pip install --no-deps dascore==0.0.8
       - uses: quarto-dev/quarto-actions/setup@v2
-        with:
-          version: "1.2.475"
       - name: Build docs
         run: |
           make docs-build
       # push to netlify -------------------------------------------------------
-
       # set release name ----
 
       - name: Configure pull release name
@@ -115,7 +116,6 @@ jobs:
           # use branch name, but replace slashes. E.g. feat/a -> feat-a
           echo "RELEASE_NAME=${GITHUB_REF_NAME/\//-}" >> $GITHUB_ENV
       # deploy ----
-
       - name: Create Github Deployment
         uses: bobheadxi/[email protected]
         id: deployment
@@ -125,7 +125,7 @@ jobs:
           env: ${{ env.RELEASE_NAME }}
           ref: ${{ github.head_ref }}
           transient: true
-          logs: 'https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}'
+          logs: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
 
       - name: Netlify docs preview
         run: |
@@ -149,8 +149,8 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           status: ${{ job.status }}
           deployment_id: ${{ steps.deployment.outputs.deployment_id }}
-          env_url: 'https://${{ steps.deployment.outputs.env }}--quartodoc.netlify.app'
-          logs: 'https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}'
+          env_url: "https://${{ steps.deployment.outputs.env }}--quartodoc.netlify.app"
+          logs: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
       - uses: peaceiris/actions-gh-pages@v3
         if: github.event_name == 'release'
         with:

case_studies/parsing.qmd

@@ -55,12 +55,12 @@ res["objects"][0]["children"]["some_package"]["children"]
 ## Running griffe
 
 ```{python}
-from griffe.loader import GriffeLoader
-from griffe.docstrings.parsers import Parser, parse
+from griffe import GriffeLoader
+from griffe import Parser, parse
 
-griffe = GriffeLoader()
+loader = GriffeLoader()
 
-sb2 = griffe.load_module("some_package")
+sb2 = loader.load("some_package")
 
 parse(sb2.functions["some_function"].docstring, Parser.numpy)
 ```

docs/get-started/basic-content.qmd

@@ -66,14 +66,14 @@ By default, all attributes and functions (including methods on a class) are pres
 There are four styles for presenting child members:
 
 ```{python}
-#| echo: false
-#| output: asis
+# | echo: false
+# | output: asis
 
-# print out the attributes table of ChoicesChildren 
+# print out the attributes table of ChoicesChildren
 # this is overkill, but maybe a nice case of dogfooding
 from quartodoc import get_object, MdRenderer
 from quartodoc.builder.utils import extract_type
-from griffe.docstrings.dataclasses import DocstringSectionAttributes
+from griffe import DocstringSectionAttributes
 
 renderer = MdRenderer()
 choices = get_object("quartodoc.layout.ChoicesChildren")
@@ -420,12 +420,12 @@ Below is a summary of all the options that can be applied to individual content
 
 
 ```{python}
-#| echo: false
-#| output: asis
+# | echo: false
+# | output: asis
 
 from quartodoc import get_object, MdRenderer, Auto
 from quartodoc.builder.utils import extract_type
-from griffe.docstrings.dataclasses import DocstringSectionAttributes
+from griffe import DocstringSectionAttributes
 
 renderer = MdRenderer()
 choices = get_object("quartodoc.Auto")

docs/get-started/dev-renderers.qmd

@@ -57,19 +57,20 @@ types of objects.
 ```{python}
 from plum import dispatch
 
-import griffe.dataclasses as dc
-import griffe.docstrings.dataclasses as ds
+from griffe import Alias, Object, Docstring
 
 
 @dispatch
 def render(el: object):
     print(f"Default rendering: {type(el)}")
 
+
 @dispatch
-def render(el: dc.Alias):
+def render(el: Alias):
     print("Alias rendering")
     render(el.parameters)
 
+
 @dispatch
 def render(el: list):
     print("List rendering")
@@ -85,8 +86,7 @@ quartodoc uses tree visitors to render parsed docstrings to formats like markdow
 Tree visitors define how each type of object in the parse tree should be handled.
 
 ```{python}
-import griffe.dataclasses as dc
-import griffe.docstrings.dataclasses as ds
+from griffe import Alias, Object, Docstring
 
 from quartodoc import get_object
 from plum import dispatch
@@ -102,17 +102,17 @@ class SomeRenderer:
         raise NotImplementedError(f"Unsupported type: {type(el)}")
 
     @dispatch
-    def render(self, el: Union[dc.Alias, dc.Object]):
+    def render(self, el: Union[Alias, Object]):
         header = "#" * self.header_level
         str_header = f"{header} {el.name}"
         str_params = f"N PARAMETERS: {len(el.parameters)}"
         str_sections = "SECTIONS: " + self.render(el.docstring)
-        
+
         # return something pretty
         return "\n".join([str_header, str_params, str_sections])
 
     @dispatch
-    def render(self, el: dc.Docstring):
+    def render(self, el: Docstring):
         return f"A docstring with {len(el.parsed)} pieces"
 
 

docs/get-started/extending.qmd

@@ -40,7 +40,7 @@ Then, create the file `reference/index.qmd` to have the form:
 Some custom content.
 
 
-{{< include /reference/_api_index.qmd >}}
+{{{< include /reference/_api_index.qmd >}}}
 
 
 More content stuff.

docs/get-started/sidebar.qmd

@@ -27,6 +27,6 @@ Here is what the sidebar for the [quartodoc reference page](/api) looks like:
 
 <div class="sourceCode">
 <pre class="sourceCode yaml"><code class="sourceCode yaml">
-{{< include /api/_sidebar.yml >}}
+{{{< include /api/_sidebar.yml >}}}
 </code></pre>
 </div>

pyproject.toml

@@ -53,7 +53,14 @@ ci = "https://github.com/machow/quartodoc/actions"
 
 
 [project.optional-dependencies]
-dev = ["pytest<8.0.0", "jupyterlab", "jupytext", "syrupy", "pre-commit"]
+dev = [
+    "pytest<8.0.0",
+    "pytest-cov",
+    "jupyterlab",
+    "jupytext",
+    "syrupy",
+    "pre-commit"
+]
 
 [project.scripts]
 quartodoc = "quartodoc.__main__:cli"

quartodoc/_griffe_compat.py

@@ -0,0 +1,22 @@
+# flake8: noqa
+
+try:
+    from griffe import GriffeLoader
+    from griffe import ModulesCollection, LinesCollection
+
+    import _griffe.models as dataclasses
+    import _griffe.docstrings.models as docstrings
+    import _griffe.expressions as expressions
+
+    from griffe import Parser, parse, parse_numpy
+    from griffe import AliasResolutionError
+except ImportError:
+    from griffe.loader import GriffeLoader
+    from griffe.collections import ModulesCollection, LinesCollection
+
+    import griffe.dataclasses as dataclasses
+    import griffe.docstrings.dataclasses as docstrings
+    import griffe.expressions as expressions
+
+    from griffe.docstrings.parsers import Parser, parse
+    from griffe.exceptions import AliasResolutionError

quartodoc/ast.py

@@ -2,10 +2,11 @@
 
 import warnings
 
+from ._griffe_compat import docstrings as ds
+from ._griffe_compat import dataclasses as dc
+
 from enum import Enum
 from dataclasses import dataclass
-from griffe.docstrings import dataclasses as ds
-from griffe import dataclasses as dc
 from plum import dispatch
 from typing import Type, Union
 

quartodoc/autosummary.py

@@ -5,13 +5,11 @@
 import warnings
 import yaml
 
+from ._griffe_compat import GriffeLoader, ModulesCollection, LinesCollection
+from ._griffe_compat import dataclasses as dc
+from ._griffe_compat import Parser, parse
+
 from fnmatch import fnmatchcase
-from griffe.loader import GriffeLoader
-from griffe.collections import ModulesCollection, LinesCollection
-from griffe.dataclasses import Alias
-from griffe.docstrings.parsers import Parser, parse
-from griffe.docstrings import dataclasses as ds  # noqa
-from griffe import dataclasses as dc
 from plum import dispatch  # noqa
 from pathlib import Path
 from types import ModuleType
@@ -37,7 +35,7 @@
 
 def parse_function(module: str, func_name: str):
     griffe = GriffeLoader()
-    mod = griffe.load_module(module)
+    mod = griffe.load(module)
 
     f_data = mod.functions[func_name]
 
@@ -66,7 +64,7 @@ def get_function(module: str, func_name: str, parser: str = "numpy") -> dc.Objec
     griffe = GriffeLoader(
         docstring_parser=Parser(parser), docstring_options=get_parser_defaults(parser)
     )
-    mod = griffe.load_module(module)
+    mod = griffe.load(module)
 
     f_data = mod.functions[func_name]
 
@@ -138,7 +136,7 @@ def get_object(
     # note that it is critical for performance that we only do this when necessary.
     root_mod = module.split(".", 1)[0]
     if root_mod not in loader.modules_collection:
-        loader.load_module(module)
+        loader.load(module)
 
     # griffe uses only periods for the path
     griffe_path = f"{module}.{object_path}" if object_path else module
@@ -164,10 +162,10 @@ def get_object(
     # Alias objects can refer to objects imported from other modules.
     # in this case, we need to import the target's module in order to resolve
     # the alias
-    if isinstance(f_data, Alias) and load_aliases:
+    if isinstance(f_data, dc.Alias) and load_aliases:
         target_mod = f_data.target_path.split(".")[0]
         if target_mod != module:
-            loader.load_module(target_mod)
+            loader.load(target_mod)
 
     return f_data