diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2104aab9..905739a2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -81,7 +81,7 @@ jobs: # TODO: temporary installs for examples # once quartodoc is stable we should move into their own libraries python -m pip install shiny shinylive - python -m pip install --no-deps dascore + python -m pip install --no-deps dascore==0.0.8 - uses: quarto-dev/quarto-actions/setup@v2 - name: Build docs run: | diff --git a/Makefile b/Makefile index 7dc0ebcc..e2eaf254 100644 --- a/Makefile +++ b/Makefile @@ -13,7 +13,7 @@ docs/examples/%: examples/%/_site rm -rf docs/examples/$* cp -rv $< $@ -docs-build-examples: docs/examples/single-page docs/examples/pkgdown docs/examples/shiny docs/examples/dascore +docs-build-examples: docs/examples/single-page docs/examples/pkgdown docs/examples/shiny docs-build: docs-build-examples cd docs && quarto add --no-prompt .. diff --git a/examples/pkgdown/_quarto.yml b/examples/pkgdown/_quarto.yml index 635a239c..8e88a29c 100644 --- a/examples/pkgdown/_quarto.yml +++ b/examples/pkgdown/_quarto.yml @@ -24,6 +24,7 @@ format: quartodoc: style: pkgdown dir: reference + display_name: relative package: quartodoc sections: - title: Some functions @@ -31,3 +32,5 @@ quartodoc: contents: - get_object - preview + - Builder + - Builder.build diff --git a/examples/pkgdown/objects.json b/examples/pkgdown/objects.json index f5421174..9210b6c4 100644 --- a/examples/pkgdown/objects.json +++ b/examples/pkgdown/objects.json @@ -1 +1 @@ -{"project": "quartodoc", "version": "0.0.9999", "count": 2, "items": [{"name": "quartodoc.get_object", "domain": "py", "role": "function", "priority": "1", "uri": "reference/get_object.html", "dispname": "get_object"}, {"name": "quartodoc.preview", "domain": "py", "role": "function", "priority": "1", "uri": "reference/preview.html", "dispname": "preview"}]} \ No newline at end of file +{"project": "quartodoc", "version": "0.0.9999", "count": 4, "items": [{"name": "quartodoc.get_object", "domain": "py", "role": "function", "priority": "1", "uri": "reference/get_object.html", "dispname": "get_object"}, {"name": "quartodoc.preview", "domain": "py", "role": "function", "priority": "1", "uri": "reference/preview.html", "dispname": "preview"}, {"name": "quartodoc.Builder", "domain": "py", "role": "class", "priority": "1", "uri": "reference/Builder.html", "dispname": "Builder"}, {"name": "quartodoc.Builder.build", "domain": "py", "role": "function", "priority": "1", "uri": "reference/Builder.build.html", "dispname": "Builder.build"}]} \ No newline at end of file diff --git a/examples/pkgdown/reference/Builder.build.qmd b/examples/pkgdown/reference/Builder.build.qmd new file mode 100644 index 00000000..c28deb47 --- /dev/null +++ b/examples/pkgdown/reference/Builder.build.qmd @@ -0,0 +1,5 @@ +## build { #build } + +`build(self)` + +Build index page, sphinx inventory, and individual doc pages. \ No newline at end of file diff --git a/examples/pkgdown/reference/Builder.qmd b/examples/pkgdown/reference/Builder.qmd new file mode 100644 index 00000000..cfed5959 --- /dev/null +++ b/examples/pkgdown/reference/Builder.qmd @@ -0,0 +1,19 @@ +## Builder { #Builder } + +`Builder(self, package, sections, version=None, dir='reference', title='Function reference', renderer='markdown', out_index=None, sidebar=None, use_interlinks=False, display_name='name')` + +Base class for building API docs. + +### Parameters + +| Name | Type | Description | Default | +|----------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------| +| `package` | str | The name of the package. | required | +| `sections` | list[Any] | A list of sections, with items to document. | required | +| `version` | str \| None | The package version. By default this attempts to look up the current package version (TODO). | `None` | +| `dir` | str | Name of API directory. | `'reference'` | +| `title` | str | Title of the API index page. | `'Function reference'` | +| `renderer` | dict \| Renderer \| str | The renderer used to convert docstrings (e.g. to markdown). | `'markdown'` | +| `out_index` | str | The output path of the index file, used to list all API functions. | `None` | +| `sidebar` | str \| None | The output path for a sidebar yaml config (by default no config generated). | `None` | +| `display_name` | str | The default name shown for documented functions. Either "name", "relative", "full", or "canonical". These options range from just the function name, to its full path relative to its package, to including the package name, to its the its full path relative to its .__module__. | `'name'` | \ No newline at end of file diff --git a/examples/pkgdown/reference/index.qmd b/examples/pkgdown/reference/index.qmd index d937196e..11f94cbf 100644 --- a/examples/pkgdown/reference/index.qmd +++ b/examples/pkgdown/reference/index.qmd @@ -7,4 +7,6 @@ These functions inspect and parse docstrings. | | | | --- | --- | | [get_object](/reference/get_object.qmd) | Fetch a griffe object. | -| [preview](/reference/preview.qmd) | Print a friendly representation of a griffe object (e.g. function, docstring) | \ No newline at end of file +| [preview](/reference/preview.qmd) | Print a friendly representation of a griffe object (e.g. function, docstring) | +| [Builder](/reference/Builder.qmd) | Base class for building API docs. | +| [Builder.build](/reference/Builder.build.qmd) | Build index page, sphinx inventory, and individual doc pages. | \ No newline at end of file diff --git a/examples/single-page/_quarto.yml b/examples/single-page/_quarto.yml index 25ef8c36..48170c1d 100644 --- a/examples/single-page/_quarto.yml +++ b/examples/single-page/_quarto.yml @@ -23,6 +23,7 @@ format: quartodoc: style: single-page dir: reference + display_name: relative package: quartodoc sections: - title: Some functions @@ -30,3 +31,5 @@ quartodoc: contents: - get_object - preview + - Builder + - Builder.build diff --git a/examples/single-page/objects.json b/examples/single-page/objects.json index bb16ef34..28d41785 100644 --- a/examples/single-page/objects.json +++ b/examples/single-page/objects.json @@ -1 +1 @@ -{"project": "quartodoc", "version": "0.0.9999", "count": 2, "items": [{"name": "quartodoc.get_object", "domain": "py", "role": "function", "priority": "1", "uri": "reference/index.html#quartodoc.get_object", "dispname": "get_object"}, {"name": "quartodoc.preview", "domain": "py", "role": "function", "priority": "1", "uri": "reference/index.html#quartodoc.preview", "dispname": "preview"}]} \ No newline at end of file +{"project": "quartodoc", "version": "0.0.9999", "count": 4, "items": [{"name": "quartodoc.get_object", "domain": "py", "role": "function", "priority": "1", "uri": "reference/index.html#quartodoc.get_object", "dispname": "get_object"}, {"name": "quartodoc.preview", "domain": "py", "role": "function", "priority": "1", "uri": "reference/index.html#quartodoc.preview", "dispname": "preview"}, {"name": "quartodoc.Builder", "domain": "py", "role": "class", "priority": "1", "uri": "reference/index.html#quartodoc.Builder", "dispname": "Builder"}, {"name": "quartodoc.Builder.build", "domain": "py", "role": "function", "priority": "1", "uri": "reference/index.html#quartodoc.Builder.build", "dispname": "Builder.build"}]} \ No newline at end of file diff --git a/examples/single-page/reference/index.qmd b/examples/single-page/reference/index.qmd index c49a8a76..97d88d4c 100644 --- a/examples/single-page/reference/index.qmd +++ b/examples/single-page/reference/index.qmd @@ -46,4 +46,30 @@ Print a friendly representation of a griffe object (e.g. function, docstring) ```python >>> preview(obj) ... -``` \ No newline at end of file +``` + +## Builder { #Builder } + +`Builder(self, package, sections, version=None, dir='reference', title='Function reference', renderer='markdown', out_index=None, sidebar=None, use_interlinks=False, display_name='name')` + +Base class for building API docs. + +### Parameters + +| Name | Type | Description | Default | +|----------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------| +| `package` | str | The name of the package. | required | +| `sections` | list[Any] | A list of sections, with items to document. | required | +| `version` | str \| None | The package version. By default this attempts to look up the current package version (TODO). | `None` | +| `dir` | str | Name of API directory. | `'reference'` | +| `title` | str | Title of the API index page. | `'Function reference'` | +| `renderer` | dict \| Renderer \| str | The renderer used to convert docstrings (e.g. to markdown). | `'markdown'` | +| `out_index` | str | The output path of the index file, used to list all API functions. | `None` | +| `sidebar` | str \| None | The output path for a sidebar yaml config (by default no config generated). | `None` | +| `display_name` | str | The default name shown for documented functions. Either "name", "relative", "full", or "canonical". These options range from just the function name, to its full path relative to its package, to including the package name, to its the its full path relative to its .__module__. | `'name'` | + +## build { #build } + +`build(self)` + +Build index page, sphinx inventory, and individual doc pages. \ No newline at end of file diff --git a/quartodoc/autosummary.py b/quartodoc/autosummary.py index 3429c13e..1353a431 100644 --- a/quartodoc/autosummary.py +++ b/quartodoc/autosummary.py @@ -103,8 +103,20 @@ def get_object( ) mod = griffe.load_module(module) + parts = object_name.split(".") f_data = mod._modules_collection[f"{module}.{object_name}"] + # ensure that function methods fetched off of an Alias of a class, have that + # class Alias as their parent, not the Class itself. + if isinstance(f_data, dc.Function): + try: + parent_path = ".".join(parts[:-1]) + parent_alias = mod._modules_collection[f"{module}.{parent_path}"] + except KeyError: + pass + else: + f_data = dc.Alias(f_data.name, f_data, parent=parent_alias) + # 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 diff --git a/requirements-dev.txt b/requirements-dev.txt index 0d8fbb36..dfb82a03 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.8 +# This file is autogenerated by pip-compile with Python 3.10 # by the following command: # # pip-compile --extra=dev --output-file=requirements-dev.txt setup.cfg @@ -58,19 +58,14 @@ executing==1.2.0 # via stack-data fastjsonschema==2.16.2 # via nbformat -griffe==0.24.1 +griffe==0.25.5 # via quartodoc (setup.cfg) idna==3.4 # via # anyio # requests importlib-metadata==5.1.0 - # via - # jupyterlab-server - # nbconvert - # quartodoc (setup.cfg) -importlib-resources==5.10.1 - # via jsonschema + # via quartodoc (setup.cfg) iniconfig==1.1.1 # via pytest ipykernel==6.17.1 @@ -198,8 +193,6 @@ pexpect==4.8.0 # via ipython pickleshare==0.7.5 # via ipython -pkgutil-resolve-name==1.3.10 - # via jsonschema platformdirs==2.5.4 # via jupyter-core pluggy==1.0.0 @@ -316,6 +309,4 @@ webencodings==0.5.1 websocket-client==1.4.2 # via jupyter-server zipp==3.11.0 - # via - # importlib-metadata - # importlib-resources + # via importlib-metadata diff --git a/setup.cfg b/setup.cfg index 87017f79..8af888ee 100644 --- a/setup.cfg +++ b/setup.cfg @@ -22,7 +22,7 @@ zipsafe = False python_requires = >3.8 install_requires = - griffe + griffe>=0.25 plum-dispatch sphobjinv tabulate