Skip to content

Rework docs to add new detailed example section #1141

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nathanjmcdougall merged 1 commit into from
Nov 12, 2025
Merged

Rework docs to add new detailed example section #1141

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 13 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Inspired by an [**R** package of the same name](https://usethis.r-lib.org/index.
- 📢 Fully declarative project configuration.
- ⚡ Get started on a new Python project or a new workflow in seconds.

## 🧭 Getting Started
## 🧭 Installation

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
version v0.6.8 (run `uv --version` to check, and `uv self update` to upgrade).
Expand Down Expand Up @@ -110,32 +110,14 @@ Additionally, the command line reference documentation can be viewed with `useth

## 💡 Example Usage

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

```console
$ uvx usethis init
✔ Writing 'pyproject.toml' and initializing project.
✔ Writing 'README.md'.
☐ Populate 'README.md' to help users understand the project.
✔ Adding recommended documentation tools.
☐ Run 'uv run mkdocs build' to build the documentation.
☐ Run 'uv run mkdocs serve' to serve the documentation locally.
✔ Adding recommended linters.
☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.
☐ Run 'uv run deptry src' to run deptry.
✔ Adding recommended formatters.
☐ Run 'uv run ruff format' to run the Ruff formatter.
☐ Run 'uv run pyproject-fmt pyproject.toml' to run pyproject-fmt.
✔ Adding recommended spellcheckers.
☐ Run 'uv run codespell' to run the Codespell spellchecker.
✔ Adding recommended test frameworks.
☐ Add test files to the '/tests' directory with the format 'test_*.py'.
☐ Add test functions with the format 'test_*()'.
☐ Run 'uv run pytest' to run the tests.
☐ Run 'uv run pytest --cov' to run your tests with Coverage.py.
```
To start a new project from scratch with a complete set of recommended tooling, simply run
the `uvx usethis init` command.

### Configuring individual tools

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

```console
$ uvx usethis tool ruff
Expand All @@ -147,7 +129,9 @@ $ uvx usethis tool ruff
☐ Run 'uv run ruff format' to run the Ruff formatter.
```

To use pytest, run:
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).

As another example, to use pytest, run:

```console
$ uvx usethis tool pytest
Expand All @@ -161,7 +145,7 @@ $ uvx usethis tool pytest
☐ Run 'uv run pytest' to run the tests.
```

To configure Bitbucket Pipelines, run:
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:

```console
$ uvx usethis ci bitbucket
Expand All @@ -173,6 +157,8 @@ $ uvx usethis ci bitbucket
☐ Run your pipeline via the Bitbucket website.
```

See the [CLI Reference](https://usethis.readthedocs.io/en/stable/cli/reference) for a full list of available commands.

## 📚 Similar Projects

Not sure if usethis is the exact fit for your project?
Expand Down
30 changes: 30 additions & 0 deletions docs/start/detailed-example.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# 💡 Detailed Example

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:

```console
$ uvx usethis tool ruff
✔ Adding dependency 'ruff' to the 'dev' group in 'pyproject.toml'.
✔ Adding Ruff config to 'pyproject.toml'.
✔ Selecting Ruff rules 'A', 'C4', 'E4', 'E7', 'E9', 'F', 'FLY', 'FURB', 'I', 'PLE', 'PLR', 'RUF', 'SIM'4, 'UP' in 'pyproject.toml'.
✔ Ignoring Ruff rules 'PLR2004', 'SIM108' in 'pyproject.toml'.
☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.
☐ Run 'uv run ruff format' to run the Ruff formatter.
```

Let's run through what each line of the output means:

1. `✔ Adding dependency 'ruff' to the 'dev' group in 'pyproject.toml'.`
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`).
2. `✔ Adding Ruff config to 'pyproject.toml'.`
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.
3. `✔ Selecting Ruff rules 'A', 'C4', 'E4', 'E7', 'E9', 'F', 'FLY', 'FURB', 'I', 'PLE', 'PLR', 'RUF', 'SIM', 'UP' in 'pyproject.toml'.`
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).
4. `✔ Ignoring Ruff rules 'PLR2004', 'SIM108' in 'pyproject.toml'.`
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.
5. `☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.`
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!
6. `☐ Run 'uv run ruff format' to run the Ruff formatter.`
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.

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.
38 changes: 12 additions & 26 deletions docs/example-usage.md → docs/start/example-usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,13 @@
# 💡 Example Usage

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

```console
$ uvx usethis init
✔ Writing 'pyproject.toml' and initializing project.
✔ Writing 'README.md'.
☐ Populate 'README.md' to help users understand the project.
✔ Adding recommended documentation tools.
☐ Run 'uv run mkdocs build' to build the documentation.
☐ Run 'uv run mkdocs serve' to serve the documentation locally.
✔ Adding recommended linters.
☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.
☐ Run 'uv run deptry src' to run deptry.
✔ Adding recommended formatters.
☐ Run 'uv run ruff format' to run the Ruff formatter.
☐ Run 'uv run pyproject-fmt pyproject.toml' to run pyproject-fmt.
✔ Adding recommended spellcheckers.
☐ Run 'uv run codespell' to run the Codespell spellchecker.
✔ Adding recommended test frameworks.
☐ Add test files to the '/tests' directory with the format 'test_*.py'.
☐ Add test functions with the format 'test_*()'.
☐ Run 'uv run pytest' to run the tests.
☐ Run 'uv run pytest --cov' to run your tests with Coverage.py.
```
To start a new project from scratch with a complete set of recommended tooling, simply run
the `uvx usethis init` command.

## Configuring individual tools

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

```console
$ uvx usethis tool ruff
Expand All @@ -37,7 +19,9 @@ $ uvx usethis tool ruff
☐ Run 'uv run ruff format' to run the Ruff formatter.
```

To use pytest, run:
For a detailed breakdown of what each line of the output means, [there is a detailed explanation available](start/detailed-example.md).

As another example, to use pytest, run:

```console
$ uvx usethis tool pytest
Expand All @@ -51,7 +35,7 @@ $ uvx usethis tool pytest
☐ Run 'uv run pytest' to run the tests.
```

To configure Bitbucket Pipelines, run:
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:

```console
$ uvx usethis ci bitbucket
Expand All @@ -62,3 +46,5 @@ $ uvx usethis ci bitbucket
✔ Adding 'Test on 3.14' to default pipeline in 'bitbucket-pipelines.yml'.
☐ Run your pipeline via the Bitbucket website.
```

See the [CLI Reference](cli/reference.md) for a full list of available commands.
2 changes: 1 addition & 1 deletion docs/getting-started.md → docs/start/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# 🧭 Getting Started
# 🧭 Installation

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
version v0.6.8 (run `uv --version` to check, and `uv self update` to upgrade).
Expand Down
6 changes: 4 additions & 2 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,10 @@ site_name: usethis

nav:
- Introduction: index.md
- Getting Started: getting-started.md
- Example Usage: example-usage.md
- Getting Started:
- Installation: start/installation.md
- Example Usage: start/example-usage.md
- Detailed Example: start/detailed-example.md
- CLI Reference:
- Overview: cli/overview.md
- Reference: cli/reference.md
Expand Down
25 changes: 22 additions & 3 deletions tests/docs/test_readme.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import difflib
from pathlib import Path


Expand All @@ -11,7 +12,7 @@ def test_assemble_readme_from_docs(usethis_dev_dir: Path):
usethis_dev_dir / "docs" / "index.md", skip_lines=2, demote_headers=False
)
)
parts.append(_get_doc_file(usethis_dev_dir / "docs" / "getting-started.md"))
parts.append(_get_doc_file(usethis_dev_dir / "docs" / "start" / "installation.md"))
cli_overview_content = _get_doc_file(
usethis_dev_dir / "docs" / "cli" / "overview.md",
).replace( # README uses absolute links, docs use relative links
Expand All @@ -20,7 +21,17 @@ def test_assemble_readme_from_docs(usethis_dev_dir: Path):
)

parts.append(cli_overview_content)
parts.append(_get_doc_file(usethis_dev_dir / "docs" / "example-usage.md"))
parts.append(
_get_doc_file(usethis_dev_dir / "docs" / "start" / "example-usage.md")
.replace( # README uses absolute links, docs use relative links
"](start/detailed-example.md)",
"](https://usethis.readthedocs.io/en/stable/start/detailed-example)",
)
.replace(
"](cli/reference.md)",
"](https://usethis.readthedocs.io/en/stable/cli/reference)",
)
)
parts.append(_get_doc_file(usethis_dev_dir / "docs" / "similar-projects.md"))

content = (
Expand All @@ -29,7 +40,15 @@ def test_assemble_readme_from_docs(usethis_dev_dir: Path):
.replace("> [!TIP]\n> ", "")
)
for part in parts:
assert part in content
assert part in content, "\n".join(
difflib.unified_diff(
part.splitlines(),
content.splitlines(),
fromfile="docs",
tofile="README.md",
lineterm="",
)
)


def _get_doc_file(
Expand Down
42 changes: 0 additions & 42 deletions tests/usethis/_ui/interface/test_init.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,48 +60,6 @@ def test_pre_commit_included(self, tmp_path: Path):
"codespell",
]

def test_readme_example(self, tmp_path: Path):
"""This example is used the README.md file.

Note carefully! If this test is updated, the README.md file must be
updated too.
"""
# Act
runner = CliRunner()
with change_cwd(tmp_path):
result = runner.invoke_safe(app, ["init"])

# Assert
assert result.exit_code == 0, result.output
assert (
result.output
# ###################################
# See docstring!
# ###################################
== """\
✔ Writing 'pyproject.toml' and initializing project.
✔ Writing 'README.md'.
☐ Populate 'README.md' to help users understand the project.
✔ Setting the development status to '1 - Planning'.
✔ Adding recommended documentation tools.
☐ Run 'uv run mkdocs build' to build the documentation.
☐ Run 'uv run mkdocs serve' to serve the documentation locally.
✔ Adding recommended linters.
☐ Run 'uv run deptry src' to run deptry.
☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.
✔ Adding recommended formatters.
☐ Run 'uv run ruff format' to run the Ruff formatter.
☐ Run 'uv run pyproject-fmt pyproject.toml' to run pyproject-fmt.
✔ Adding recommended spellcheckers.
☐ Run 'uv run codespell' to run the Codespell spellchecker.
✔ Adding recommended test frameworks.
☐ Add test files to the '/tests' directory with the format 'test_*.py'.
☐ Add test functions with the format 'test_*()'.
☐ Run 'uv run pytest' to run the tests.
☐ Run 'uv run pytest --cov' to run your tests with Coverage.py.
"""
)

def test_specify_path(self, tmp_path: Path):
# Act
runner = CliRunner()
Expand Down