search

Garden-AI / garden

https://garden-ai.readthedocs.io
MIT License
21 stars 4 forks source link

docs revamp #528

Closed OwenPriceSkelly closed 2 months ago

OwenPriceSkelly commented 3 months ago

closes #512

Overview

This PR cleans up our docs in a few places, with the major new addition being a (hopefully) helpful API reference for the main user-facing classes in the SDK (Client, Gardens, Entrypoints, *Metadata objects, plus decorators and helpers).

The "automatic" documentation also required some painstaking updates to the docstrings for the classes I wanted to document, so the diff isn't entirely limited to the docs/ directory (no functional changes though). This also involved prefixing some methods with underscores so they didn't get pulled into the generated docs.

I also changed the decorator name from garden_entrypoint to entrypoint, but I kept garden_entrypoint around as an alias for backwards-compatibility

Discussion

I still have some lingering gripes with the docs, but I don't want to spend more much more time on the docs right now until we have the users to read them. But I think this reaches the short term goal of "a hypothetical user could work out how to link their paper or dataset metadata to their entrypoints entirely from the docs" which I'm happy with.

If we don't think that goal is met yet I'm happy to revisit, but I think other docs gripes can wait / fall under their own PR

Testing

with mkdocs serve and my own two eyes 👀

Documentation

All docs!

📚 Documentation preview 📚: https://garden-ai--528.org.readthedocs.build/en/528/

codecov[bot] commented 3 months ago

Codecov Report

Attention: Patch coverage is 94.11765% with 2 lines in your changes missing coverage. Please review.

Project coverage is 83.74%. Comparing base (138d9ff) to head (ad79336). Report is 1 commits behind head on main.

Files Patch % Lines
garden_ai/entrypoints.py 75.00% 1 Missing :warning:
garden_ai/scripts/save_session_and_metadata.py 0.00% 1 Missing :warning:
Additional details and impacted files ```diff @@ Coverage Diff @@ ## main #528 +/- ## ========================================== + Coverage 83.70% 83.74% +0.03% ========================================== Files 53 53 Lines 3806 3814 +8 ========================================== + Hits 3186 3194 +8 Misses 620 620 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.