Select a toolkit for auto-generating Python documentation

[hancush]

Background

Documentation is really important, but it can be hard to prioritize, especially if we don't have earmarked budget. One friction we can reduce is producing documentation and code from the same source. There are several toolkits that will produce nice documentation from docstrings, etc. Let's look into those and adopt one.

Proposal

I'd like to produce a tight comparison of a few documentation-from-code frameworks and spike 1, perhaps 2, on a module of python-legistar-scraper.

This looks like a great starting point: https://medium.com/@peterkong/comparison-of-python-documentation-generators-660203ca3804

Deliverables

This R&D effort will produce:

• Documentation for at least one python-legistar-scraper module built from the framework of our choice.
• A recommendation of adoption for the framework we like best.

Timeline

I expect this to take no more than two R&D days.

[hancush]

I tried pdoc and autodoc/Sphinx. Though it takes a bit more configuration, the latter is the clear winner for configuration. More tk.

[hancush]

Still working past this issue: https://stackoverflow.com/questions/67485175/docstrings-are-not-included-in-read-the-docs-sphinx-build

[hancush]

Silly me, the solution is to install the package you're documenting, duh.

[hancush]

Working docs build here: https://github.com/datamade/census_area/pull/14

Read The Docs is pretty cool and, like Netlify, will auto build your docs for you, so that's what I did. https://docs.readthedocs.io/en/stable/

[hancush]

Include guidance on when to do this.