usethis-python · nathanjmcdougall · Jul 15, 2025 · Jul 15, 2025 · Jul 15, 2025
diff --git a/README.md b/README.md
@@ -73,6 +73,7 @@ $ pipx run usethis tool ruff
 
 ### Manage Tooling
 
+- [`usethis doc`](#usethis-doc) — Add/Configure recommended documentation tools (namely, [MkDocs](https://www.mkdocs.org/)).
 - [`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/)).
 - [`usethis lint`](#usethis-lint) — Add/Configure recommended linters (namely, [Ruff](https://docs.astral.sh/ruff/linter) and [deptry](https://github.com/fpgmaas/deptry)).
 - [`usethis spellcheck`](#usethis-spellcheck) — Add/Configure recommended spellcheckers (namely, [codespell](https://github.com/codespell-project/codespell)).
@@ -108,6 +109,9 @@ $ 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.
@@ -177,6 +181,7 @@ Initialize a new Python project with recommended defaults, including:
 
 Supported options:
 
+- `--doc` to add recommended documentation tools (default; or `--no-doc` to opt-out)
 - `--format` to add recommended formatters (default; or `--no-format` to opt-out)
 - `--lint` to add recommended linters (default; or `--no-lint` to opt-out)
 - `--spellcheck` to add a recommended spellchecker (default; or `--no-spellcheck` to opt-out)
@@ -203,6 +208,26 @@ Supported options:
 - `--quiet` to suppress output
 - `--frozen` to leave the virtual environment and lockfile unchanged (i.e. do not install dependencies, nor update lockfiles)
 
+### `usethis doc`
+
+Add recommended documentation tools to the project (namely, [MkDocs](https://www.mkdocs.org/)), including:
+
+- declared & installed dependencies via `uv add`,
+- relevant `pyproject.toml` configuration, and
+- any other relevant directories or tool-bespoke configuration files.
+
+Note if `pyproject.toml` is not present, it will be created, since this is required for declaring dependencies via `uv add`.
+
+Supported options:
+
+- `--remove` to remove the tool instead of adding it
+- `--how` to only print how to use the tool, with no other side effects
+- `--offline` to disable network access and rely on caches
+- `--frozen` to leave the virtual environment and lockfile unchanged
+- `--quiet` to suppress output
+
+See [`usethis tool`](#usethis-tool) for more information.
+
 ### `usethis format`
 
 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`.
 
 #### Documentation
 
-- `usethis tool mkdocs` - Use [MkDocs](https://www.mkdocs.org/): project documentation sites with Markdown.
+- `usethis tool mkdocs` - Use [MkDocs](https://www.mkdocs.org/): Generate project documentation sites with Markdown.
 
 #### Configuration Files
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -202,7 +202,7 @@ name = "usethis._interface"
 type = "layers"
 layers = [
   # Note; if you're adding an interface, make sure it's in the README too.
-  "author | badge | browse | ci | docstyle | format_ | init | lint | list | readme | rule | show | spellcheck | status | test | tool | version",
+  "author | badge | browse | ci | doc | docstyle | format_ | init | lint | list | readme | rule | show | spellcheck | status | test | tool | version",
 ]
 containers = [ "usethis._interface" ]
 exhaustive = true

diff --git a/src/usethis/_app.py b/src/usethis/_app.py
@@ -6,6 +6,7 @@
 import usethis._interface.badge
 import usethis._interface.browse
 import usethis._interface.ci
+import usethis._interface.doc
 import usethis._interface.docstyle
 import usethis._interface.format_
 import usethis._interface.init
@@ -38,6 +39,12 @@
 )
 
 rich_help_panel = "Manage Tooling"
+app.command(
+    help="Add or configure recommended documentation tools.",
+    rich_help_panel=rich_help_panel,
+)(
+    usethis._interface.doc.doc,
+)
 app.command(
     name="format",
     help="Add or configure recommended formatters.",

diff --git a/src/usethis/_interface/doc.py b/src/usethis/_interface/doc.py
@@ -0,0 +1,28 @@
+import typer
+
+from usethis._options import frozen_opt, how_opt, offline_opt, quiet_opt, remove_opt
+
+
+def doc(
+    remove: bool = remove_opt,
+    how: bool = how_opt,
+    offline: bool = offline_opt,
+    quiet: bool = quiet_opt,
+    frozen: bool = frozen_opt,
+) -> None:
+    """Add a recommended documentation framework to the project."""
+    from usethis._config import usethis_config
+    from usethis._config_file import files_manager
+    from usethis._console import err_print
+    from usethis._toolset.doc import use_doc_frameworks
+    from usethis.errors import UsethisError
+
+    with (
+        usethis_config.set(offline=offline, quiet=quiet, frozen=frozen),
+        files_manager(),
+    ):
+        try:
+            use_doc_frameworks(remove=remove, how=how)
+        except UsethisError as err:
+            err_print(err)
+            raise typer.Exit(code=1) from None
diff --git a/src/usethis/_interface/init.py b/src/usethis/_interface/init.py
@@ -6,9 +6,13 @@
 from usethis._core.enums.docstyle import DocStyleEnum
 from usethis._core.enums.status import DevelopmentStatusEnum
 from usethis._options import frozen_opt, offline_opt, quiet_opt
+from usethis._toolset.doc import use_doc_frameworks
 
 
 def init(  # noqa: PLR0913, PLR0915
+    doc: bool = typer.Option(
+        True, "--doc/--no-doc", help="Add a recommended documentation framework."
+    ),
     format_: bool = typer.Option(
         True, "--format/--no-format", help="Add recommended formatters."
     ),
@@ -95,6 +99,11 @@ def init(  # noqa: PLR0913, PLR0915
                     use_pre_commit()
                 use_pre_commit(how=True)
 
+            if doc:
+                tick_print("Adding recommended documentation tools.")
+                with usethis_config.set(alert_only=True):
+                    use_doc_frameworks()
+                use_doc_frameworks(how=True)
             if lint:
                 tick_print("Adding recommended linters.")
                 with usethis_config.set(alert_only=True):

diff --git a/src/usethis/_interface/tool.py b/src/usethis/_interface/tool.py
@@ -115,7 +115,7 @@ def import_linter(
 
 @app.command(
     name="mkdocs",
-    help="Use MkDocs: project documentation sites with Markdown.",
+    help="Use MkDocs: Generate project documentation sites with Markdown.",
     rich_help_panel="Documentation",
 )
 def mkdocs(

diff --git a/src/usethis/_toolset/doc.py b/src/usethis/_toolset/doc.py
@@ -0,0 +1,5 @@
+from usethis._core.tool import use_mkdocs
+
+
+def use_doc_frameworks(remove: bool = False, how: bool = False):
+    use_mkdocs(remove=remove, how=how)
diff --git a/tests/usethis/_interface/test_doc.py b/tests/usethis/_interface/test_doc.py
@@ -0,0 +1,21 @@
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+from usethis._app import app
+from usethis._config_file import files_manager
+from usethis._integrations.uv.deps import Dependency, get_deps_from_group
+from usethis._test import change_cwd
+
+
+class TestDoc:
+    def test_dependencies_added(self, tmp_path: Path):
+        # Act
+        runner = CliRunner()
+        with change_cwd(tmp_path):
+            result = runner.invoke(app, ["doc"])
+
+        # Assert
+        assert result.exit_code == 0, result.output
+        with change_cwd(tmp_path), files_manager():
+            assert Dependency(name="mkdocs") in get_deps_from_group("doc")
diff --git a/tests/usethis/_interface/test_init.py b/tests/usethis/_interface/test_init.py
@@ -26,6 +26,9 @@ def test_pre_commit_included(self, tmp_path: Path):
             "✔ Setting the development status to '1 - Planning'.\n"
             "✔ Adding the pre-commit framework.\n"
             "☐ Run 'uv run pre-commit run --all-files' to run the hooks manually.\n"
+            "✔ Adding recommended documentation tools.\n"
+            "☐ Run 'uv run mkdocs build' to build the documentation.\n"
+            "☐ Run 'uv run mkdocs serve' to serve the documentation locally.\n"
             "✔ Adding recommended linters.\n"
             "☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.\n"
             "☐ Run 'uv run deptry src' to run deptry.\n"
@@ -76,6 +79,9 @@ def test_readme_example(self, tmp_path: Path):
 ✔ 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 ruff check --fix' to run the Ruff linter with autofixes.
 ☐ Run 'uv run deptry src' to run deptry.
@@ -144,6 +150,9 @@ def test_bitbucket_docstyle_and_status(self, tmp_path: Path):
             "✔ Setting the development status to '5 - Production/Stable'.\n"
             "✔ Adding the pre-commit framework.\n"
             "☐ Run 'uv run pre-commit run --all-files' to run the hooks manually.\n"
+            "✔ Adding recommended documentation tools.\n"
+            "☐ Run 'uv run mkdocs build' to build the documentation.\n"
+            "☐ Run 'uv run mkdocs serve' to serve the documentation locally.\n"
             "✔ Adding recommended linters.\n"
             "☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.\n"
             "☐ Run 'uv run deptry src' to run deptry.\n"

diff --git a/tests/usethis/_interface/test_test.py b/tests/usethis/_interface/test_test.py
@@ -8,7 +8,7 @@
 from usethis._test import change_cwd
 
 
-class TestSpellcheck:
+class TestTest:
     def test_dependencies_added(self, tmp_path: Path):
         # Act
         runner = CliRunner()