Skip to content
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

Converted docstrings from reST to Google style #951

Merged
merged 3 commits into from
Mar 27, 2024

Conversation

forman
Copy link
Member

@forman forman commented Mar 27, 2024

  • Converted docstrings from reST to Google style
  • Changed devguide accordingly using docconvert
  • Adjusted Sphinx configuration, which is now using sphinx.ext.napoleon for API doc generation

Checklist:

  • Add unit tests and/or doctests in docstrings
  • Add docstrings and API docs for any new/modified user-facing classes and functions
  • New/modified features documented in docs/source/*
  • Changes documented in CHANGES.md
  • GitHub CI passes
  • AppVeyor CI passes
  • Test coverage remains or increases (target 100%)

@forman forman marked this pull request as ready for review March 27, 2024 11:38
@forman forman self-assigned this Mar 27, 2024
Copy link
Contributor

@thomasstorm thomasstorm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tiny suggestion, otherwise looking fine!

CHANGES.md Outdated Show resolved Hide resolved
Copy link
Member

@pont-us pont-us left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved, but note that docconvert has missed many functions (at least 41 by my count) -- list of files with remaining rST docstrings appended below.

However, I don't see this as a barrier to merging. There's no quick workaround to convert the remaining rST string (at least, I couldn't persuade docconvert to do anything with them), and converting them all by hand would be very time-consuming. So I think we should merge this PR now and fix the remaining strings as and when we come across them during other work. Sphinx + napoleon handles mixtures of both docstring styles, so the rendered documentation is fine in any case.

xcube/core/compute.py
xcube/core/level.py
xcube/core/_tile2.py
xcube/core/subsampling.py
xcube/core/resampling/spatial.py
xcube/core/reproject.py
xcube/core/gen2/generator.py
xcube/core/zarrstore/generic.py
xcube/core/update.py
xcube/core/gridmapping/base.py
xcube/core/timeslice.py
xcube/core/store/fs/accessor.py
xcube/core/store/fs/store.py
xcube/core/store/datatype.py
xcube/core/store/store.py
xcube/core/geom.py
xcube/webapi/compute/context.py
xcube/webapi/ows/wmts/controllers.py
xcube/util/expression.py
xcube/util/dask.py
xcube/util/cache.py
xcube/util/temp.py
xcube/util/extend.py
xcube/util/jsonschema.py
xcube/util/jsonencoder.py
xcube/server/asyncexec.py
xcube/server/webservers/tornado.py

Co-authored-by: Thomas Storm <thomas.storm@brockmann-consult.de>
@pont-us pont-us merged commit d3f9f62 into main Mar 27, 2024
1 check passed
@pont-us pont-us deleted the forman-docstrings_from_rest_to_google branch April 4, 2024 09:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants