Configure Docs

/configure:docs

Check and configure code documentation standards and generators.

When to Use This Skill

Context

• Project root: !pwd
• Package files: !find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' \)
• Biome config: !find . -maxdepth 1 -name 'biome.json'
• TSDoc config: !find . -maxdepth 1 \( -name 'tsdoc.json' -o -name 'typedoc.json' \)
• Python config: !find . -maxdepth 1 \( -name 'pyproject.toml' -o -name 'ruff.toml' -o -name '.ruff.toml' \)
• Rust config: !find . -maxdepth 1 \( -name 'Cargo.toml' -o -name 'clippy.toml' \)
• Pre-commit: !find . -maxdepth 1 -name '.pre-commit-config.yaml'
• Doc generators: !find . -maxdepth 1 \( -name 'mkdocs.yml' -o -name 'docusaurus.config.*' \)
• Docs directory: !find . -maxdepth 1 -type d -name 'docs'

Parameters

Parse from command arguments:

• --check-only: Report compliance status without modifications (CI/CD mode)
• --fix: Apply fixes automatically without prompting
• --level <minimal|standard|strict>: Documentation enforcement level (default: standard)
• --type <typescript|javascript|python|rust>: Override language detection
• --generator <typedoc|sphinx|mkdocs|rustdoc>: Override documentation generator detection

Enforcement Levels:

• minimal: Syntax validation only (valid doc comments)
• standard: Public API documentation required (recommended)
• strict: All items documented, including private

Generator Auto-Detection:

Execution

Execute this documentation standards configuration check:

Step 1: Detect project language

Identify language(s) from file structure:

For multi-language projects, configure each detected language. Allow --type override to focus on one.

Step 2: Analyze current documentation state

For each detected language, check existing configuration:

TypeScript/JavaScript:

• [ ] tsdoc.json exists (TypeScript)
• [ ] Biome configured with organize imports
• [ ] TypeDoc or API Extractor configured for documentation generation

Python:

• [ ] pyproject.toml has [tool.ruff.lint.pydocstyle] section
• [ ] Convention specified (google, numpy, pep257)
• [ ] D rules enabled in ruff lint select

Rust:

• [ ] Cargo.toml has [lints.rust] section
• [ ] missing_docs lint configured
• [ ] [lints.rustdoc] section for rustdoc-specific lints

Step 3: Generate compliance report

Print a formatted compliance report:

Documentation Standards Compliance Report
=========================================
Project: [name]
Languages: [detected languages]
Enforcement Level: [minimal|standard|strict]

Linting Standards:
  TypeScript/JavaScript:
    tsdoc.json              [PASS | MISSING | N/A]
    TypeDoc configured      [PASS | MISSING | OUTDATED]
    API docs generated      [PASS | DISABLED]

  Python:
    ruff pydocstyle        [PASS | MISSING]
    convention             [google | not set]
    D rules enabled        [PASS | DISABLED]

  Rust:
    missing_docs lint      [PASS | DISABLED]
    rustdoc lints          [PASS | PARTIAL]

Documentation Generator:
  Generator type         [typedoc|mkdocs|sphinx|rustdoc]  [DETECTED | SUGGESTED]
  Config file            [config path]                     [EXISTS | MISSING]
  Build script           [command]                         [EXISTS | MISSING]
  Output directory       [docs/|site/|target/doc/]         [EXISTS | NOT BUILT]

Overall: [X issues found]

Next Steps:
  - Run `[build command]` to generate documentation locally
  - Run `/configure:github-pages` to set up deployment

If --check-only, stop here.

Step 4: Configure documentation standards (if --fix or user confirms)

Apply configuration based on detected language. Use templates from REFERENCE.md:

TypeScript Configuration

1. Create tsdoc.json with schema reference 2. Install TypeDoc: npm install --save-dev typedoc 3. Create typedoc.json with entry points and output directory

Python Configuration

1. Update pyproject.toml with [tool.ruff.lint.pydocstyle] section 2. Set convention to google (or numpy for scientific projects) 3. Configure level-specific rules (minimal: D1 only, standard: D with convention, strict: all D rules)

Rust Configuration

1. Update Cargo.toml with [lints.rust] section 2. Set missing_docs = "warn" (standard) or "deny" (strict) 3. Add [lints.rustdoc] section for broken link detection

Step 5: Configure documentation tests

Create tests to validate documentation compliance:

1. TypeScript/JavaScript: Add docs:check script running typedoc --emit none 2. Python: Add test file running ruff check --select D on source 3. Rust: Add cargo doc --no-deps and cargo clippy -- -W missing_docs to CI

Use test templates from REFERENCE.md.

Step 6: Set up documentation generator

Auto-detect or configure the documentation site generator:

1. Check for existing generator configs (use existing if found) 2. If --generator provided, use specified generator 3. Otherwise, match to detected project type 4. Create config file and add build scripts

Use generator templates from REFERENCE.md.

Step 7: Add pre-commit integration

If .pre-commit-config.yaml exists, add documentation hooks for the detected language. Use hook templates from REFERENCE.md.

Step 8: Update standards tracking

Update .project-standards.yaml:

standards_version: "2025.1"
project_type: "[detected]"
last_configured: "[timestamp]"
components:
  docs: "2025.1"
  docs_level: "[minimal|standard|strict]"
  docs_languages: ["typescript", "python", "rust"]

For detailed configuration templates, see REFERENCE.md.

Output

Provide: 1. Compliance report with per-language status 2. List of changes made (if --fix) or proposed (if interactive) 3. Instructions for running documentation tests 4. Next steps for improving coverage

Agentic Optimizations

See Also

• /configure:github-pages - Set up GitHub Pages deployment
• /configure:all - Run all compliance checks
• /configure:status - Quick compliance overview
• /configure:pre-commit - Pre-commit hook configuration
• biome-tooling skill for TypeScript/JavaScript
• ruff-linting skill for Python
• rust-development skill for Rust

Documentation Standards Reference

Configuration templates for documentation linting, generators, and tests.

TypeScript Configuration

tsdoc.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json"
}

TypeDoc Installation

npm install --save-dev typedoc
# or
bun add --dev typedoc

typedoc.json

{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["./src"],
  "entryPointStrategy": "expand",
  "out": "docs/api",
  "name": "PROJECT_NAME",
  "includeVersion": true,
  "readme": "README.md",
  "plugin": ["typedoc-plugin-markdown"]
}

Package.json Scripts

{
  "scripts": {
    "docs:build": "typedoc",
    "docs:check": "typedoc --emit none",
    "docs:serve": "npx serve docs"
  }
}

Documentation Test (tests/docs.test.ts)

import { execSync } from 'child_process';
import { describe, it, expect } from 'vitest';

describe('Documentation Compliance', () => {
  it('should generate API documentation without errors', () => {
    expect(() => {
      execSync('npm run docs:check', { stdio: 'pipe' });
    }).not.toThrow();
  });
});

Python Configuration

Ruff Pydocstyle (pyproject.toml)

[tool.ruff.lint]
select = [
    "E",    # pycodestyle errors
    "F",    # pyflakes
    "D",    # pydocstyle
]

[tool.ruff.lint.pydocstyle]
convention = "google"  # or "numpy" for scientific projects

Level-specific configuration:

MkDocs Installation

uv add --group docs mkdocs mkdocs-material mkdocstrings[python]

mkdocs.yml

site_name: PROJECT_NAME
site_description: Project description
repo_url: https://github.com/OWNER/REPO

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - search.suggest

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          options:
            show_source: true
            show_root_heading: true

nav:
  - Home: index.md
  - API Reference: api/

Sphinx Installation (Alternative)

uv add --group docs sphinx sphinx-rtd-theme sphinx-autodoc-typehints myst-parser

docs/conf.py

project = 'PROJECT_NAME'
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx_autodoc_typehints',
    'myst_parser',
]
html_theme = 'sphinx_rtd_theme'

Documentation Test (tests/test_docs.py)

"""Documentation compliance tests."""
import subprocess
import pytest


def test_pydocstyle_compliance():
    """Verify all modules have proper docstrings."""
    result = subprocess.run(
        ["ruff", "check", "--select", "D", "--output-format", "json", "src/"],
        capture_output=True,
        text=True,
    )
    assert result.returncode == 0, f"Documentation violations found:\n{result.stdout}"


def test_public_api_documented():
    """Verify public API has docstrings."""
    result = subprocess.run(
        ["ruff", "check", "--select", "D1", "src/"],
        capture_output=True,
        text=True,
    )
    assert result.returncode == 0, f"Missing public docstrings:\n{result.stdout}"

Rust Configuration

Cargo.toml Lints

[lints.rust]
missing_docs = "warn"  # standard level
# missing_docs = "deny"  # strict level

[lints.rustdoc]
broken_intra_doc_links = "warn"
missing_crate_level_docs = "warn"

For strict level, add clippy lint:

[lints.clippy]
missing_docs_in_private_items = "warn"

Cargo.toml Docs.rs Metadata

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

CI Check (.github/workflows/docs.yml)

name: Documentation Check
on: [push, pull_request]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check documentation
        run: |
          cargo doc --no-deps
          cargo clippy -- -W missing_docs

Pre-commit Integration

repos:
  # Python
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.2
    hooks:
      - id: ruff
        args: [--select, D, --fix]

  # Rust (if not already present)
  - repo: local
    hooks:
      - id: cargo-clippy-docs
        name: clippy docs
        entry: cargo clippy -- -W missing_docs
        language: system
        types: [rust]
        pass_filenames: false

Build Commands Summary