Rework API docs #1476
Rework API docs #1476
Conversation
Obfuscates the code generation, and only introduces minor changes.
Everything stays the same.
Only the year of creation is necessary, see https://stackoverflow.com/q/2390230/554319.
Our configuration file should not replace the Sphinx documentation.
astrojuanlu
force-pushed
the
fix-api-docs
branch
from
69342b8
to
364536b
Compare
|
Rendered version: https://poliastro--1476.org.readthedocs.build/en/1476/api.html |
Codecov Report
@@ Coverage Diff @@
## main #1476 +/- ##
=======================================
Coverage 91.83% 91.83%
=======================================
Files 97 97
Lines 4459 4459
Branches 426 426
=======================================
Hits 4095 4095
Misses 274 274
Partials 90 90 Continue to review full report at Codecov.
|
| maxdepth: 1 | ||
| glob: | ||
| --- | ||
| /autoapi/poliastro/[!c_]*/index |
There was a problem hiding this comment.
Sadly, it looks like this is the best approach to exclude the core at this moment. Let us keep an eye on the Sphinx issue you linked.
There was a problem hiding this comment.
Yep 😢 no way around that for now unfortunately
There was a problem hiding this comment.
Very clean work, @astrojuanlu! Having the Orbit, Maneuver and Ephem objects in the main API section is so nice. Approving this 👍🏽
|
Thanks a lot @jorgepiloto ! Merging 🚀 |
Fixes #1183. I used some Sphinx and sphinx-autoapi hackery to make the API index more useful, by hopefully addressing the most common use cases and making the toctrees more shallow. I think this strikes a good balance between manually written docs and automatically generated ones.
This made me think about what should we consider public API though. We have plenty of high level modules and probably we should communicate to users which ones they should use and which ones they can ignore. However, making submodules private would be a breaking change, and since I plan to backport this pull request to 0.16.1, I will deal with that separately.
I also used this opportunity to trim most of the cruft from
conf.py. Modern versions ofsphinx-quickstartdon't include so much stuff, but this wasn't the case 8 years ago 🙃 Folks willing to change our docs config should read the documentation.Requesting a review from @jorgepiloto, who did the original work here.