Skip to content

Commit daf96cb

Browse files
nathanjmcdougallnathanjmcdougall
authored
Implement usethis doc and usethis init --doc (#854)
* Implement `usethis doc` and `usethis init --doc` * Fix typo in docstring for `doc` interface function
1 parent 4731365 commit daf96cb

10 files changed

Lines changed: 108 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ $ pipx run usethis tool ruff
7373

7474
### Manage Tooling
7575

76+
- [`usethis doc`](#usethis-doc) — Add/Configure recommended documentation tools (namely, [MkDocs](https://www.mkdocs.org/)).
7677
- [`usethis format`](#usethis-format) — Add/Configure recommended formatters (namely, [Ruff](https://docs.astral.sh/ruff/formatter/) and [pyproject-fmt](https://pyproject-fmt.readthedocs.io/en/latest/)).
7778
- [`usethis lint`](#usethis-lint) — Add/Configure recommended linters (namely, [Ruff](https://docs.astral.sh/ruff/linter) and [deptry](https://github.com/fpgmaas/deptry)).
7879
- [`usethis spellcheck`](#usethis-spellcheck) — Add/Configure recommended spellcheckers (namely, [codespell](https://github.com/codespell-project/codespell)).
@@ -108,6 +109,9 @@ $ uvx usethis init
108109
✔ Writing 'pyproject.toml' and initializing project.
109110
✔ Writing 'README.md'.
110111
☐ Populate 'README.md' to help users understand the project.
112+
✔ Adding recommended documentation tools.
113+
☐ Run 'uv run mkdocs build' to build the documentation.
114+
☐ Run 'uv run mkdocs serve' to serve the documentation locally.
111115
✔ Adding recommended linters.
112116
☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.
113117
☐ Run 'uv run deptry src' to run deptry.
@@ -177,6 +181,7 @@ Initialize a new Python project with recommended defaults, including:
177181

178182
Supported options:
179183

184+
- `--doc` to add recommended documentation tools (default; or `--no-doc` to opt-out)
180185
- `--format` to add recommended formatters (default; or `--no-format` to opt-out)
181186
- `--lint` to add recommended linters (default; or `--no-lint` to opt-out)
182187
- `--spellcheck` to add a recommended spellchecker (default; or `--no-spellcheck` to opt-out)
@@ -203,6 +208,26 @@ Supported options:
203208
- `--quiet` to suppress output
204209
- `--frozen` to leave the virtual environment and lockfile unchanged (i.e. do not install dependencies, nor update lockfiles)
205210

211+
### `usethis doc`
212+
213+
Add recommended documentation tools to the project (namely, [MkDocs](https://www.mkdocs.org/)), including:
214+
215+
- declared & installed dependencies via `uv add`,
216+
- relevant `pyproject.toml` configuration, and
217+
- any other relevant directories or tool-bespoke configuration files.
218+
219+
Note if `pyproject.toml` is not present, it will be created, since this is required for declaring dependencies via `uv add`.
220+
221+
Supported options:
222+
223+
- `--remove` to remove the tool instead of adding it
224+
- `--how` to only print how to use the tool, with no other side effects
225+
- `--offline` to disable network access and rely on caches
226+
- `--frozen` to leave the virtual environment and lockfile unchanged
227+
- `--quiet` to suppress output
228+
229+
See [`usethis tool`](#usethis-tool) for more information.
230+
206231
### `usethis format`
207232

208233
Add recommended formatters to the project (namely, [Ruff](https://docs.astral.sh/ruff/formatter/) and [pyproject-fmt](https://pyproject-fmt.readthedocs.io/en/latest/)), including:
@@ -311,7 +336,7 @@ declaring dependencies with `uv add`.
311336

312337
#### Documentation
313338

314-
- `usethis tool mkdocs` - Use [MkDocs](https://www.mkdocs.org/): project documentation sites with Markdown.
339+
- `usethis tool mkdocs` - Use [MkDocs](https://www.mkdocs.org/): Generate project documentation sites with Markdown.
315340

316341
#### Configuration Files
317342

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -202,7 +202,7 @@ name = "usethis._interface"
202202
type = "layers"
203203
layers = [
204204
# Note; if you're adding an interface, make sure it's in the README too.
205-
"author | badge | browse | ci | docstyle | format_ | init | lint | list | readme | rule | show | spellcheck | status | test | tool | version",
205+
"author | badge | browse | ci | doc | docstyle | format_ | init | lint | list | readme | rule | show | spellcheck | status | test | tool | version",
206206
]
207207
containers = [ "usethis._interface" ]
208208
exhaustive = true

‎src/usethis/_app.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
import usethis._interface.badge
77
import usethis._interface.browse
88
import usethis._interface.ci
9+
import usethis._interface.doc
910
import usethis._interface.docstyle
1011
import usethis._interface.format_
1112
import usethis._interface.init
@@ -38,6 +39,12 @@
3839
)
3940

4041
rich_help_panel = "Manage Tooling"
42+
app.command(
43+
help="Add or configure recommended documentation tools.",
44+
rich_help_panel=rich_help_panel,
45+
)(
46+
usethis._interface.doc.doc,
47+
)
4148
app.command(
4249
name="format",
4350
help="Add or configure recommended formatters.",

‎src/usethis/_interface/doc.py‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
import typer
2+
3+
from usethis._options import frozen_opt, how_opt, offline_opt, quiet_opt, remove_opt
4+
5+
6+
def doc(
7+
remove: bool = remove_opt,
8+
how: bool = how_opt,
9+
offline: bool = offline_opt,
10+
quiet: bool = quiet_opt,
11+
frozen: bool = frozen_opt,
12+
) -> None:
13+
"""Add a recommended documentation framework to the project."""
14+
from usethis._config import usethis_config
15+
from usethis._config_file import files_manager
16+
from usethis._console import err_print
17+
from usethis._toolset.doc import use_doc_frameworks
18+
from usethis.errors import UsethisError
19+
20+
with (
21+
usethis_config.set(offline=offline, quiet=quiet, frozen=frozen),
22+
files_manager(),
23+
):
24+
try:
25+
use_doc_frameworks(remove=remove, how=how)
26+
except UsethisError as err:
27+
err_print(err)
28+
raise typer.Exit(code=1) from None

‎src/usethis/_interface/init.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,13 @@
66
from usethis._core.enums.docstyle import DocStyleEnum
77
from usethis._core.enums.status import DevelopmentStatusEnum
88
from usethis._options import frozen_opt, offline_opt, quiet_opt
9+
from usethis._toolset.doc import use_doc_frameworks
910

1011

1112
def init( # noqa: PLR0913, PLR0915
13+
doc: bool = typer.Option(
14+
True, "--doc/--no-doc", help="Add a recommended documentation framework."
15+
),
1216
format_: bool = typer.Option(
1317
True, "--format/--no-format", help="Add recommended formatters."
1418
),
@@ -95,6 +99,11 @@ def init( # noqa: PLR0913, PLR0915
9599
use_pre_commit()
96100
use_pre_commit(how=True)
97101

102+
if doc:
103+
tick_print("Adding recommended documentation tools.")
104+
with usethis_config.set(alert_only=True):
105+
use_doc_frameworks()
106+
use_doc_frameworks(how=True)
98107
if lint:
99108
tick_print("Adding recommended linters.")
100109
with usethis_config.set(alert_only=True):

‎src/usethis/_interface/tool.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ def import_linter(
115115

116116
@app.command(
117117
name="mkdocs",
118-
help="Use MkDocs: project documentation sites with Markdown.",
118+
help="Use MkDocs: Generate project documentation sites with Markdown.",
119119
rich_help_panel="Documentation",
120120
)
121121
def mkdocs(

‎src/usethis/_toolset/doc.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
from usethis._core.tool import use_mkdocs
2+
3+
4+
def use_doc_frameworks(remove: bool = False, how: bool = False):
5+
use_mkdocs(remove=remove, how=how)

‎tests/usethis/_interface/test_doc.py‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
from pathlib import Path
2+
3+
from typer.testing import CliRunner
4+
5+
from usethis._app import app
6+
from usethis._config_file import files_manager
7+
from usethis._integrations.uv.deps import Dependency, get_deps_from_group
8+
from usethis._test import change_cwd
9+
10+
11+
class TestDoc:
12+
def test_dependencies_added(self, tmp_path: Path):
13+
# Act
14+
runner = CliRunner()
15+
with change_cwd(tmp_path):
16+
result = runner.invoke(app, ["doc"])
17+
18+
# Assert
19+
assert result.exit_code == 0, result.output
20+
with change_cwd(tmp_path), files_manager():
21+
assert Dependency(name="mkdocs") in get_deps_from_group("doc")

‎tests/usethis/_interface/test_init.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@ def test_pre_commit_included(self, tmp_path: Path):
2626
"✔ Setting the development status to '1 - Planning'.\n"
2727
"✔ Adding the pre-commit framework.\n"
2828
"☐ Run 'uv run pre-commit run --all-files' to run the hooks manually.\n"
29+
"✔ Adding recommended documentation tools.\n"
30+
"☐ Run 'uv run mkdocs build' to build the documentation.\n"
31+
"☐ Run 'uv run mkdocs serve' to serve the documentation locally.\n"
2932
"✔ Adding recommended linters.\n"
3033
"☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.\n"
3134
"☐ Run 'uv run deptry src' to run deptry.\n"
@@ -76,6 +79,9 @@ def test_readme_example(self, tmp_path: Path):
7679
✔ Writing 'README.md'.
7780
☐ Populate 'README.md' to help users understand the project.
7881
✔ Setting the development status to '1 - Planning'.
82+
✔ Adding recommended documentation tools.
83+
☐ Run 'uv run mkdocs build' to build the documentation.
84+
☐ Run 'uv run mkdocs serve' to serve the documentation locally.
7985
✔ Adding recommended linters.
8086
☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.
8187
☐ Run 'uv run deptry src' to run deptry.
@@ -144,6 +150,9 @@ def test_bitbucket_docstyle_and_status(self, tmp_path: Path):
144150
"✔ Setting the development status to '5 - Production/Stable'.\n"
145151
"✔ Adding the pre-commit framework.\n"
146152
"☐ Run 'uv run pre-commit run --all-files' to run the hooks manually.\n"
153+
"✔ Adding recommended documentation tools.\n"
154+
"☐ Run 'uv run mkdocs build' to build the documentation.\n"
155+
"☐ Run 'uv run mkdocs serve' to serve the documentation locally.\n"
147156
"✔ Adding recommended linters.\n"
148157
"☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.\n"
149158
"☐ Run 'uv run deptry src' to run deptry.\n"

‎tests/usethis/_interface/test_test.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
from usethis._test import change_cwd
99

1010

11-
class TestSpellcheck:
11+
class TestTest:
1212
def test_dependencies_added(self, tmp_path: Path):
1313
# Act
1414
runner = CliRunner()

0 commit comments

Comments
 (0)