avwx-rest / avwx-engine

Aviation Weather parsing engine. METAR & TAF
MIT License
90 stars 31 forks source link

PoC of using pdoc to generate API docs #56

Closed marchuffnagle closed 1 year ago

marchuffnagle commented 1 year ago

This draft PR adds support for generating docs using pdoc. It looked like one of the simpler options, less complex than something like sphinx.

I only focused on the main doc page, and the METAR page. The other links on the main page won't work yet.

I renamed some of the functions in metar.py to start with `__ so that they wouldn't show up in the generated documentation. (They aren't in the existing documentation, so I assumed you wanted them hidden.)

Like the previous draft PR, if this seems like something worth pursuing, I'm happy to finish up the PoC and issue a full PR with the updated docs.

You can preview the docs by running poetry run pdoc avwx, which will start up a doc server on http://localhost:8080

(I do actually have a project that I want to build on top of this library, but I got distracted 😄.)

devdupont commented 1 year ago

pdoc looks like it will do exactly what I want. I love that it uses the existing md in the docstrings too.

I want to push a quick data update build before merging this and playing with it. So far, the only weird thing I need to config is showing inherited class methods like Metar.parse since that is core to every report class.

I'll also dive deeper into the pods and Python docs on discoverability. Most of those metar.py functions don't get used outside of the file they are in, but some of them could still be useful. I should go back through and audit what should and should not be considered a public function. For example, most of the avwx.parsing.core functions are just meant to be used by avwx report parsers, but I've used some of them in outside projects because they were already implemented.

marchuffnagle commented 1 year ago

I poked around at this a bit more this evening, and updated some more docs.

pdoc's docs talk a bit about discoverability. The data/__init__.py file uses the __all__ approach.

Let me know if you'd like more help with these documentation updates, I'm happy to keep poking at it. Otherwise, I'm going to go start using the library. Thanks again for the work you've put into this.

devdupont commented 1 year ago

Thank you for your work starting the auto doc. I'll merge this in and keep playing with it. I'll finally get the documentation pipeline fixed too 😄

devdupont commented 1 year ago

Thanks for the help on this. If you email me, I'll send you some stickers :)