Skip to content

Commit 7425f84

Browse files
reint-fischerreint-fischer
authored
Merge pull request #2395 from Parcels-code/reference-api-v4
v4 Reference API using autoapi
2 parents b6eecd3 + 070fb66 commit 7425f84

12 files changed

Lines changed: 312 additions & 36 deletions

File tree

‎docs/_autoapi_templates/python/class.rst‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
{# Adapted from sphinx-autoapi https://github.com/readthedocs/sphinx-autoapi #}
2+
{% if obj.display %}
3+
{% if is_own_page %}
4+
{{ obj.id }}
5+
{{ "=" * obj.id | length }}
6+
{% endif %}
7+
{% set visible_children = obj.children|selectattr("display")|list %}
8+
{% set own_page_children = visible_children|selectattr("type", "in", own_page_types)|list %}
9+
{% if is_own_page and own_page_children %}
10+
.. toctree::
11+
:hidden:
12+
{% for child in own_page_children %}
13+
{{ child.include_path }}
14+
{% endfor %}
15+
{% endif %}
16+
.. py:{{ obj.type }}:: {% if is_own_page %}{{ obj.id }}{% else %}{{ obj.short_name }}{% endif %}{% if obj.args %}({{ obj.args }}){% endif %}
17+
18+
{% for (args, return_annotation) in obj.overloads %}
19+
{{ " " * (obj.type | length) }} {{ obj.short_name }}{% if args %}({{ args }}){% endif %}
20+
21+
{% endfor %}
22+
{% if obj.bases %}
23+
{% if "show-inheritance" in autoapi_options %}
24+
25+
Bases: {% for base in obj.bases %}{{ base|link_objs }}{% if not loop.last %}, {% endif %}{% endfor %}
26+
{% endif %}
27+
{% if "show-inheritance-diagram" in autoapi_options and obj.bases != ["object"] %}
28+
.. autoapi-inheritance-diagram:: {{ obj.obj["full_name"] }}
29+
:parts: 1
30+
{% if "private-members" in autoapi_options %}
31+
:private-bases:
32+
{% endif %}
33+
34+
{% endif %}
35+
{% endif %}
36+
{% if obj.docstring %}
37+
{{ obj.docstring|indent(3) }}
38+
{% endif %}
39+
{% for obj_item in visible_children %}
40+
{% if obj_item.type not in own_page_types %}
41+
{{ obj_item.render()|indent(3) }}
42+
{% endif %}
43+
{% endfor %}
44+
{% if is_own_page and own_page_children %}
45+
{% set visible_methods = visible_children|selectattr("type", "equalto", "method")|list %}
46+
{% if visible_methods %}
47+
Methods
48+
-------
49+
50+
.. autoapisummary::
51+
52+
{% for method in visible_methods %}
53+
{{ method.id }}
54+
{% endfor %}
55+
56+
57+
{% endif %}
58+
{% set visible_attributes = visible_children|selectattr("type", "equalto", "attribute")|list %}
59+
{% if visible_attributes %}
60+
Attributes
61+
----------
62+
63+
.. autoapisummary::
64+
65+
{% for attribute in visible_attributes %}
66+
{{ attribute.id }}
67+
{% endfor %}
68+
69+
70+
{% endif %}
71+
{% set visible_exceptions = own_page_children|selectattr("type", "equalto", "exception")|list %}
72+
{% if visible_exceptions %}
73+
Exceptions
74+
----------
75+
76+
.. autoapisummary::
77+
78+
{% for exception in visible_exceptions %}
79+
{{ exception.id }}
80+
{% endfor %}
81+
82+
83+
{% endif %}
84+
{% set visible_classes = own_page_children|selectattr("type", "equalto", "class")|list %}
85+
{% if visible_classes %}
86+
Classes
87+
-------
88+
89+
.. autoapisummary::
90+
91+
{% for klass in visible_classes %}
92+
{{ klass.id }}
93+
{% endfor %}
94+
{% endif %}
95+
{% endif %}
96+
{% endif %}

‎docs/_autoapi_templates/python/module.rst‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
{# Adapted from sphinx-autoapi https://github.com/readthedocs/sphinx-autoapi #}
2+
{% if obj.display %}
3+
{% if is_own_page %}
4+
{{ obj.id }}
5+
{{ "=" * obj.id|length }}
6+
7+
.. py:module:: {{ obj.name }}
8+
9+
{% if obj.docstring %}
10+
.. autoapi-nested-parse::
11+
12+
{{ obj.docstring|indent(3) }}
13+
14+
{% endif %}
15+
16+
{% block content %}
17+
{% set visible_children = obj.children|selectattr("display")|list %}
18+
{% if visible_children %}
19+
{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %}
20+
{% if visible_classes %}
21+
{% if "class" in own_page_types or "show-module-summary" in autoapi_options %}
22+
Classes
23+
-------
24+
25+
{% if "class" in own_page_types %}
26+
.. toctree::
27+
:hidden:
28+
:caption: Classes
29+
30+
{% for klass in visible_classes %}
31+
{{ klass.include_path }}
32+
{% endfor %}
33+
34+
{% endif %}
35+
.. autoapisummary::
36+
37+
{% for klass in visible_classes %}
38+
{{ klass.id }}
39+
{% endfor %}
40+
{% endif %}
41+
42+
43+
{% endif %}
44+
{% set visible_exceptions = visible_children|selectattr("type", "equalto", "exception")|list %}
45+
{% if visible_exceptions %}
46+
{% if "exception" in own_page_types or "show-module-summary" in autoapi_options %}
47+
Exceptions
48+
----------
49+
50+
{% if "exception" in own_page_types %}
51+
.. toctree::
52+
:hidden:
53+
54+
{% for exception in visible_exceptions %}
55+
{{ exception.include_path }}
56+
{% endfor %}
57+
58+
{% endif %}
59+
.. autoapisummary::
60+
61+
{% for exception in visible_exceptions %}
62+
{{ exception.id }}
63+
{% endfor %}
64+
{% endif %}
65+
66+
67+
{% endif %}
68+
{% set visible_attributes = visible_children|selectattr("type", "equalto", "data")|list %}
69+
{% if visible_attributes %}
70+
{% if "attribute" in own_page_types or "show-module-summary" in autoapi_options %}
71+
Attributes
72+
----------
73+
74+
{% if "attribute" in own_page_types %}
75+
.. toctree::
76+
:hidden:
77+
78+
{% for attribute in visible_attributes %}
79+
{{ attribute.include_path }}
80+
{% endfor %}
81+
82+
{% endif %}
83+
.. autoapisummary::
84+
85+
{% for attribute in visible_attributes %}
86+
{{ attribute.id }}
87+
{% endfor %}
88+
{% endif %}
89+
90+
91+
{% endif %}
92+
{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %}
93+
{% if visible_functions %}
94+
{% if "function" in own_page_types or "show-module-summary" in autoapi_options %}
95+
Functions
96+
---------
97+
98+
{% if "function" in own_page_types %}
99+
.. toctree::
100+
:hidden:
101+
102+
{% for function in visible_functions %}
103+
{{ function.include_path }}
104+
{% endfor %}
105+
106+
{% endif %}
107+
.. autoapisummary::
108+
109+
{% for function in visible_functions %}
110+
{{ function.id }}
111+
{% endfor %}
112+
{% endif %}
113+
114+
115+
{% endif %}
116+
{% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
117+
{% set visible_submodules = obj.submodules|selectattr("display")|list %}
118+
{% set visible_submodules = (visible_subpackages + visible_submodules)|sort %}
119+
{% if visible_submodules %}
120+
.. toctree::
121+
:caption: Submodules
122+
:maxdepth: 1
123+
124+
{% for submodule in visible_submodules %}
125+
{{ submodule.include_path }}
126+
{% endfor %}
127+
{% endif %}
128+
{% set this_page_children = visible_children|rejectattr("type", "in", own_page_types)|list %}
129+
{% if this_page_children %}
130+
{{ obj.type|title }} Contents
131+
{{ "-" * obj.type|length }}---------
132+
133+
{% for obj_item in this_page_children %}
134+
{{ obj_item.render()|indent(0) }}
135+
{% endfor %}
136+
{% endif %}
137+
{% endif %}
138+
{% endblock %}
139+
{% else %}
140+
.. py:module:: {{ obj.name }}
141+
142+
{% if obj.docstring %}
143+
.. autoapi-nested-parse::
144+
145+
{{ obj.docstring|indent(6) }}
146+
147+
{% endif %}
148+
{% for obj_item in visible_children %}
149+
{{ obj_item.render()|indent(3) }}
150+
{% endfor %}
151+
{% endif %}
152+
{% endif %}

‎docs/conf.py‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
"""Sphinx configuration file for Parcels documentation."""
1+
"""autoSphinx configuration file for Parcels documentation."""
22
# parcels documentation build configuration file, created by
33
# sphinx-quickstart on Tue Oct 20 09:58:20 2015.
44
#
@@ -40,6 +40,7 @@
4040
"numpydoc",
4141
"sphinxcontrib.mermaid",
4242
"sphinx_design",
43+
"autoapi.extension",
4344
]
4445

4546
# Add any paths that contain templates here, relative to this directory.
@@ -115,6 +116,7 @@
115116
# directories to ignore when looking for source files.
116117
exclude_patterns = [
117118
"_build",
119+
"_autoapi_templates",
118120
"jupyter_execute",
119121
"**.ipynb_checkpoints",
120122
"user_guide/examples_v3",
@@ -528,3 +530,19 @@ def linkcode_resolve(domain, info):
528530
nb_execution_excludepatterns = ["jupyter_execute", ".jupyter_cache"]
529531
nb_execution_raise_on_error = True
530532
nb_execution_timeout = 75
533+
534+
# -- Options for autoapi --------------------------------------------------
535+
autoapi_dirs = ["../src/parcels"]
536+
# autoapi_add_toctree_entry = False
537+
autoapi_root = "reference"
538+
autoapi_options = [
539+
"members",
540+
# "show-inheritance",
541+
"undoc-members",
542+
"show-module-summary",
543+
"imported-members",
544+
]
545+
autoapi_member_order = "bysource"
546+
autodoc_typehints = "none"
547+
autoapi_template_dir = "_autoapi_templates"
548+
autoapi_own_page_level = "class"

‎docs/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ _Animation of virtual particles carried by ocean surface flow in the global ocea
1212
You can browse the documentation for older versions by using the version switcher in the bottom right.
1313
```
1414

15-
**Useful links**: [Installation instructions](getting_started/installation.md) | [Discussions on GitHub](https://github.com/Parcels-code/parcels/discussions) | [Issue on GitHub](https://github.com/Parcels-code/parcels/issues) | [Parcels website](https://parcels-code.org/) | [CLAM community website](https://clam-community.github.io/) | [API reference](reference.md)
15+
**Useful links**: [Installation instructions](getting_started/installation.md) | [Discussions on GitHub](https://github.com/Parcels-code/parcels/discussions) | [Issue on GitHub](https://github.com/Parcels-code/parcels/issues) | [Parcels website](https://parcels-code.org/) | [CLAM community website](https://clam-community.github.io/) | [API reference](reference/parcels/index)
1616

1717
`````{grid} 1 2 2 2
1818
:gutter: 4
@@ -94,7 +94,7 @@ Getting started <getting_started/index>
9494
User guide <user_guide/index>
9595
Community <community/index>
9696
Development <development/index>
97-
API reference <reference>
97+
API reference <reference/parcels/index>
9898
v4 <v4/index>
9999
Parcels website <https://parcels-code.org/>
100100
```

‎docs/reference.md‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎pixi.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ matplotlib-base = ">=2.0.2"
7373
gsw = "*"
7474

7575
[feature.docs.dependencies]
76+
parcels = { path = "." }
7677
numpydoc = "!=1.9.0"
7778
myst-nb = "*"
7879
ipython = "*"
@@ -82,6 +83,7 @@ pydata-sphinx-theme = "*"
8283
sphinx-autobuild = "*"
8384
sphinxcontrib-mermaid = "*"
8485
sphinx-design = "*"
86+
sphinx-autoapi = "*"
8587

8688
[feature.docs.tasks]
8789
docs = "sphinx-build docs docs/_build"

‎pyproject.toml‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -110,12 +110,6 @@ ignore = [
110110
# TODO: ignore for now (requires more work). Remove ignore once fixed
111111
# Missing docstring in public module
112112
"D100",
113-
# Missing docstring in public class
114-
"D101",
115-
# Missing docstring in public method
116-
"D102",
117-
# Missing docstring in public function
118-
"D103",
119113
# Missing docstring in public package
120114
"D104",
121115
# Missing docstring in magic method
@@ -131,6 +125,17 @@ ignore = [
131125
"F811",
132126
]
133127

128+
[tool.ruff.lint.per-file-ignores]
129+
# Ignore docstring rules everywhere except for the stable files (particleset.py, interpolators.py).
130+
"!src/parcels/{_core/basegrid,_core/field,_core/fieldset,_core/kernel,_core/particle,_core/particlefile,_core/particleset,_core/uxgrid,_core/xgrid,kernels/advection,kernels/advectiondiffusion,interpolators}.py" = [
131+
# Missing docstring in public class
132+
"D101",
133+
# Missing docstring in public method
134+
"D102",
135+
# Missing docstring in public function
136+
"D103",
137+
]
138+
134139
[tool.ruff.lint.pydocstyle]
135140
convention = "numpy"
136141

0 commit comments

Comments
 (0)