Content on "How to create a Python package"

[brian-rose]

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.

[brian-rose]

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.

[jbusecke]

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.

[brian-rose]

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.

[dopplershift]

I think this material is really valuable, but I think calling it "Foundations" is a stretch.

[brian-rose]

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.

[brian-rose]

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.