v4 Reference API using autoapi #2395
Draft
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Member
erikvansebille
left a comment
erikvansebille
left a comment
There was a problem hiding this comment.
I agree that the alphabetic order of items in the API list now feels a bit haphazard, so not ideal.
Comment on lines
+128
to
+137
| # [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", | ||
| # ] |
Member
There was a problem hiding this comment.
Can this be removed completely?
Contributor
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 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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?