Automatically generate a documentation

[cnstt]

Maybe that could be a good thing, to generate a documentation automatically. What do you think about this? Maybe some kind of basic sphinx documentation? Because I plan to do a documentation for my plugin, but thought maybe as I'm working on it I may also contribute to a more general approach for the cookiecutter template...

[tlambert03]

We used to have this, but recently removed it: https://github.com/napari/cookiecutter-napari-plugin/pull/115

It was removed because of high maintenance burden and low reward. It's rather hard to keep that sort of thing up to date in a cookiecutter template (as sphinx or mkdocs updates over time), and it's pretty trivial to just run sphinx-quickstart or mkdocs new to get the most up-to-date recommendations from the corresponding docs provider

[tlambert03]

https://github.com/napari/cookiecutter-napari-plugin#create-your-documentation

[cnstt]

Okay I see, I just saw a github action exists to simplify the maintenance burden, would this be better to implement in cookiecutter? https://github.com/marketplace/actions/sphinx-docs-to-github-pages Combined to dependabot https://github.com/napari/cookiecutter-napari-plugin/issues/120 the github action would update itself automatically ;)

[tlambert03]

that action appears to publish docs to the gh-pages branch in a given repo. which wouldn't help here?

Just to clarify, are you discussing making it so that "ready to go documentation" is part of the plugin after you create it? or are you talking about docs for napari-cookie-cutter itself?

[cnstt]

Just to clarify, are you discussing making it so that "ready to go documentation" is part of the plugin after you create it? or are you talking about docs for napari-cookie-cutter itself?

I'm meaning ready to go documentation for the plugin after you create it

[tlambert03]

yeah, the maintenance burden I'm referring to is that if we a "prebaked" docs folder in this template (i.e. if we run sphinx-quickstart once here for people). then those files that were autogenerated by sphinx will, themselves, go out of date eventually. And we would essentially have to redo that process (or somehow automate it) periodically to keep it up to date. The github action you're pointing to would simply build already complete documentation into an html site and upload it to your repo (which isn't what we want here... we don't want to actually create a gh-pages branch here in this repo).

I know it's tempting to make these cookiecutters do "all the things" one could ever want out of a repo :) but in this case, given the complexities of actually doing documentation well, I think both we (the maintainers) and the end-users are better off going directly to the source here (i.e. go to sphinx or mkdocs or jupyter-book and follow their up-to-date tutorials).