From ba9e5cf0058a9d4cee4a6758ef318ee07b18713c Mon Sep 17 00:00:00 2001
From: John Sirois <john.sirois@gmail.com>
Date: Sun, 26 Jan 2025 22:51:16 -0800
Subject: [PATCH] Upgrade dev-cmd and document commands & tasks. (#128)

Now:
```console
:; uvrc -l
Commands:
(5 commands are hidden.)
check-python-version
fmt
check-fmt
lint
check-lint
type-check
doc
    -type: The type of sphinx doc to build. One of:
           html, dirhtml, htmlhelp, qthelp, devhelp, text, gettext, linkcheck or xml.
           [default: html]

Tasks:
test
linkcheck: Check documentation for broken links.
package: Build the science scies using science from local sources.
science: Runs science from local sources. Accepts extra args after --.
checks: Runs all development checks, including auto-formatting code.
ci: Runs all checks used for CI.
```
---
 pyproject.toml | 48 ++++++++++++++++++++++++++++++++++++++----------
 uv.lock        |  8 +++++---
 2 files changed, 43 insertions(+), 13 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 706d643..515ba7f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -101,11 +101,12 @@ check-lint = ["ruff", "check"]
 
 type-check = ["mypy", "docs/_ext", "science", "scripts", "setup.py", "tests", "test-support"]
 
-doc = ["sphinx-build", "-b", "{-type:html}", "-aEW", "docs", "docs/build/{-type:html}"]
+[tool.dev-cmd.commands.create-zipapp]
+args = ["scripts/create-zipapp.py"]
+hidden = true
 
-create-zipapp = ["scripts/create-zipapp.py"]
-
-package-thin-scie = [
+[tool.dev-cmd.commands.package-thin-scie]
+args = [
     "python",
     "dist/science.pyz",
     "lift",
@@ -121,8 +122,10 @@ package-thin-scie = [
     "--dest-dir",
     "dist",
 ]
+hidden = true
 
-package-fat-scie = [
+[tool.dev-cmd.commands.package-fat-scie]
+args = [
     "python",
     "dist/science.pyz",
     "lift",
@@ -142,29 +145,54 @@ package-fat-scie = [
     "--dest-dir",
     "dist",
 ]
+hidden = true
+
+[tool.dev-cmd.commands.doc.factors]
+type = """\
+The type of sphinx doc to build. One of:
+html, dirhtml, htmlhelp, qthelp, devhelp, text, gettext, linkcheck or xml.
+"""
+[tool.dev-cmd.commands.doc]
+args = ["sphinx-build", "-b", "{-type:html}", "-aEW", "docs", "docs/build/{-type:html}"]
 
 [tool.dev-cmd.commands.run-zipapp]
 env = {"SCIENCE_DOC_LOCAL" = "docs/build/html"}
 args = ["python", "dist/science.pyz"]
 accepts-extra-args = true
+hidden = true
 
 [tool.dev-cmd.commands.pytest]
 args = ["pytest", "-n", "auto"]
 cwd = "tests"
 accepts-extra-args = true
+hidden = true
 [tool.dev-cmd.commands.pytest.env]
 BUILD_ROOT = ".."
 PYTHONPATH = "../test-support"
 SCIENCE_TEST_PYZ_PATH = "../dist/science.pyz"
 
 [tool.dev-cmd.tasks]
-linkcheck = ["doc-type:linkcheck"]
 test = ["create-zipapp", "pytest"]
-checks = [["check-python-version", ["fmt", "lint"]], "type-check", "test"]
-ci = [["check-python-version", "check-fmt", "check-lint", "type-check"], "test"]
-science = [["doc", "create-zipapp"], "run-zipapp"]
 
-package = [["doc", "create-zipapp"], ["package-thin-scie", "package-fat-scie"]]
+[tool.dev-cmd.tasks.linkcheck]
+description = "Check documentation for broken links."
+steps = ["doc-type:linkcheck"]
+
+[tool.dev-cmd.tasks.package]
+description = "Build the science scies using science from local sources."
+steps = [["doc", "create-zipapp"], ["package-thin-scie", "package-fat-scie"]]
+
+[tool.dev-cmd.tasks.science]
+description = "Runs science from local sources. Accepts extra args after --."
+steps = [["doc", "create-zipapp"], "run-zipapp"]
+
+[tool.dev-cmd.tasks.checks]
+description = "Runs all development checks, including auto-formatting code."
+steps = [["check-python-version", ["fmt", "lint"]], "type-check", "test"]
+
+[tool.dev-cmd.tasks.ci]
+description = "Runs all checks used for CI."
+steps = [["check-python-version", "check-fmt", "check-lint", "type-check"], "test"]
 
 [tool.dev-cmd]
 default = "checks"
diff --git a/uv.lock b/uv.lock
index f495e0f..76783f7 100644
--- a/uv.lock
+++ b/uv.lock
@@ -150,7 +150,7 @@ wheels = [
 
 [[package]]
 name = "dev-cmd"
-version = "0.13.0"
+version = "0.15.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aioconsole" },
@@ -159,8 +159,9 @@ dependencies = [
     { name = "packaging" },
     { name = "typing-extensions" },
 ]
+sdist = { url = "https://files.pythonhosted.org/packages/d4/15/9486a9383319132c3cc2005364508e8ca2ab4296c8401307f685795a0043/dev_cmd-0.15.0.tar.gz", hash = "sha256:f2ae669574c43bcf3319123679e8f98d8d9af549a81da84856a889e7c5380b55", size = 41750 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e9/ab/2d9aa6dbb7a4305ce7c3be03895596992762d39b0e408f3809c7bfcfd884/dev_cmd-0.13.0-py3-none-any.whl", hash = "sha256:0f3211e624806ba5b6a62e4edb7e4a3fbc908a31f88f9c4aca87f330b0f1822c", size = 32452 },
+    { url = "https://files.pythonhosted.org/packages/68/0e/6c3d8b6ae50f82d54cdaef99f1da5bd1147b6de78121935011dcbc212766/dev_cmd-0.15.0-py3-none-any.whl", hash = "sha256:36a72f4e8d7bca161277af33d00a828eefa759b45554ce6bed71d1cfd1fc3bc4", size = 34739 },
 ]
 
 [[package]]
@@ -517,6 +518,7 @@ wheels = [
 
 [[package]]
 name = "science"
+version = "0.11.2"
 source = { editable = "." }
 dependencies = [
     { name = "appdirs" },
@@ -586,7 +588,7 @@ dev = [
     { name = "shiv" },
     { name = "sphinx" },
     { name = "sphinx-click" },
-    { name = "sphinx-library", git = "https://github.com/vsalvino/sphinx-library?rev=5cbb26686cf8d5b9201074ab7aa7ee5f6b3bd02b#5cbb26686cf8d5b9201074ab7aa7ee5f6b3bd02b" },
+    { name = "sphinx-library", git = "https://github.com/vsalvino/sphinx-library?rev=5cbb26686cf8d5b9201074ab7aa7ee5f6b3bd02b" },
     { name = "toml" },
     { name = "types-appdirs" },
     { name = "types-beautifulsoup4" },