stravalib icon indicating copy to clipboard operation
stravalib copied to clipboard

DOC: update / fix docstrings throughout to be numpy style

Open lwasser opened this issue 2 years ago • 2 comments

Currently there are a few issues thorughout our API related to documentation.

  • [ ] Docs have a mixture of numpy style and rst style . We should move to numpy style to facilitate consistent documentation
  • [x] Pydantic makes autodoc a bit more complex. however we can easily using autodoc-pydantic extension to create cleaner documented objects that use / inherit from pydantic objects.
  • [x] move to pydata sphinx theme to fix the autodoc toctree issues.

I am going to work on this in pieces - starting first with simply cleaning up the docs and fixing docstrings that don't render.

Then in a second push we can begin to document each module a bit more carefully adding examples where needed.

Files to fix

  • [x] client.py
  • [ ] model.py

lwasser avatar Jan 29 '23 16:01 lwasser

@jsamoocha i do want to be careful with this as you're adding commits. this is why i thought it might be nice to merge that current PR #324 and then i can add on top of it a few cleanup docs focused pr's! this will take a bit of the onus off of you to cleanup docstrings but you can review my pr's and suggest changes as needed. i think examples will be really helpful to add and we can do it in pieces :) .

lwasser avatar Jan 29 '23 16:01 lwasser

i also want to move us to pydata sphinx theme

essentially using furo i'm running into TOC issues where each object that is documented is listed in the left side bar. this is a default for furo. But i think moving to pydata we can customize. i'll wait to do this once we merge the pydantic branch.

Screen Shot 2023-02-03 at 8 21 24 PM

lwasser avatar Feb 04 '23 03:02 lwasser