feat: add implementation pages in the guidebook to support peer review

[lwasser]

In our slack, @coatless made some great suggestions as our current Editor in Chief regarding gaps in our guidebook related to our peer review process and how things could be more seamless as we work through peer review.

These guides are conceptually strong; but, leave some of the implementation examples MIA:
https://www.pyopensci.org/python-package-guide/documentation/index.html
https://www.pyopensci.org/python-package-guide/tests/index.html

I think that it would be better for the EiC to have more concrete examples in the guide so we can link to the guide (and we can also link out from the guide if there are better things to just point to in some cases).

But in the spirit of "one way to do things" having working examples (that are in our copier template) would be invaluable.

@coatless are examples of how to setup docs and how to setup tests the place where we should start? this would also be documentation for our copier template

or do you have anything to add / did I miss things that you think are missing here?

********* 2026 update ******
Let's try to update a single page with copier template examples for running tests and see how that goes

---

Maybe at the top of each page, we then create a breakout - if you use our copier template, you can build the docs using

hatch run: docs:run etc. So this is a sprintable thing that someone could tackle, starting with adding / cross-linking to how to run tests.

for the tests page here:
https://www.pyopensci.org/python-package-guide/tests/index.html

it might look like a breakout at the top of that page that says -

Our packaging template using pytest as the test tool and hatch environments that are configured to run tests across multiple python versions.
If you use our packaging copier template to create your package, an initial test suite is set up and can be run using Hatch environments with the following command:

hatch run test:run

Maybe we can add a config example in the breakout on how to adjust Python versions in the pyproject.toml file.

Let's test this out if someone wants to sprint on it during a sprint in 2026!! I'll add it to our help, wanted board.

[pllim]

FWIW

• OpenAstronomy has packaging guide that uses cookiecutter at https://github.com/OpenAstronomy/packaging-guide
• Scientific Python has some guides here as well: https://learn.scientific-python.org/development/guides/packaging-simple/

[lwasser]

thank you for this @pllim !! I haven't looked closely at the openAstronomy template yet! The feedback we keep getting is that people want one way to do things. So while the scientific python's template and guide is great - people don't want all of the tabs and options.

So that is what our guide tries to do along with explaining things for users who are not packaging experts.

One middle ground is we create examples from our template BUT then cross link to Scientific Python's guide for multi tool options.

I did talk to Henry a bit about cross linking at pycon us! thoughts?

[pllim]

I seldom have to create a package from scratch but for the 1-2 times I had to do it, cookiecutter was nice. It had prompts and then give you a somewhat functional skeleton. Still have to go in and clean things up but better than writing up everything from scratch. Perhaps @Cadair could comment more on the OpenAstronomy one. 🙏 Hope this helps!

[Cadair]

The goal of the OpenAstronomy template is to provide exactly 0 options, and for you to end up with a package which looks like astropy/sunpy when you are done. I appreciate that's not the most modern way of doing things any more but that's the goal.

[lwasser]

Cool - thank you all!! I love the work that has been done on openAstronomy!!
We also have a copier template now. And our tutorials teach someone how to create a package. I think the issue here might be to cross-reference and provide examples of say how to build and serve run docs locally using Hatch, based on our template.

Maybe at the top of each page, we then create a breakout - if you use our copier template, you can build the docs using

hatch run: docs:run etc. So this is a sprintable thing that someone could tackle, starting with adding / cross-linking to how to run tests.

for the tests page here:
https://www.pyopensci.org/python-package-guide/tests/index.html

it might look like a breakout at the top of that page that says -

Our packaging template using pytest as the test tool and hatch environments that are configured to run tests across multiple python versions.
If you use our packaging copier template to create your package, an initial test suite is set up and can be run using Hatch environments with the following command:

hatch run test:run

Maybe we can add a config example in the breakout on how to adjust Python versions in the pyproject.toml file.

Let's test this out if someone wants to sprint on it during a sprint in 2026!! I'll add it to our help, wanted board.