-
Notifications
You must be signed in to change notification settings - Fork 168
v4 Reference API using autoapi #2395
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
erikvansebille
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree that the alphabetic order of items in the API list now feels a bit haphazard, so not ideal.
pyproject.toml
Outdated
| # [tool.ruff.lint.per-file-ignores] | ||
| # # Ignore docstring rules everywhere except for the stable files (particleset.py, interpolators.py). | ||
| # "!src/parcels/{_core/particleset,interpolators}.py" = [ | ||
| # # Missing docstring in public class | ||
| # "D101", | ||
| # # Missing docstring in public method | ||
| # "D102", | ||
| # # Missing docstring in public function | ||
| # "D103", | ||
| # ] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can this be removed completely?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I have edited and activated this, and it now checks for all the files with public classes that docstrings are present, which I think is a minimal requirement. It does mean that the list of files is hardcoded, which means that new files may not be tracked. This ruff.lint can be easily extended to include rules as we update the docstrings (e.g. checking returns :https://docs.astral.sh/ruff/rules/docstring-missing-returns/#docstring-missing-returns-doc201)
Aha! Just found out isort can be turned off for a file (docs) -
+# isort: skip_file
from importlib.metadata import version as _version
try:
__version__ = _version("parcels")
except Exception:
# Local copy or not installed with setuptools.
__version__ = "unknown"
from parcels._core.basegrid import BaseGrid
from parcels._core.converters import (
Geographic,
GeographicPolar,
GeographicPolarSquare,
GeographicSquare,
Unity,
)I think with being able to manually sort this via re-ordering the import blocks, using autoapi becomes much more attractive |
for more information, see https://pre-commit.ci
for more information, see https://pre-commit.ci
|
I have now edited the autoapi configuration so that it is automatically generated from the imported classes and functions defined in A minor issue I encountered is that Parcels/src/parcels/_core/particle.py Line 195 in ea9517a
@VeckoTheGecko, do you think we should make |
I don't think it makes sense to make Is the main concern here that there isn't a docstring for the attribute? If so - unfortunately Python doesn't natively support attribute docstrings (PEP224), but there might be support from Sphinx that allows this (comment about Sphinx's Other than that, I don't think its really necessary for |
To clarify, I guess my concerns were twofold:
|
I think that just goes back to there being limited customisation that we can do with Note that |
|
Sounds good! |
erikvansebille
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good! Just a few comments below
| Community <community/index> | ||
| Development <development/index> | ||
| API reference <reference> | ||
| API reference <reference/parcels/index> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.



Fixes #2269
I have implemented sphinx-autoapi to generate the reference API based on the names made public by
__all__in init.py. This means that curating which classes and methods are included happens fully in this list, and no custom list is necessary (as was necessary in reference.rst, see #2269).This also means however, that we have less control over the order and presentation done by
autoapi. The classes, exceptions, and attributes are all documented on one page now, and their order is determined by the order in which they are imported, which is fixed by alphabetically byisort. It is also not possible to control the order of the autosummary at the top of the page, which is sorted by group. From what I can see, autoapi is still quite a small project, and most other projects haveautodocstyle API references like we had before.I think these complications are challenging enough to suggest returning to our manually curated API by reverting #2270 . @VeckoTheGecko, and @erikvansebille , would you take a look at the docs build and tell me what you think?