search

MillionConcepts / lhorizon

lhorizon helps you find things in the Solar System.
BSD 3-Clause "New" or "Revised" License
5 stars 2 forks source link

Use sphinx to generate docs? #14

Closed malmans2 closed 3 years ago

malmans2 commented 3 years ago

If I'm understanding correctly, api.md is not automatically inferred from the actual code but was manually written. I think it would be more robust to only use docstrings in the code, this way the api in the documentation is always up to date. I suggest to look into sphinx, particularly the docstring extensions: google style, numpy style

https://github.com/openjournals/joss-reviews/issues/3495

m-stclair commented 3 years ago

api.md is generated using mkdocs -- i prefer markdown docstrings to google or numpy-style docstrings for this project. I am, however, regenerating it only manually -- do you think it would be preferable to add a CI hook to rebuild the docs?

malmans2 commented 3 years ago

do you think it would be preferable to add a CI hook to rebuild the docs?

Yes, I think that would be ideal. You could either add a github action that rebuilds the API and automatically submits a commit/PR, or you could add a test function that rebuilds the API and checks whether it is identical to the existing one. If not, pytest will report a failure and you'll know that you have to rebuild the API.

m-stclair commented 3 years ago

there's an apparent regression in pydoc-markdown preventing me from automating this, so I'm putting a pin in this for now. if the issue isn't resolved in a couple of weeks, I'll switch to some other documentation-generating system.

m-stclair commented 3 years ago

doc freshness test added: cf0c99b