Ouranosinc / cookiecutter-pypackage

Cookiecutter template for a Python package.
BSD 3-Clause "New" or "Revised" License
6 stars 1 forks source link

Suggestions of improvements #37

Closed bzah closed 5 months ago

bzah commented 6 months ago

Description

This issue is meant to upstream the improvements suggested on xncml by @fmigneault comments in the PR https://github.com/xarray-contrib/xncml/pull/76

On CHANGELOG.rst/CHANGES.rst:

On CONTRIBUTING.rst

On Makefile

On pyproject.toml

On readme.rst

~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 commented 6 months ago

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

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.