Flesh out contributing docs to include pre-commit, style, build info, more

[mfisher87]

What elements are needed or out of date in CONTRIBUTING.md? For example, we should probably document:

• Usage of pre-commit, i.e. pre-commit install to enable it to run automatically; pre-commit run -a to run manually
• That we use "Google-style" docstrings (and link to Napoleon docs or other tools to help us author them correctly)
• How to work on docs locally, i.e. scripts/docs-live.sh and scripts/build-docs.sh. Video tutorial: https://www.youtube.com/watch?v=mNjlMZ4F3So
• Limitations of our mkdocs setup (e.g. when using scripts/docs-live.sh, it won't autoreload when you change a docstring in the code. Hot reloader only watches the docs themselves for changes)

[Sherwin-14]

@mfisher87 Is this relevant? Do you have any specific opinions about this?

[mfisher87]

Yes, I think most of this is still relevant. I think this can all go in the contributing index doc? Not sure; I don't want that doc to get too big again, so open to suggestions :) Updated the original post! Let me know if there are still unanswered questions!

[Sherwin-14]

I think we should include this in contributing index doc since the topics discussed here would be in contributor interest :)

[Sherwin-14]

Hey should we assign an entirely different section addressing these points? I wonder which is the section where all of these fit together

[mfisher87]

Do you mean a section within the contributing index doc? We could update the "format and lint" section to use pre-commit instead of Make.

Perhaps for the docs stuff, we add a subsection "... to contribute to docs"?

Perhaps for conda v poetry, we could add a section for "development environment management". Where do we tell contributors how to use poetry to install a development environment? I don't know how personally (and I think we should switch away from poetry ;) ). I don't know that we actually document that currently, so I think we might need new content.

[Sherwin-14]

Yeah I mean sections under contributing index doc. I agree with all the suggestions and maybe we can put the poetry issue on hold for now and once things are sorted then we can add the add it later.

[mfisher87]

I think that sounds like a great path forward, thank you @Sherwin-14 :) Would you like to be assigned to this issue?

[Sherwin-14]

Yes I would be glad :)