Skip to content

Commit

Permalink
Merge pull request #49 from machow/feat-func-alias
Browse files Browse the repository at this point in the history 
Feat func alias
  • Loading branch information
@machow
machow authored Feb 23, 2023
2 parents 6d0fbca + edc1c34 commit 25bc5a2
Show file tree
Hide file tree
Showing 13 changed files with 81 additions and 20 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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: |
Expand Down
2 changes: 1 addition & 1 deletion Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 ..
Expand Down
3 changes: 3 additions & 0 deletions examples/pkgdown/_quarto.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,13 @@ format:
quartodoc:
style: pkgdown
dir: reference
display_name: relative
package: quartodoc
sections:
- title: Some functions
desc: These functions inspect and parse docstrings.
contents:
- get_object
- preview
- Builder
- Builder.build
2 changes: 1 addition & 1 deletion examples/pkgdown/objects.json
View file
Original file line number Diff line number Diff line change
@@ -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"}]}
{"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"}]}
5 changes: 5 additions & 0 deletions examples/pkgdown/reference/Builder.build.qmd
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
## build { #build }

`build(self)`

Build index page, sphinx inventory, and individual doc pages.
19 changes: 19 additions & 0 deletions examples/pkgdown/reference/Builder.qmd
View file
Original file line number Diff line number Diff line change
@@ -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'` |
4 changes: 3 additions & 1 deletion examples/pkgdown/reference/index.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
| [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. |
3 changes: 3 additions & 0 deletions examples/single-page/_quarto.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,13 @@ format:
quartodoc:
style: single-page
dir: reference
display_name: relative
package: quartodoc
sections:
- title: Some functions
desc: These functions inspect and parse docstrings.
contents:
- get_object
- preview
- Builder
- Builder.build
2 changes: 1 addition & 1 deletion examples/single-page/objects.json
View file
Original file line number Diff line number Diff line change
@@ -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"}]}
{"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"}]}
28 changes: 27 additions & 1 deletion examples/single-page/reference/index.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,4 +46,30 @@ Print a friendly representation of a griffe object (e.g. function, docstring)
```python
>>> preview(obj)
...
```
```

## 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.
12 changes: 12 additions & 0 deletions quartodoc/autosummary.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
17 changes: 4 additions & 13 deletions requirements-dev.txt
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
2 changes: 1 addition & 1 deletion setup.cfg
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ zipsafe = False

python_requires = >3.8
install_requires =
griffe
griffe>=0.25
plum-dispatch
sphobjinv
tabulate
Expand Down

0 comments on commit 25bc5a2

Please sign in to comment.