Build API docs with sphinx-autoapi #1000
Conversation
Codecov Report
@@ Coverage Diff @@
## master #1000 +/- ##
==========================================
+ Coverage 89.49% 89.52% +0.02%
==========================================
Files 74 74
Lines 3932 3941 +9
Branches 343 343
==========================================
+ Hits 3519 3528 +9
Misses 322 322
Partials 91 91
Continue to review full report at Codecov.
|
|
Thanks a lot for this @jorgepiloto! Let me have a look locally |
|
Some warnings might be the following: In Then, they are added to the poliastro/src/poliastro/constants/general.py Lines 48 to 50 in d40700d I think this is causing the error, since they are not directly defined within the source code. The |
|
In the CI we have |
|
From official documentation:
|
|
I found a little hack. If the following line: is substituted by: from astropy.constants.iau2015 import M_earth as _M_earth, M_jup as _M_jupiter, M_sun as _M_sun
# Custom variable definition
M_earth = _M_earth
M_jupiter = _M_jupiter
M_sun = _M_sunAutoapi does not complain, since these vars have been defined in the module. |
|
Haha, interesting! Let's proceed like that for the moment so we don't get blocked. Please implement the hack leaving a comment, and if the docs look good we can merge.
|
|
Although the |
|
Beware of typos 😉 |
|
I showed this PR to @humitos who helped me a lot understand what was going on (thanks!). For the Options:
I think option (2) is the best, given that we already started the effort of using sphinx-apidoc. We can always resort to (3) if all else fails. Apart from that, I see that we're getting several warnings: |
|
I also noticed is possible to generate docstrings for constants by doing: UNITY = 1.00
""" Unitary constant """Might trigger the |
|
I was able locally to get ride of some warnings and end up having only those ones claiming for the addition of |
|
OMG: I solved it in an easy way! Let me rewrite git history and push changes 👍 |
|
Wohoo amazing! Looking forward to the finished version :) |
There was a problem hiding this comment.
The result is excellent! Lots of undocumented modules and packages appeared, we were forced to add docstrings to many of them (which is a good thing) and the organization is good. I think this is a great improvement over what we had before and you executed beautifully, so I am merging this. Thanks a lot @jorgepiloto!
Solves for #967 by making use of
sphinx-autoapifor building project's API documentation. Although very useful, some warnings were raise, which is treated as an error bytox -e docs. Some of this warnings are related with typos and therefore, easy to fix. However, others are related with imports and I am not sure whysphinx-autoapiis not able to properly parse those poliastro objects.I deleted the whole
docs/source/apidirectory since it only contained*.rstfiles with the minimum required layout for building pages documentation, that is the reason behind so many simplified lines of code. By defaultsphinx-autoapibuilds a temporary directory calledautoapiinsidedocs/sourceand generates all necessary*.rstfiles. After desired output files (*.html, *.tex, etc...) are built, theautoapifolder is deleted.