Content on "How to create a Python package"
Opened this issue · 6 comments
Migrating an interesting discussion over from ProjectPythia/projectpythia.github.io#43.
I think that the Foundations book could have an entirely new top-level section (after Core Scientific Packages) devoted to best practices for developing Python packages.
Tentatively, the chapter could be entitled "Building Python Packages", and have sections like:
- tutorial on tests and testing
- Good package structure (i.e., the structure of the files and folders in the repository)
- Building documentation
- CI services like GitHub Action (for testing, linting, etc.) and ReadTheDocs (for building and hosting documentation)
- Using pre-commit hooks and other enforcing tools (including various pre-commit checks like black/prettier, flake8, isort, talisman, etc.)
I'm not 100% sure if this is in-scope for the Foundations book, but it could be really useful to have self-contained tutorials on all this material cross-referenced with our tutorials on conda, git, GitHub pull requests, etc.
It bears repeating here, @jbusecke has already done much of this work over at https://github.com/jbusecke/cookiecutter-science-project
and we could easily adapt many of the instructions from his README.
Is there already a skeleton for this kind of documentation? I was just wondering if I should add more info to my readme (which should really be a full docs page at this point) or already move over to a more general space.
Is there already a skeleton for this kind of documentation? I was just wondering if I should add more info to my readme (which should really be a full docs page at this point) or already move over to a more general space.
We now have a template notebook for new contributions to the Pythia Foundations book: https://foundations.projectpythia.org/preamble/template.html
What I proposed above was to add an entirely new top-level section to the book, with individual sections delivering content in line with our template. I could quickly rough this out in a PR with some tentative section headings if that will help get things rolling.
I think this material is really valuable, but I think calling it "Foundations" is a stretch.
I think this material is really valuable, but I think calling it "Foundations" is a stretch.
True enough... this material could exist in a separate repo and be hosted as a separate piece of content on the main Pythia portal.
At the EWG meeting today (9/30/2021) we batted around the idea of getting started with a separate gallery or "cookbook" section of the Pythia Portal that could house material that doesn't belong in Foundations for whatever reason. That could be the right place for this content.