spec-kitty-cli 0.12.1__py3-none-any.whl

specify_cli/missions/documentation/templates/divio/reference-template.md

@@ -0,0 +1,179 @@
+---
+type: reference
+divio_category: information-oriented
+target_audience: all-users
+purpose: technical-description
+outcome: user-knows-what-exists
+---
+
+# Reference: {API/CLI/CONFIG_NAME}
+
+> **Divio Type**: Reference (Information-Oriented)
+> **Target Audience**: All users looking up technical details
+> **Purpose**: Provide accurate, complete technical description
+> **Outcome**: User finds the information they need
+
+## Overview
+
+{Brief description of what this reference documents}
+
+**Quick Navigation**:
+- [{Section 1}](#{section-anchor})
+- [{Section 2}](#{section-anchor})
+- [{Section 3}](#{section-anchor})
+
+## {API Class/CLI Command/Config Section}
+
+### Syntax
+
+```{language}
+{canonical-syntax}
+```
+
+### Description
+
+{Neutral, factual description of what this does}
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `{param1}` | `{type}` | Yes | - | {Description} |
+| `{param2}` | `{type}` | No | `{default}` | {Description} |
+| `{param3}` | `{type}` | No | `{default}` | {Description} |
+
+### Return Value
+
+**Type**: `{return-type}`
+
+**Description**: {What is returned}
+
+**Possible values**:
+- `{value1}`: {When this is returned}
+- `{value2}`: {When this is returned}
+
+### Exceptions / Errors
+
+| Error | Condition | Resolution |
+|-------|-----------|------------|
+| `{ErrorType}` | {When it occurs} | {How to handle} |
+| `{ErrorType}` | {When it occurs} | {How to handle} |
+
+### Examples
+
+**Basic usage**:
+```{language}
+{basic-example}
+```
+
+**With options**:
+```{language}
+{example-with-options}
+```
+
+**Advanced usage**:
+```{language}
+{advanced-example}
+```
+
+### Notes
+
+- {Important implementation detail}
+- {Edge case or limitation}
+- {Performance consideration}
+
+### See Also
+
+- [{Related API/command}](#{anchor})
+- [{Related concept}](../explanation/{link})
+
+---
+
+## {Next API Class/CLI Command/Config Section}
+
+{Repeat the structure above for each item being documented}
+
+---
+
+## Constants / Enumerations
+
+### `{ConstantName}`
+
+**Type**: `{type}`
+**Value**: `{value}`
+**Description**: {What it represents}
+
+**Usage**:
+```{language}
+{usage-example}
+```
+
+---
+
+## Type Definitions
+
+### `{TypeName}`
+
+```{language}
+{type-definition}
+```
+
+**Properties**:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `{prop1}` | `{type}` | {Description} |
+| `{prop2}` | `{type}` | {Description} |
+
+**Example**:
+```{language}
+{example-usage}
+```
+
+---
+
+## Version History
+
+### Version {X.Y.Z}
+- Added: `{new-feature}`
+- Changed: `{modified-behavior}`
+- Deprecated: `{old-feature}` (use `{new-feature}` instead)
+- Removed: `{removed-feature}`
+
+### Version {X.Y.Z}
+- {Changes in this version}
+
+---
+
+## Write the Docs Best Practices (Remove this section before publishing)
+
+**Reference Principles**:
+- ✅ Information-oriented: Describe facts accurately
+- ✅ Structure around code organization (classes, modules, commands)
+- ✅ Consistent format for all similar items
+- ✅ Complete and accurate
+- ✅ Neutral tone (no opinions or recommendations)
+- ✅ Include examples for every item
+- ✅ Do not explain how to use (that's How-To) or why (that's Explanation)
+
+**Accessibility**:
+- ✅ Proper heading hierarchy
+- ✅ Alt text for diagrams/screenshots
+- ✅ Tables for structured data
+- ✅ Syntax highlighting for code
+- ✅ Descriptive link text
+
+**Inclusivity**:
+- ✅ Diverse example names
+- ✅ Gender-neutral language
+- ✅ No cultural assumptions
+
+**Reference-Specific Guidelines**:
+- Alphabetical or logical ordering
+- Every public API/command documented
+- Parameters/options in consistent format (tables work well)
+- Examples for typical usage
+- Don't bury the lead - most important info first
+- Link to related reference items
+- Version history for deprecations/changes
+- Autogenerate from code when possible (JSDoc, Sphinx, rustdoc)

specify_cli/missions/documentation/templates/divio/tutorial-template.md

@@ -0,0 +1,146 @@
+---
+type: tutorial
+divio_category: learning-oriented
+target_audience: beginners
+purpose: hands-on-lesson
+outcome: learner-can-do-something
+---
+
+# Tutorial: {TUTORIAL_TITLE}
+
+> **Divio Type**: Tutorial (Learning-Oriented)
+> **Target Audience**: Beginners with little to no prior experience
+> **Purpose**: Guide learners through completing a meaningful task step-by-step
+> **Outcome**: By the end, learners will have accomplished something concrete
+
+## What You'll Learn
+
+In this tutorial, you will:
+- {Bullet point: First thing they'll accomplish}
+- {Bullet point: Second thing they'll accomplish}
+- {Bullet point: Third thing they'll accomplish}
+
+**Time to Complete**: Approximately {X} minutes
+
+## Before You Begin
+
+**Prerequisites**:
+- {Required knowledge or skill - keep minimal for beginners}
+- {Required tool or software with installation link}
+- {Required account or access}
+
+**What You'll Need**:
+- {Physical or digital resources needed}
+- {Optional: Link to starter code or files}
+
+## Step 1: {First Step Title}
+
+{Brief introduction to what this step accomplishes}
+
+**Do this**:
+
+```bash
+# Exact command to run
+{command-here}
+```
+
+**You should see**:
+
+```
+{Expected output}
+```
+
+✅ **Checkpoint**: {How learner knows this step succeeded}
+
+> **💡 Learning Note**: {Brief explanation of what just happened - keep it short}
+
+## Step 2: {Second Step Title}
+
+{Brief introduction to what this step builds on the previous one}
+
+**Do this**:
+
+```{language}
+# Code to write or run
+{code-here}
+```
+
+**Where to put it**: {Exact file location}
+
+✅ **Checkpoint**: {How learner knows this step succeeded}
+
+> **💡 Learning Note**: {Brief explanation}
+
+## Step 3: {Third Step Title}
+
+{Continue pattern - each step builds on the last}
+
+**Do this**:
+
+{Concrete action}
+
+✅ **Checkpoint**: {Verification}
+
+## Step 4: {Continue as needed...}
+
+{Maintain momentum - learners should see progress at every step}
+
+## What You've Accomplished
+
+Congratulations! You've completed {the task}. You now have:
+- ✅ {Concrete accomplishment #1}
+- ✅ {Concrete accomplishment #2}
+- ✅ {Concrete accomplishment #3}
+
+## Next Steps
+
+Now that you've learned {the basics}, you can:
+- **Learn More**: See [Explanation: {Topic}](../explanation/{link}) to understand why this works
+- **Solve Problems**: Check [How-To: {Task}](../how-to/{link}) for specific scenarios
+- **Reference**: Refer to [{API/CLI}](../reference/{link}) for all options
+
+## Troubleshooting
+
+**Problem**: {Common issue learners face}
+**Solution**: {Exact steps to fix it}
+
+**Problem**: {Another common issue}
+**Solution**: {Exact steps to fix it}
+
+---
+
+## Write the Docs Best Practices (Remove this section before publishing)
+
+**Tutorial Principles**:
+- ✅ Learning-oriented: Help learners gain competence
+- ✅ Allow learner to learn by doing
+- ✅ Get learners started quickly with early success
+- ✅ Make sure tutorial works reliably
+- ✅ Give immediate sense of achievement at each step
+- ✅ Ensure learner sees results immediately
+- ✅ Make tutorial repeatable and reliable
+- ✅ Focus on concrete steps, not abstract concepts
+- ✅ Provide minimum necessary explanation (link to Explanation docs)
+- ✅ Ignore options and alternatives (focus on the happy path)
+
+**Accessibility**:
+- ✅ Use proper heading hierarchy (H1 → H2 → H3, no skipping)
+- ✅ Provide alt text for all images and screenshots
+- ✅ Use clear, plain language (avoid jargon, or define it immediately)
+- ✅ Code blocks have language tags for syntax highlighting
+- ✅ Use descriptive link text (not "click here")
+
+**Inclusivity**:
+- ✅ Use diverse names in examples (not just "John", "Alice")
+- ✅ Gender-neutral language where possible
+- ✅ Avoid cultural assumptions (not everyone celebrates the same holidays)
+- ✅ Consider accessibility needs (keyboard navigation, screen readers)
+
+**Tutorial-Specific Guidelines**:
+- Start with a working example, not theory
+- Each step should produce a visible result
+- Don't explain everything - just enough to complete the task
+- Link to Explanation docs for deeper understanding
+- Test the tutorial with a beginner (does it work as written?)
+- Keep it short - 15-30 minutes maximum
+- Use consistent formatting for commands, code, and checkpoints

specify_cli/missions/documentation/templates/generators/jsdoc.json.template

@@ -0,0 +1,18 @@
+{
+  "source": {
+    "include": ["{source_dir}"],
+    "includePattern": ".+\\.(js|jsx|ts|tsx)$",
+    "excludePattern": "(^|\\/|\\\\)_"
+  },
+  "opts": {
+    "destination": "{output_dir}",
+    "recurse": true,
+    "readme": "README.md",
+    "template": "node_modules/{template}"
+  },
+  "plugins": ["plugins/markdown"],
+  "templates": {
+    "cleverLinks": false,
+    "monospaceLinks": false
+  }
+}

specify_cli/missions/documentation/templates/generators/sphinx-conf.py.template

@@ -0,0 +1,36 @@
+# Sphinx configuration for {project_name}
+# Auto-generated by spec-kitty documentation mission
+
+project = '{project_name}'
+author = '{author}'
+version = '{version}'
+release = version
+
+# Extensions
+extensions = [
+    'sphinx.ext.autodoc',      # Auto-generate docs from docstrings
+    'sphinx.ext.napoleon',     # Support Google/NumPy docstring styles
+    'sphinx.ext.viewcode',     # Add links to source code
+    'sphinx.ext.intersphinx',  # Link to other project docs
+]
+
+# Napoleon settings for Google-style docstrings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+
+# HTML output options
+html_theme = '{theme}'
+html_static_path = ['_static']
+
+# Autodoc options
+autodoc_default_options = {
+    'members': True,
+    'undoc-members': True,
+    'show-inheritance': True,
+}
+
+# Path setup
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))

specify_cli/missions/documentation/templates/plan-template.md

@@ -0,0 +1,269 @@
+# Implementation Plan: [DOCUMENTATION PROJECT]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/kitty-specs/[###-feature-name]/spec.md`
+
+**Note**: This template is filled in by the `/spec-kitty.plan` command. See mission command templates for execution workflow.
+
+## Summary
+
+[Extract from spec: documentation goals, Divio types selected, target audience, generators needed]
+
+## Technical Context
+
+**Documentation Framework**: [Sphinx | MkDocs | Docusaurus | Jekyll | Hugo | None (starting fresh) or NEEDS CLARIFICATION]
+**Languages Detected**: [Python, JavaScript, Rust, etc. - from codebase analysis]
+**Generator Tools**:
+- JSDoc for JavaScript/TypeScript API reference
+- Sphinx for Python API reference (autodoc + napoleon extensions)
+- rustdoc for Rust API reference
+
+**Output Format**: [HTML | Markdown | PDF or NEEDS CLARIFICATION]
+**Hosting Platform**: [Read the Docs | GitHub Pages | GitBook | Custom or NEEDS CLARIFICATION]
+**Build Commands**:
+- `sphinx-build -b html docs/ docs/_build/html/` (Python)
+- `npx jsdoc -c jsdoc.json` (JavaScript)
+- `cargo doc --no-deps` (Rust)
+
+**Theme**: [sphinx_rtd_theme | docdash | custom or NEEDS CLARIFICATION]
+**Accessibility Requirements**: WCAG 2.1 AA compliance (proper headings, alt text, contrast)
+
+## Project Structure
+
+### Documentation (this feature)
+
+```
+kitty-specs/[###-feature]/
+├── spec.md              # Documentation goals and user scenarios
+├── plan.md              # This file
+├── research.md          # Phase 0 output (gap analysis, framework research)
+├── data-model.md        # Phase 1 output (Divio type definitions)
+├── quickstart.md        # Phase 1 output (getting started guide)
+└── tasks.md             # Phase 2 output (/spec-kitty.tasks command)
+```
+
+### Documentation Files (repository root)
+
+```
+docs/
+├── index.md                    # Landing page with navigation
+├── tutorials/
+│   ├── getting-started.md     # Step-by-step for beginners
+│   └── [additional-tutorials].md
+├── how-to/
+│   ├── authentication.md      # Problem-solving guides
+│   ├── deployment.md
+│   └── [additional-guides].md
+├── reference/
+│   ├── api/                   # Generated API documentation
+│   │   ├── python/            # Sphinx autodoc output
+│   │   ├── javascript/        # JSDoc output
+│   │   └── rust/              # cargo doc output
+│   ├── cli.md                 # CLI reference (manual)
+│   └── config.md              # Configuration reference (manual)
+├── explanation/
+│   ├── architecture.md        # Design decisions and rationale
+│   ├── concepts.md            # Core concepts explained
+│   └── [additional-explanations].md
+├── conf.py                    # Sphinx configuration (if using Sphinx)
+├── jsdoc.json                 # JSDoc configuration (if using JSDoc)
+└── Cargo.toml                 # Rust docs config (if using rustdoc)
+```
+
+**Divio Type Organization**:
+- **Tutorials** (`tutorials/`): Learning-oriented, hands-on lessons for beginners
+- **How-To Guides** (`how-to/`): Goal-oriented recipes for specific tasks
+- **Reference** (`reference/`): Information-oriented technical specifications
+- **Explanation** (`explanation/`): Understanding-oriented concept discussions
+
+## Phase 0: Research
+
+### Objective
+
+[For gap-filling mode] Audit existing documentation, classify into Divio types, identify gaps and priorities.
+[For initial mode] Research documentation best practices, evaluate framework options, plan structure.
+
+### Research Tasks
+
+1. **Documentation Audit** (gap-filling mode only)
+   - Scan existing documentation directory for markdown files
+   - Parse frontmatter to classify Divio type
+   - Build coverage matrix: which features/areas have which documentation types
+   - Identify high-priority gaps (e.g., no tutorials for key workflows)
+   - Calculate coverage percentage
+
+2. **Generator Setup Research**
+   - Verify JSDoc installed: `npx jsdoc --version`
+   - Verify Sphinx installed: `sphinx-build --version`
+   - Verify rustdoc available: `cargo doc --help`
+   - Research configuration options for each applicable generator
+   - Plan integration strategy for generated + manual docs
+
+3. **Divio Template Research**
+   - Review Write the Docs guidance for each documentation type
+   - Identify examples of effective tutorials, how-tos, reference, and explanation docs
+   - Plan section structure appropriate for each type
+   - Consider target audience knowledge level
+
+4. **Framework Selection** (if starting fresh)
+   - Evaluate static site generators (Sphinx, MkDocs, Docusaurus, Jekyll, Hugo)
+   - Consider language ecosystem (Python project → Sphinx, JavaScript → Docusaurus)
+   - Review hosting options and deployment complexity
+   - Select theme that meets accessibility requirements
+
+### Research Output
+
+See [research.md](research.md) for detailed findings on:
+- Gap analysis results (coverage matrix, prioritized gaps)
+- Generator configuration research
+- Divio template examples
+- Framework selection rationale
+
+## Phase 1: Design
+
+### Objective
+
+Define documentation structure, configure generators, plan content outline for each Divio type.
+
+### Documentation Structure
+
+**Directory Layout**:
+```
+docs/
+├── index.md                    # Landing page
+├── tutorials/                  # Learning-oriented
+├── how-to/                     # Problem-solving
+├── reference/                  # Technical specs
+└── explanation/                # Understanding
+```
+
+**Navigation Strategy**:
+- Landing page links to all four Divio sections
+- Each section has clear purpose statement
+- Cross-links between types (tutorials → reference, how-tos → explanation)
+- Search functionality (if framework supports it)
+
+### Generator Configurations
+
+**Sphinx Configuration** (Python):
+```python
+# docs/conf.py
+project = '[PROJECT NAME]'
+extensions = [
+    'sphinx.ext.autodoc',      # Generate docs from docstrings
+    'sphinx.ext.napoleon',     # Support Google/NumPy docstring styles
+    'sphinx.ext.viewcode',     # Add source code links
+    'sphinx.ext.intersphinx',  # Link to other projects' docs
+]
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+```
+
+**JSDoc Configuration** (JavaScript):
+```json
+{
+  "source": {
+    "include": ["src/"],
+    "includePattern": ".+\\.js$",
+    "excludePattern": "(node_modules/|test/)"
+  },
+  "opts": {
+    "destination": "docs/reference/api/javascript",
+    "template": "node_modules/docdash",
+    "recurse": true
+  },
+  "plugins": ["plugins/markdown"]
+}
+```
+
+**rustdoc Configuration** (Rust):
+```toml
+# Cargo.toml
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--document-private-items"]
+```
+
+### Content Outline
+
+**Tutorials** (WP02 in tasks):
+- Getting Started (installation, first use, basic concepts)
+- [Additional tutorials based on key user journeys]
+
+**How-To Guides** (WP03 in tasks):
+- How to [solve specific problem 1]
+- How to [solve specific problem 2]
+- [Additional guides based on common tasks]
+
+**Reference** (WP04 in tasks):
+- API Reference (generated from code)
+- CLI Reference (manual)
+- Configuration Reference (manual)
+
+**Explanation** (WP05 in tasks):
+- Architecture Overview (design decisions, system structure)
+- Core Concepts (domain concepts explained)
+- [Additional explanations as needed]
+
+### Work Breakdown Preview
+
+Detailed work packages will be generated in Phase 2 (tasks.md). High-level packages:
+
+1. **WP01: Documentation Structure Setup** - Create directories, configure generators, set up build
+2. **WP02: Tutorial Documentation** - Write learning-oriented tutorials
+3. **WP03: How-To Guide Documentation** - Write problem-solving guides
+4. **WP04: Reference Documentation** - Generate API docs, write manual reference
+5. **WP05: Explanation Documentation** - Write understanding-oriented explanations
+6. **WP06: Quality Validation & Publishing** - Validate accessibility, build, deploy
+
+## Phase 2: Implementation
+
+**Note**: Phase 2 (work package generation) is handled by the `/spec-kitty.tasks` command.
+
+## Success Criteria Validation
+
+Validating against spec.md success criteria:
+
+- **SC-001** (findability): Structured navigation and search enable quick information access
+- **SC-002** (accessibility): Templates enforce proper headings, alt text, clear language
+- **SC-003** (API completeness): Generators ensure comprehensive API coverage
+- **SC-004** (task completion): Tutorials and how-tos enable users to succeed independently
+- **SC-005** (build quality): Documentation builds without errors or warnings
+
+## Constitution Check
+
+*GATE: Documentation mission requires adherence to Write the Docs best practices and Divio principles.*
+
+**Write the Docs Principles**:
+- Documentation as code (version controlled, reviewed, tested)
+- Accessible language (clear, plain, bias-free)
+- User-focused (written for audience, not developers)
+- Maintained (updated with code changes)
+
+**Divio Documentation System**:
+- Four distinct types with clear purposes
+- Learning-oriented tutorials
+- Goal-oriented how-tos
+- Information-oriented reference
+- Understanding-oriented explanations
+
+**Accessibility Standards**:
+- WCAG 2.1 AA compliance
+- Proper heading hierarchy
+- Alt text for all images
+- Sufficient color contrast
+- Keyboard navigation support
+
+## Risks & Dependencies
+
+**Risks**:
+- Documentation becomes outdated as code evolves
+- Generated documentation quality depends on code comment quality
+- Accessibility requirements may require manual auditing
+- Framework limitations may restrict functionality
+
+**Dependencies**:
+- Generator tools must be installed in development environment
+- Code must have comments/docstrings for reference generation
+- Hosting platform must be available and accessible
+- Build pipeline must support documentation generation