update-docs

# update-docs

Initialize or update project documentation following a standard format with overview, goals, milestones, and todos.

## Usage

```bash
# Initialize docs for a new project
update-docs --project myproject --mode init

# Update existing docs with recent changes
update-docs --project myproject --notes "Added user authentication, fixed login bug"

# Update and deploy
update-docs --project myproject --notes "Release v1.0" --deploy true
```

## Arguments

| Flag | Description | Default |
|------|-------------|---------|
| `--project` | Project name (directory name under projects_root) | Required |
| `--notes` | Recent changes to incorporate into docs | "" |
| `--mode` | "init" for new projects, "update" to preserve existing | "update" |
| `--deploy` | Deploy docs after updating (true/false) | "false" |

## Configuration

This tool uses `settings.yaml` for path configuration. Copy `defaults.yaml` to `settings.yaml` and customize:

```yaml
# Root directory containing your projects
projects_root: "~/PycharmProjects"

# Centralized docs location (e.g., Docusaurus project)
# If empty, docs are written to <project>/docs/ directly
docs_root: "~/PycharmProjects/project-docs"

# Structure within docs_root for project docs
# {project} is replaced with the project name (lowercased)
docs_structure: "docs/projects/{project}"

# Create symlinks from project/docs to centralized docs
create_symlinks: true

# Deploy configuration
deploy:
  enabled: true
  script: "scripts/build-public-docs.sh"
  url_pattern: "https://your-docs-site.com/{project}/"
```

### Default Behavior (no settings.yaml)

Without configuration:
- Projects are expected in `~/PycharmProjects/`
- Docs are written to `<project>/docs/` directory
- No symlinks created
- Deploy is disabled

### Centralized Docs Setup

For projects using a centralized docs system (like Docusaurus):

1. Set `docs_root` to your docs project path
2. Set `docs_structure` for the folder structure (e.g., `docs/projects/{project}`)
3. Enable `create_symlinks` to link project/docs to the centralized location
4. Configure deploy script and URL pattern

## Generated Files

The tool creates/updates four documentation files:

| File | Purpose |
|------|---------|
| `overview.md` | Project intro, features, quick start, architecture |
| `goals.md` | Prioritized goals with checkboxes and #high/#medium/#low tags |
| `milestones.md` | Project milestones organized as Active/Future/Completed |
| `todos.md` | Action items linked to milestones with @M1, @M2 tags |
| `updating-documentation.md` | Instructions for updating docs (auto-created) |

## How It Works

1. Reads project context from CLAUDE.md, README.md, and source files
2. Reads existing docs (if any) to preserve content in update mode
3. Uses AI to generate/update documentation following the standard format
4. Writes files to the configured docs location
5. Optionally creates symlinks and runs deploy script

## Tips

- Use `--mode init` only for new projects or to completely regenerate docs
- Use `--notes` to describe recent changes so the AI knows what to add
- Run regularly after significant changes to keep docs current
- The tool preserves completed items and milestone history in update mode