Closed marchuffnagle closed 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.
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.
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 😄
Thanks for the help on this. If you email me, I'll send you some stickers :)
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 😄.)