Suggestions of improvements

[bzah]

• Date you used Cookiecutter PyPackage: March 2024
• Cookiecutter version used, if any: f391bbd (Feb 28, 2024)

Description

This issue is meant to upstream the improvements suggested on xncml by @fmigneault comments in the PR xarray-contrib/xncml#76

On CHANGELOG.rst/CHANGES.rst:

• Add .. _changes_x.y.z: as section titles and add the bummyversion config to manage these automatically (example of config here).

On CONTRIBUTING.rst

• Remove the leading $ when suggestion commands, it makes it harder to copy-paste commands.
• Remove .. highlight:: shell at the top and use explicit .. code-block:: shell when needed.
• Use the make commands (in particual make dev and make release), instead of rewriting their content through individual commands.

On Makefile

• use python -m pip install no need to show flit here.
• For the local installation do python -m pip install --editable .[all] (see pyproject.toml below for the [all] part).
• Add a make release-conda do wrap the conda release process described in CONTRIBUTING.rst (edit: not necessary as the initial release is done only once and subsequent release are managed automatically on the feedstock).
• add pre-commit install step to make dev.

On pyproject.toml

• add a all = ["{{project_name}}[dev]", "{{project_name}}[docs]"] to easily install all dependency for when stting up a local dev environment.
• Add the bumpmyversion template update for CHANGES.rst

On readme.rst

• Use .. code-block:: python instead of ```python
• Remove leading $ for shell commands

At last, an architectural suggestion: we could also change the overall layout to follow a src layout instead of a flat layout, but this may have a higher migration cost than the other changes suggested above. (separate issue #39)

note: I will be opening a PR shortly with these changes (apart from the architectural change).

[Zeitsperre]

Thanks so much for upstreaming your changes! I've been meaning to perform an update of the existing projects versioned here, so it'll be great to have your improvements as well!

• Remove the leading $ when suggestion commands, it makes it harder to copy-paste commands.

I think I added this specifically so that:

1. It's clear to users that these are terminal commands
2. It's a tiny bit harder to just copy and paste

If you think it's unnecessary, I'll go with your suggestion.

• use python -m pip install no need to show flit here.

Good call. I think I was reading some older documentation for flit when I wrote that. This will make our (development) lives much less complicated.

we could also change the overall layout to follow a src layout instead of a flat layout, but this may have a higher migration cost than the other changes suggested above.

That's a major change, but I would be willing to discuss it at the very least. This would affect several projects, but if the gains are worthwhile, I don't see an issue with migrating the template over. Perhaps we can start an issue about that specifically?

[bzah]

Remove the leading $ when suggestion commands, it makes it harder to copy-paste commands.

It's clear to users that these are terminal commands

I think it's the role of the renderer to make it clear it's a command and both sphinx for readthedoc or github are doing it well IMO. It's only when reading the raw rst file that it can be confusing right ?

I agree for the src layout, I will create a dedicated issue.