Rework README and move dev instructions to contributing#481
Rework README and move dev instructions to contributing#481samcunliffe merged 12 commits intomainfrom
Conversation
Move all developer instructions out from README and rework/update the instructions. Disable markdownlint rule MD033 globally.
samcunliffe
added
documentation
samcunliffe
added
the
needs-2-reviewers
paddyroddy
left a comment
paddyroddy
left a comment
There was a problem hiding this comment.
I like the idea but see my concerns on DRYness
dstansby
left a comment
dstansby
left a comment
There was a problem hiding this comment.
Looking good 👍 - I've left some nitpicks that you can take or leave
| ``` | ||
|
|
||
| You can also [install cookiecutter]. | ||
| Do this if you don't use [uv], or if you're likely to want to use cookiecutter again. |
There was a problem hiding this comment.
This says "you can do this if you don't use uv", but then the command below uses uv. Perhaps just link to https://cookiecutter.readthedocs.io/en/stable/README.html#installation instead of offering extra commands?
There was a problem hiding this comment.
I do link to there. Line above ☝️
And I thought "Here's the way we install it" indicated that there are other ways.
There was a problem hiding this comment.
Maybe we could change
[install cookiecutter]
to
[install cookiecutter] with pipx or pip
to make it clearer that this is distinct from the uv installation instructions and maybe also change
Here's the way we install it:
to
To install cookiecutter using uv run
There was a problem hiding this comment.
How about just removing the whole thing and directing the user to install cookiecutter following cookiecutter's instructions?
Then it becomes a bit simpler.
Co-authored-by: David Stansby <dstansby@gmail.com>
|
pre-commit.ci autofix |
for more information, see https://pre-commit.ci
matt-graham
left a comment
matt-graham
left a comment
There was a problem hiding this comment.
Looks much clearer to me overall, thanks @samcunliffe! I agree with @paddyroddy's suggestions to remove example run through of cookiecutter and resulting project directory tree as seem like these will just be a pain to keep up to date without adding much value for users. Have also added some suggested changes around @dstansby's comments on installing cookiecutter.
| ``` | ||
|
|
||
| You can also [install cookiecutter]. | ||
| Do this if you don't use [uv], or if you're likely to want to use cookiecutter again. |
There was a problem hiding this comment.
Maybe we could change
[install cookiecutter]
to
[install cookiecutter] with pipx or pip
to make it clearer that this is distinct from the uv installation instructions and maybe also change
Here's the way we install it:
to
To install cookiecutter using uv run
Co-authored-by: David Stansby <dstansby@gmail.com>
Direct to cookiecutter's instructions.
| @@ -1,2 +1,4 @@ | |||
| --- | |||
| MD013: false | |||
| # Markdown linting rules to ignore. | |||
There was a problem hiding this comment.
Feels like you've done this to trigger me...
Given that you can do other things besides ignoring in this file. I think we should remove this comment.
| # Markdown linting rules to ignore. |
There was a problem hiding this comment.
But everything in here is a rule to ignore.
you can do other things
We're not doing other things.
There was a problem hiding this comment.
Then we would add another comment above the block of other things?
samcunliffe
deleted the
sc/rework-readme-and-move-dev-instructions-to-contributing
branch
4 participants
I've attempted to simplify the user-facing quick-start instructions. Not a huge fan of enumerated instructions and the optional (but cool) one-liner it doesn't really fit in 1. 2. 3....
Also it's a bit overkill to have a venv/conda environment just for cookiecutter itself. The cookiecutter docs recommend
pipx install. I claim that we want to encourageuvxbecause it's fast and cool 😎 .I've spent a bit of effort trying to be clear but comments on clarity etc are very welcome.
I also moved and merged the dev instructions into CONTRIBUTING so README is just user-facing. And CONTRIBUTING is just dev.
This addresses
And two comments
uvandpixi. #464 (comment)uvand add it to the website. #419 (comment)