Skip to content

Commit 196ade5

Browse files
nathanjmcdougallnathanjmcdougall
authored
Rework docs to add new detailed example section (#1141)
Also rename the getting started section of the readme to Installation, and make the usage examples more friendly.
1 parent 36a0629 commit 196ade5

7 files changed

Lines changed: 82 additions & 101 deletions

File tree

‎README.md‎

Lines changed: 13 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Inspired by an [**R** package of the same name](https://usethis.r-lib.org/index.
3131
- 📢 Fully declarative project configuration.
3232
- ⚡ Get started on a new Python project or a new workflow in seconds.
3333

34-
## 🧭 Getting Started
34+
## 🧭 Installation
3535

3636
First, it is strongly recommended you [install the uv package manager](https://docs.astral.sh/uv/getting-started/installation/): this is a simple, documented process. If you're already using uv, make sure you're using at least
3737
version v0.6.8 (run `uv --version` to check, and `uv self update` to upgrade).
@@ -110,32 +110,14 @@ Additionally, the command line reference documentation can be viewed with `useth
110110

111111
## 💡 Example Usage
112112

113-
To start a new project from scratch with a complete set of recommended tooling, run:
113+
### Starting a new project
114114

115-
```console
116-
$ uvx usethis init
117-
✔ Writing 'pyproject.toml' and initializing project.
118-
✔ Writing 'README.md'.
119-
☐ Populate 'README.md' to help users understand the project.
120-
✔ Adding recommended documentation tools.
121-
☐ Run 'uv run mkdocs build' to build the documentation.
122-
☐ Run 'uv run mkdocs serve' to serve the documentation locally.
123-
✔ Adding recommended linters.
124-
☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.
125-
☐ Run 'uv run deptry src' to run deptry.
126-
✔ Adding recommended formatters.
127-
☐ Run 'uv run ruff format' to run the Ruff formatter.
128-
☐ Run 'uv run pyproject-fmt pyproject.toml' to run pyproject-fmt.
129-
✔ Adding recommended spellcheckers.
130-
☐ Run 'uv run codespell' to run the Codespell spellchecker.
131-
✔ Adding recommended test frameworks.
132-
☐ Add test files to the '/tests' directory with the format 'test_*.py'.
133-
☐ Add test functions with the format 'test_*()'.
134-
☐ Run 'uv run pytest' to run the tests.
135-
☐ Run 'uv run pytest --cov' to run your tests with Coverage.py.
136-
```
115+
To start a new project from scratch with a complete set of recommended tooling, simply run
116+
the `uvx usethis init` command.
117+
118+
### Configuring individual tools
137119

138-
To use Ruff on an existing project, run:
120+
You can also configure individual tools one-by-one. For example, to add Ruff on an existing project, run:
139121

140122
```console
141123
$ uvx usethis tool ruff
@@ -147,7 +129,9 @@ $ uvx usethis tool ruff
147129
☐ Run 'uv run ruff format' to run the Ruff formatter.
148130
```
149131

150-
To use pytest, run:
132+
For a detailed breakdown of what each line of the output means, [there is a detailed explanation available](https://usethis.readthedocs.io/en/stable/start/detailed-example).
133+
134+
As another example, to use pytest, run:
151135

152136
```console
153137
$ uvx usethis tool pytest
@@ -161,7 +145,7 @@ $ uvx usethis tool pytest
161145
☐ Run 'uv run pytest' to run the tests.
162146
```
163147

164-
To configure Bitbucket Pipelines, run:
148+
There are also commands to configure aspects other than tools. For example, to configure [Bitbucket Pipelines](https://www.atlassian.com/software/bitbucket/features/pipelines), run:
165149

166150
```console
167151
$ uvx usethis ci bitbucket
@@ -173,6 +157,8 @@ $ uvx usethis ci bitbucket
173157
☐ Run your pipeline via the Bitbucket website.
174158
```
175159

160+
See the [CLI Reference](https://usethis.readthedocs.io/en/stable/cli/reference) for a full list of available commands.
161+
176162
## 📚 Similar Projects
177163

178164
Not sure if usethis is the exact fit for your project?

‎docs/start/detailed-example.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# 💡 Detailed Example
2+
3+
The output from usethis is chatty. If you know what you're doing, you can suppress it with the `--quiet` option, but usually it's worth paying close attention. For example, when adding the Ruff linting and formatting tool with the command `usethis tool ruff`, this is the output:
4+
5+
```console
6+
$ uvx usethis tool ruff
7+
✔ Adding dependency 'ruff' to the 'dev' group in 'pyproject.toml'.
8+
✔ Adding Ruff config to 'pyproject.toml'.
9+
✔ Selecting Ruff rules 'A', 'C4', 'E4', 'E7', 'E9', 'F', 'FLY', 'FURB', 'I', 'PLE', 'PLR', 'RUF', 'SIM'4, 'UP' in 'pyproject.toml'.
10+
✔ Ignoring Ruff rules 'PLR2004', 'SIM108' in 'pyproject.toml'.
11+
☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.
12+
☐ Run 'uv run ruff format' to run the Ruff formatter.
13+
```
14+
15+
Let's run through what each line of the output means:
16+
17+
1. `✔ Adding dependency 'ruff' to the 'dev' group in 'pyproject.toml'.`
18+
This line indicates that the `ruff` package has been added as a development dependency in the `pyproject.toml` file. This means that `ruff` has been installed automatically via `uv`, but also that it is recorded in the project's dependency list for others when they start working on the project (e.g. with `uv sync`).
19+
2. `✔ Adding Ruff config to 'pyproject.toml'.`
20+
This line indicates that a configuration section for Ruff has been added to the `pyproject.toml` file. This section contains settings that control how Ruff behaves when it is run. The settings adopted by usethis are "context aware" - based on the structure of your project, other tools you are using, etc., and so they are more likely to be appropriate for your project than the default settings.
21+
3. `✔ Selecting Ruff rules 'A', 'C4', 'E4', 'E7', 'E9', 'F', 'FLY', 'FURB', 'I', 'PLE', 'PLR', 'RUF', 'SIM', 'UP' in 'pyproject.toml'.`
22+
This line indicates that a set of recommended Ruff rule sets has been selected and added to the `pyproject.toml` configuration. These rules determine what kinds of issues Ruff will check for in your code. The selected rules are based on best practices and are intended to help you maintain high code quality. Most of them have auto-fixes available. You can learn more about the specific rules in the [Ruff documentation](https://docs.astral.sh/ruff/rules).
23+
4. `✔ Ignoring Ruff rules 'PLR2004', 'SIM108' in 'pyproject.toml'.`
24+
This line indicates that certain Ruff rules have been explicitly ignored in the configuration. These rules were deemed less useful or potentially problematic for most projects, so usethis has chosen to disable them by default. You can always modify this list later if you find that you want to enable or disable additional rules.
25+
5. `☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.`
26+
This line is an instruction for you to run the Ruff linter on your codebase. It helps teach you how to use the tool which has just been installed and configured. You're ready to go and explore!
27+
6. `☐ Run 'uv run ruff format' to run the Ruff formatter.`
28+
Ruff is also a code formatter. Similar to the previous line, this is an instruction for you to run the Ruff formatter on your codebase. This will help ensure that your code adheres to consistent formatting standards.
29+
30+
The key idea is that lines beginning with a check mark (✔) indicate actions that have been successfully completed by usethis, while lines beginning with an empty box (☐) are instructions for you to follow up on.

docs/example-usage.md renamed to docs/start/example-usage.md

Lines changed: 12 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,13 @@
11
# 💡 Example Usage
22

3-
To start a new project from scratch with a complete set of recommended tooling, run:
3+
## Starting a new project
44

5-
```console
6-
$ uvx usethis init
7-
✔ Writing 'pyproject.toml' and initializing project.
8-
✔ Writing 'README.md'.
9-
☐ Populate 'README.md' to help users understand the project.
10-
✔ Adding recommended documentation tools.
11-
☐ Run 'uv run mkdocs build' to build the documentation.
12-
☐ Run 'uv run mkdocs serve' to serve the documentation locally.
13-
✔ Adding recommended linters.
14-
☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.
15-
☐ Run 'uv run deptry src' to run deptry.
16-
✔ Adding recommended formatters.
17-
☐ Run 'uv run ruff format' to run the Ruff formatter.
18-
☐ Run 'uv run pyproject-fmt pyproject.toml' to run pyproject-fmt.
19-
✔ Adding recommended spellcheckers.
20-
☐ Run 'uv run codespell' to run the Codespell spellchecker.
21-
✔ Adding recommended test frameworks.
22-
☐ Add test files to the '/tests' directory with the format 'test_*.py'.
23-
☐ Add test functions with the format 'test_*()'.
24-
☐ Run 'uv run pytest' to run the tests.
25-
☐ Run 'uv run pytest --cov' to run your tests with Coverage.py.
26-
```
5+
To start a new project from scratch with a complete set of recommended tooling, simply run
6+
the `uvx usethis init` command.
7+
8+
## Configuring individual tools
279

28-
To use Ruff on an existing project, run:
10+
You can also configure individual tools one-by-one. For example, to add Ruff on an existing project, run:
2911

3012
```console
3113
$ uvx usethis tool ruff
@@ -37,7 +19,9 @@ $ uvx usethis tool ruff
3719
☐ Run 'uv run ruff format' to run the Ruff formatter.
3820
```
3921

40-
To use pytest, run:
22+
For a detailed breakdown of what each line of the output means, [there is a detailed explanation available](start/detailed-example.md).
23+
24+
As another example, to use pytest, run:
4125

4226
```console
4327
$ uvx usethis tool pytest
@@ -51,7 +35,7 @@ $ uvx usethis tool pytest
5135
☐ Run 'uv run pytest' to run the tests.
5236
```
5337

54-
To configure Bitbucket Pipelines, run:
38+
There are also commands to configure aspects other than tools. For example, to configure [Bitbucket Pipelines](https://www.atlassian.com/software/bitbucket/features/pipelines), run:
5539

5640
```console
5741
$ uvx usethis ci bitbucket
@@ -62,3 +46,5 @@ $ uvx usethis ci bitbucket
6246
✔ Adding 'Test on 3.14' to default pipeline in 'bitbucket-pipelines.yml'.
6347
☐ Run your pipeline via the Bitbucket website.
6448
```
49+
50+
See the [CLI Reference](cli/reference.md) for a full list of available commands.

docs/getting-started.md renamed to docs/start/installation.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# 🧭 Getting Started
1+
# 🧭 Installation
22

33
First, it is strongly recommended you [install the uv package manager](https://docs.astral.sh/uv/getting-started/installation/): this is a simple, documented process. If you're already using uv, make sure you're using at least
44
version v0.6.8 (run `uv --version` to check, and `uv self update` to upgrade).

‎mkdocs.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,10 @@ site_name: usethis
22

33
nav:
44
- Introduction: index.md
5-
- Getting Started: getting-started.md
6-
- Example Usage: example-usage.md
5+
- Getting Started:
6+
- Installation: start/installation.md
7+
- Example Usage: start/example-usage.md
8+
- Detailed Example: start/detailed-example.md
79
- CLI Reference:
810
- Overview: cli/overview.md
911
- Reference: cli/reference.md

‎tests/docs/test_readme.py‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import difflib
12
from pathlib import Path
23

34

@@ -11,7 +12,7 @@ def test_assemble_readme_from_docs(usethis_dev_dir: Path):
1112
usethis_dev_dir / "docs" / "index.md", skip_lines=2, demote_headers=False
1213
)
1314
)
14-
parts.append(_get_doc_file(usethis_dev_dir / "docs" / "getting-started.md"))
15+
parts.append(_get_doc_file(usethis_dev_dir / "docs" / "start" / "installation.md"))
1516
cli_overview_content = _get_doc_file(
1617
usethis_dev_dir / "docs" / "cli" / "overview.md",
1718
).replace( # README uses absolute links, docs use relative links
@@ -20,7 +21,17 @@ def test_assemble_readme_from_docs(usethis_dev_dir: Path):
2021
)
2122

2223
parts.append(cli_overview_content)
23-
parts.append(_get_doc_file(usethis_dev_dir / "docs" / "example-usage.md"))
24+
parts.append(
25+
_get_doc_file(usethis_dev_dir / "docs" / "start" / "example-usage.md")
26+
.replace( # README uses absolute links, docs use relative links
27+
"](start/detailed-example.md)",
28+
"](https://usethis.readthedocs.io/en/stable/start/detailed-example)",
29+
)
30+
.replace(
31+
"](cli/reference.md)",
32+
"](https://usethis.readthedocs.io/en/stable/cli/reference)",
33+
)
34+
)
2435
parts.append(_get_doc_file(usethis_dev_dir / "docs" / "similar-projects.md"))
2536

2637
content = (
@@ -29,7 +40,15 @@ def test_assemble_readme_from_docs(usethis_dev_dir: Path):
2940
.replace("> [!TIP]\n> ", "")
3041
)
3142
for part in parts:
32-
assert part in content
43+
assert part in content, "\n".join(
44+
difflib.unified_diff(
45+
part.splitlines(),
46+
content.splitlines(),
47+
fromfile="docs",
48+
tofile="README.md",
49+
lineterm="",
50+
)
51+
)
3352

3453

3554
def _get_doc_file(

‎tests/usethis/_ui/interface/test_init.py‎

Lines changed: 0 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -60,48 +60,6 @@ def test_pre_commit_included(self, tmp_path: Path):
6060
"codespell",
6161
]
6262

63-
def test_readme_example(self, tmp_path: Path):
64-
"""This example is used the README.md file.
65-
66-
Note carefully! If this test is updated, the README.md file must be
67-
updated too.
68-
"""
69-
# Act
70-
runner = CliRunner()
71-
with change_cwd(tmp_path):
72-
result = runner.invoke_safe(app, ["init"])
73-
74-
# Assert
75-
assert result.exit_code == 0, result.output
76-
assert (
77-
result.output
78-
# ###################################
79-
# See docstring!
80-
# ###################################
81-
== """\
82-
✔ Writing 'pyproject.toml' and initializing project.
83-
✔ Writing 'README.md'.
84-
☐ Populate 'README.md' to help users understand the project.
85-
✔ Setting the development status to '1 - Planning'.
86-
✔ Adding recommended documentation tools.
87-
☐ Run 'uv run mkdocs build' to build the documentation.
88-
☐ Run 'uv run mkdocs serve' to serve the documentation locally.
89-
✔ Adding recommended linters.
90-
☐ Run 'uv run deptry src' to run deptry.
91-
☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.
92-
✔ Adding recommended formatters.
93-
☐ Run 'uv run ruff format' to run the Ruff formatter.
94-
☐ Run 'uv run pyproject-fmt pyproject.toml' to run pyproject-fmt.
95-
✔ Adding recommended spellcheckers.
96-
☐ Run 'uv run codespell' to run the Codespell spellchecker.
97-
✔ Adding recommended test frameworks.
98-
☐ Add test files to the '/tests' directory with the format 'test_*.py'.
99-
☐ Add test functions with the format 'test_*()'.
100-
☐ Run 'uv run pytest' to run the tests.
101-
☐ Run 'uv run pytest --cov' to run your tests with Coverage.py.
102-
"""
103-
)
104-
10563
def test_specify_path(self, tmp_path: Path):
10664
# Act
10765
runner = CliRunner()

0 commit comments

Comments
 (0)