I have used Python Sphinx (https://www.sphinx-doc.org/en/master/) for a work project a couple of years ago. It has the ability to "autodoc" your python code if you follow their commenting template for each function and class. The tool was simple to setup and I had a build process that simply created the html files and pushed them to our docs webserver location each time we did a release.
Looking back, I would have used mkdocs as markdown is more accepted as a documenting language than RST (ReStructuredText). One benefit of using mkdocs that should be considered is that we can have the documentation in multiple languages. Since the Seasons skin was internationalized and we have about the same amount of weather stations inside the US as well as outside the US, having a platform like this allows for the documentation to be translated and easily accessible. Given the large changes to install and manage WeeWX in v5, it begs us to consider a new documentation platform as refactoring all that html code with the changes will take as much time as migrating the raw text to markdown. I also to hate to say this, but this could spillover for a large website update for WeeWX in general as the documentation and the station registry is about 90% of the website today. All of this will take a lot of time. Maybe we should run a poll with the existing users to see what they want to see in the documentation and website before looking at moving tools and such. DDJ On Sat, Dec 31, 2022 at 1:35 AM Vince Skahan <[email protected]> wrote: > Thanks Doug. It turns out I used mkdocs at my last $job for our local > docs but those brain cells apparently retired with me it seems 18 months > ago. Thanks for refreshing my memory. > > I also asked on reddit and got pointed to https://github.com/pi-hole/docs > which has the howto for how they build those docs. If I get a chance I'll > try to run the weewx docs through and see what they look like with that > styling. > > And github actions is a great idea for automating ! > > On Friday, December 30, 2022 at 9:53:01 PM UTC-8 [email protected] > wrote: > >> pi-hole uses mkdocs, which is a website generator that translates >> markdown to a nice website solution. it is simple to setup. >> >> pi-hole/docs: The official Pi-hole documentation (github.com) >> <https://github.com/pi-hole/docs> >> >> deployment can be done with github actions where you approve a pull >> request to main, GitHub can run the builder and send the html to a target >> directory. >> >> now writing the documentation, well that is a different story. >> >> DDJ >> > -- > You received this message because you are subscribed to the Google Groups > "weewx-development" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To view this discussion on the web visit > https://groups.google.com/d/msgid/weewx-development/caa275f3-898f-4555-a7c3-391b2846b320n%40googlegroups.com > <https://groups.google.com/d/msgid/weewx-development/caa275f3-898f-4555-a7c3-391b2846b320n%40googlegroups.com?utm_medium=email&utm_source=footer> > . > -- You received this message because you are subscribed to the Google Groups "weewx-development" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/weewx-development/CACC0i0ysPOwuAzOCg8_nuwugG6mFb2ZhPmMaOMaROj%2B_-mE-_Q%40mail.gmail.com.
