FEAT-19: Add Google Style Documentation Comments

.gitignore

@@ -19,6 +19,7 @@ wheels/
 .claude/skills/video-planner/
 .videos/
 graph.mmd
+docs/pdoc/
 scripts/*.ps1
 scripts/*.cmd
 

.vscode/tasks.json

@@ -0,0 +1,19 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Build Roadmap and Diagram",
+            "type": "shell",
+            "command": "docket graph todo -o .\\graph.mmd; docket docs roadmap todo",
+            "problemMatcher": []
+        },
+        {
+            "label": "Build API Docs",
+            "type": "shell",
+            "command": "uv run pdoc -d google -o docs/pdoc docket",
+            "problemMatcher": []
+        }
+    ]
+}

CLAUDE.md

@@ -25,7 +25,7 @@ Match existing style exactly:
 - camelCase for functions, variables, params (`updateRootBranches`, `doTheThing`). NOT snake_case. Repo-wide, intentional, keep it.
 - `# MARK: Imports` / `# MARK: Constants` / `# MARK: Functions` / `# MARK: Classes` section headers in every module.
 - Module docstring: title line, blank line, one-line description.
-- Function docstrings: description, blank line, then `paramName: description.` lines (no Sphinx/Google style), then `Returns ...` sentence. Backticks around code refs.
+- Function docstrings are in Google Style. Backticks around code refs. Backticks around code refs.
 - Inline comment above nearly every logical block, short imperative ("# Stash the changes").
 - Full type hints everywhere. `Optional[X]` / `Union[X, Y]` from typing, builtin generics (`list[str]`, `dict[str, Any]`).
 - Private helpers: `_name` or `__name` prefix.

CONTRIBUTING.md

@@ -12,6 +12,7 @@ Docket runs on Docket.
     * [Issues and Tickets](#issues-and-tickets)
     * [Getting Set Up](#getting-set-up)
     * [Code Style](#code-style)
+        * [API Docs](#api-docs)
     * [Naming Across Interfaces](#naming-across-interfaces)
     * [Versioning](#versioning)
     * [Tests](#tests)
@@ -65,7 +66,7 @@ Match the surrounding code exactly:
 - **camelCase** for functions, variables, and parameters, never snake_case.
 - **`# MARK:` section headers** in every module: `Imports`, `Constants`, `Functions`, `Classes`, in that order.
 - **Module docstrings**: title line, blank line, one line description.
-- **Function docstrings**: description, blank line, `paramName: description.` lines, then a `Returns ...` sentence. No Sphinx or Google style. Backticks around code references.
+- **Function docstrings**: Google Style, with `Args:`, `Returns:`, and `Raises:` sections as needed. Backticks around code references.
 - **A short imperative comment above nearly every logical block.** "Stash the changes", not a paragraph.
 - **Full type hints everywhere.** `Optional[X]` and `Union[X, Y]` from `typing`, builtin generics like `list[str]`.
 - **Private helpers** are prefixed `_name` or `__name`.
@@ -76,6 +77,18 @@ Match the surrounding code exactly:
 Scripts under `scripts/` are standalone and import nothing from `docket`.
 Keep them that way.
 
+### API Docs
+
+The docstrings render into browsable API docs with [pdoc](https://pdoc.dev).
+They are for contributors only, are never hosted, and are git ignored.
+
+```bash
+uv run pdoc -d google docket                   # live server with reload
+uv run pdoc -d google -o docs/pdoc docket      # static HTML into docs/pdoc/
+```
+
+The `Build API Docs` VS Code task runs the static build.
+
 ## Naming Across Interfaces
 
 Two external interfaces deliberately break camelCase, and neither convention leaks into the other.

docs/tickets/todo/FEAT-19_addGoogleStyleDocumentationComments.md → docs/tickets/done/FEAT-19_addGoogleStyleDocumentationComments.md

@@ -1,7 +1,7 @@
 ---
 id: FEAT-19
 title: Add Google Style Documentation Comments
-status: todo
+status: done
 priority: 1
 requires: []
 metadata: {}

docs/tickets/todo/FEAT-20_cliAccessorsForAllHeadmatter.md

@@ -0,0 +1,18 @@
+---
+id: FEAT-20
+title: CLI Accessors for All Headmatter
+status: todo
+priority: 0
+requires: []
+metadata: {}
+---
+
+# CLI Accessors for All Headmatter
+
+Right now, only `status` (which gets `status` from the headmatter) and `meta` (which gets the `metadata` from the headmatter) exist to provide pipeable accessors to headmatter data for tickets.
+
+`show` exists, but prints the ticket information in a *human-centric* format which is not well suited for scripting.
+
+To resolve this, accessors should be added to `docket <ticket_id> ...` in some manner to facilitate direct output of headmatter information in a pipeable way.
+
+A note should be made in instruction files to ensure that any new ticket headmatter also receives an accessor.

pyproject.toml

@@ -74,6 +74,7 @@ testpaths = ["tests"]
 
 [dependency-groups]
 dev = [
+    "pdoc>=16.0.0",
     "pytest>=9.1.1",
     "twine>=6.1.0",
 ]

roadmap.md

@@ -1,66 +1,29 @@
-# Roadmap
+# Roadmap: todo
 
 > Generated with `docket docs roadmap`.
 
 ```mermaid
 graph TD
   subgraph BUG
-    BUG_1("BUG-1<br/>Fix Character Encoding<br/>Issue in FEAT-5<br/>p1 done")
-    BUG_2("BUG-2<br/>Cannot Clear with Set<br/>Command<br/>p0 done")
-    BUG_3("BUG-3<br/>Migrate Server to MCP<br/>2.x MCPServer API<br/>p0 done")
-    BUG_4("BUG-4<br/>Add to Requires in CLI<br/>p1 done")
-    BUG_5("BUG-5<br/>Serialize Ticket Writes<br/>Across Processes<br/>p3 done")
     BUG_6["BUG-6<br/>Key Removal Checks Usage<br/>Outside the Lock<br/>p4 todo"]
   end
   subgraph FEAT
-    FEAT_1("FEAT-1<br/>Record Demo GIF with VHS<br/>p2 done")
-    FEAT_2("FEAT-2<br/>Set Up and Publish to<br/>PyPI<br/>p3 done")
-    FEAT_3("FEAT-3<br/>All Tickets Graph<br/>p2 done")
-    FEAT_4("FEAT-4<br/>Shorthand for CLI<br/>p2 done")
-    FEAT_5("FEAT-5<br/>Selection Options in CLI<br/>p2 done")
     FEAT_6["FEAT-6<br/>Templates for Tickets<br/>per Key<br/>p3 todo"]
-    FEAT_7("FEAT-7<br/>Unified Version Code<br/>p1 done")
     FEAT_8["FEAT-8<br/>Host Flag<br/>p4 todo"]
-    FEAT_9("FEAT-9<br/>Track Arbitrary<br/>Additional Metadata on<br/>Tickets/Groups<br/>p1 done")
-    FEAT_10("FEAT-10<br/>Tree Style CLI Commands<br/>p2 done")
-    FEAT_11("FEAT-11<br/>Repository Automation<br/>and Contribution<br/>Scaffolding<br/>p3 done")
     FEAT_12["FEAT-12<br/>Per Key Ticket Board<br/>View<br/>p2 todo"]
-    FEAT_13("FEAT-13<br/>Check if Ticket Is Ready<br/>for Work<br/>p1 done")
-    FEAT_14["FEAT-14<br/>Roadmap Graph Generation<br/>p2 todo"]
-    FEAT_15("FEAT-15<br/>Use Title Case for<br/>Tickets<br/>p1 done")
     FEAT_16["FEAT-16<br/>Ticket Show Uses<br/>Optional Formatting<br/>p2 todo"]
-    FEAT_17("FEAT-17<br/>Add Status to Graph<br/>Scope<br/>p1 done")
-    FEAT_18("FEAT-18<br/>Offsite Ticket Authoring<br/>Brief<br/>p1 done")
     FEAT_19["FEAT-19<br/>Add Google Style<br/>Documentation Comments<br/>p1 todo"]
+    FEAT_20["FEAT-20<br/>CLI Accessors for All<br/>Headmatter<br/>p0 todo"]
   end
-  BUG_1 --> FEAT_2
-  BUG_1 --> FEAT_5
-  BUG_2 --> FEAT_2
-  BUG_3 --> FEAT_2
-  BUG_4 --> FEAT_2
-  BUG_5 --> BUG_6
-  BUG_5 --> FEAT_2
-  FEAT_1 --> FEAT_2
-  FEAT_2 --> FEAT_11
-  FEAT_4 --> FEAT_2
-  FEAT_5 --> FEAT_2
   FEAT_6 --> FEAT_12
-  FEAT_7 --> FEAT_2
-  FEAT_10 --> FEAT_2
-  classDef doneP0 fill:#2d6a4f,color:#fff,stroke:#ff6b6b,stroke-width:4px
-  classDef doneP1 fill:#2d6a4f,color:#fff,stroke:#ff922b,stroke-width:3px
-  classDef doneP2 fill:#2d6a4f,color:#fff,stroke:#ffd43b,stroke-width:2px
-  classDef doneP3 fill:#2d6a4f,color:#fff,stroke:#adb5bd,stroke-width:2px
+  classDef todoP0 fill:#495057,color:#fff,stroke:#ff6b6b,stroke-width:4px
   classDef todoP1 fill:#495057,color:#fff,stroke:#ff922b,stroke-width:3px
   classDef todoP2 fill:#495057,color:#fff,stroke:#ffd43b,stroke-width:2px
   classDef todoP3 fill:#495057,color:#fff,stroke:#adb5bd,stroke-width:2px
   classDef todoP4 fill:#495057,color:#fff,stroke:#6c757d,stroke-width:1px
-  class BUG_2,BUG_3 doneP0
-  class BUG_1,BUG_4,FEAT_13,FEAT_15,FEAT_17,FEAT_18,FEAT_7,FEAT_9 doneP1
-  class FEAT_1,FEAT_10,FEAT_3,FEAT_4,FEAT_5 doneP2
-  class BUG_5,FEAT_11,FEAT_2 doneP3
+  class FEAT_20 todoP0
   class FEAT_19 todoP1
-  class FEAT_12,FEAT_14,FEAT_16 todoP2
+  class FEAT_12,FEAT_16 todoP2
   class FEAT_6 todoP3
   class BUG_6,FEAT_8 todoP4
 ```

src/docket/__init__.py

@@ -8,4 +8,4 @@
 
 # No type check to comply with hatch's requirements.
 # Do not re-add.
-__version__ = "1.5.0"
+__version__ = "1.6.0"

src/docket/cli/__init__.py

@@ -118,9 +118,11 @@ def main(argv: Optional[list[str]] = None) -> int:
     """
     Entry point for the `docket` console script.
 
-    argv: Argument list to parse, defaulting to `sys.argv[1:]`.
+    Args:
+        argv: Argument list to parse, defaulting to `sys.argv[1:]`.
 
-    Returns the process exit code.
+    Returns:
+        The process exit code.
     """
 
     # Read the configuration before the parser is built, so the help text can name the keys and priorities this repository actually allows. A missing one is not fatal here, since the commands that need it say so themselves.
@@ -151,11 +153,13 @@ def dispatch(args: argparse.Namespace, config: Optional[Config], output: Output)
     """
     Route parsed arguments to the command that handles them.
 
-    args: The parsed arguments.
-    config: The configuration already discovered for the help text, or `None` when none was found.
-    output: Where to write.
+    Args:
+        args: The parsed arguments.
+        config: The configuration already discovered for the help text, or `None` when none was found.
+        output: Where to write.
 
-    Returns the process exit code.
+    Returns:
+        The process exit code.
     """
 
     # Deploy and upgrade run before a configuration exists, or in order to repair one, so they must not require discovering it first.