diff --git a/README.md b/README.md index ea1a3acd..cbd64a06 100644 --- a/README.md +++ b/README.md @@ -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). @@ -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 @@ -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 @@ -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 @@ -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? diff --git a/docs/start/detailed-example.md b/docs/start/detailed-example.md new file mode 100644 index 00000000..290364b7 --- /dev/null +++ b/docs/start/detailed-example.md @@ -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. diff --git a/docs/example-usage.md b/docs/start/example-usage.md similarity index 55% rename from docs/example-usage.md rename to docs/start/example-usage.md index cef09588..c239e3d1 100644 --- a/docs/example-usage.md +++ b/docs/start/example-usage.md @@ -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 @@ -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 @@ -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 @@ -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. diff --git a/docs/getting-started.md b/docs/start/installation.md similarity index 96% rename from docs/getting-started.md rename to docs/start/installation.md index 6dc5ef18..0b74db2a 100644 --- a/docs/getting-started.md +++ b/docs/start/installation.md @@ -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). diff --git a/mkdocs.yml b/mkdocs.yml index c4f69c6b..0f9bb8cf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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 diff --git a/tests/docs/test_readme.py b/tests/docs/test_readme.py index 587f0de7..6648d02a 100644 --- a/tests/docs/test_readme.py +++ b/tests/docs/test_readme.py @@ -1,3 +1,4 @@ +import difflib from pathlib import Path @@ -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 @@ -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 = ( @@ -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( diff --git a/tests/usethis/_ui/interface/test_init.py b/tests/usethis/_ui/interface/test_init.py index 8b1cbd0c..c18a3261 100644 --- a/tests/usethis/_ui/interface/test_init.py +++ b/tests/usethis/_ui/interface/test_init.py @@ -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()