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

nsidc / earthaccess

Python Library for NASA Earthdata APIs

https://earthaccess.readthedocs.io/

MIT License

417 stars 84 forks source link

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

Open mfisher87 opened 9 months ago

mfisher87 commented 9 months ago

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 commented 4 months ago

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

mfisher87 commented 4 months ago

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 commented 4 months ago

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

Sherwin-14 commented 4 months ago

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

mfisher87 commented 4 months ago

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 commented 4 months ago

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 commented 4 months ago

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

Sherwin-14 commented 4 months ago

Yes I would be glad :)