Build documentation

[kallewesterling]

No description provided.

[mialondon]

Can you explain what seaborn is when it's mentioned in the Notebook? (Apologies if you have and I missed it)

[kallewesterling]

The notebooks are not the documentation that I'm describing in this issue, but it's a good comment. I will add something about what seaborn is in future versions of the notebooks.

[griff-rees]

Suggestions, with ease of github hosting in mind:

quartodoc

• Very new (alpha level python module)
• Built on quarto, which supports rendering in R, julia, javascript (via observable) and jupyter
• Works for github hosting
• Exports to pdf and epub etc.

mkdocs

• Stable
• Works with github hosting
• Harder to feature languages other than python
• A lot of plug-ins needed to render analysis results

sphinx

• Original python packaging project
• Some extensions for other languages, but probably not as flexible as quarto
• Recently supports github hosting required).

[kallewesterling]

I'd definitely go with mkdocs or sphinx in this case.. I like mkdocs because of the easier-to-edit, but sphinx has some really nice autodoc features that I've used for Defoe, and we could apply here as well, perhaps?

[mialondon]

Noting that the overhead required for someone to update documentation after the project has finished might also be a consideration... e.g. how many dependencies do they need to install and manage before they can change some text?

Also noting that 'documentation' can be ambiguous - I'm guessing this is for generating docs from inline comments rather than managing ReadMes and other text?

[kallewesterling]

@griff-rees just an FYI in relation to @mialondon's comment here -- we had a conversation about documentation this morning, where we concluded that there may be many layers to documentation, where some might need to go into a README.md in the "frontmatter" of the repository, and some can be linked out to an API ref doc (which can be generated, say, using autodoc in Sphinx or so).

[kallewesterling]

how many dependencies do they need to install and manage before they can change some text?

Also in response to this, Sphinx (and the RST format) is industry standard for contributors in open-source coding these days, I think, so anyone who'd want to contribute to the package would be able to do so fairly easily. We would also set up Poetry (on the dev side) to include Sphinx, of course, so it'd be managed by the package manager there.