Metadata-Version: 2.4
Name: diary-docs
Version: 0.1.0
Summary: Scaffold DIARY documentation structure with MkDocs and Backstage support
Author-email: bakhija senakmoiky <senakmoiky@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/bakhija/diary-docs
Project-URL: Repository, https://github.com/bakhija/diary-docs
Keywords: documentation,mkdocs,backstage,techdocs,scaffolder
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Requires-Dist: inquirerpy>=0.3.4
Dynamic: license-file

# diary-docs — DIARY Documentation Scaffolder

A CLI tool that scaffolds a DIARY documentation structure with MkDocs and Backstage support, indexes your codebase for knowledge retrieval, and keeps docs in sync with code changes.

## Installation

```bash
pip install diary-docs
```

For development:

```bash
pip install -e .
```

## Commands

### `diary-docs init`

Initialize a new DIARY documentation project in the current directory.

```bash
diary-docs init
```

The tool prompts for a project name, then creates:

```
docs/
├── index.md
├── objectives.md
├── structure/
│   └── index.md
├── techdocs/
│   ├── index.md
│   ├── architecture.md
│   ├── api-contracts.md
│   ├── deployment.md
│   ├── adr.md
│   └── development-guide.md
├── product/
│   ├── index.md
│   ├── user-guide.md
│   └── modules.md
├── ops-governance/
│   ├── index.md
│   ├── runbooks.md
│   └── security.md
└── knowledge-base/
    ├── index.md
    ├── faq.md
    └── troubleshooting.md
mkdocs.yml
catalog-info.yaml
```

It also generates an AI agent skill file for content generation.

**Options:**

| Flag | Description |
|------|-------------|
| `-f`, `--force` | Overwrite existing files |
| `--help` | Show help for this command |

If files already exist, they are skipped (unless `--force` is used).

---

### `diary-docs index`

Index the workspace codebase for knowledge retrieval. Extracts symbols, files, and relationships into a SQLite database.

```bash
diary-docs index
```

**Options:**

| Flag | Description |
|------|-------------|
| `-r`, `--report` | Generate a documentation coverage report after indexing |
| `--db-path PATH` | Custom database path (default: `docs/.index/knowledge.db`) |
| `--help` | Show help for this command |

The index powers the `diary-docs generate-content` skill, allowing AI agents to query the codebase structure without manually scanning files.

---

### `diary-docs sync`

Synchronize documentation with detected code changes. Compares the current workspace against git history to find outdated AIMB (AI-Managed) blocks in markdown files.

```bash
# Preview changes without applying
diary-docs sync --dry-run

# Apply all detected changes
diary-docs sync --force
```

**Options:**

| Flag | Description |
|------|-------------|
| `-n`, `--dry-run` | Preview changes as JSON without applying |
| `-b`, `--branch NAME` | Override branch detection |
| `-f`, `--force` | Skip conflict warnings |
| `-o`, `--output FILE` | Write JSON report to file |
| `--help` | Show help for this command |

**Dry-run output** is a JSON SyncReport showing code changes, affected docs, confidence scores, and any conflicts.

---

### Global Options

| Flag | Description |
|------|-------------|
| `--version` | Show version |
| `--help` | Show top-level help |

## AI Agent Skills

`diary-docs init` generates two slash commands for AI coding agents (Claude Code, OpenCode). The skill files are placed in `.claude/commands/` or `.opencode/commands/` (you choose during init).

### `/diary-generate-content`

Analyzes the workspace codebase via the pre-built index and generates enterprise-grade documentation content for every DIARY file.

```bash
# In Claude Code or OpenCode:
/diary-generate-content
```

The skill follows a multi-step workflow:
1. Reads existing docs structure
2. Queries the knowledge index (`docs/.index/knowledge.db`)
3. Asks clarifying questions for missing context
4. Generates content with Mermaid diagrams, tables, and use cases
5. Writes all `docs/` files with AIMB (AI-Managed Block) wrappers

Output covers: architecture overview, API contracts, deployment flow, ADR log, user guide, runbooks, security compliance, FAQ, and troubleshooting.

---

### `/diary-sync`

Synchronizes documentation with detected code changes. Compares the current git state against history to find outdated AIMB blocks.

```bash
# In Claude Code or OpenCode:
/diary-sync
```

The skill follows a structured workflow:
1. Verifies git state and runs `diary-docs sync --dry-run`
2. Parses the SyncReport JSON for changes and conflicts
3. Processes each high-confidence change by updating relevant AIMB blocks
4. Flags conflicts for manual review (never auto-resolves)
5. Finalizes with `diary-docs sync --force`
6. Prints a summary of all processed files

**Prerequisites:** All code changes must be committed to git before running `/diary-sync`.

---

## What It Generates

| File/Folder | Description |
|-------------|-------------|
| `docs/` | Main documentation folder |
| `docs/index.md` | Root documentation index |
| `docs/objectives.md` | Project objectives and goals |
| `docs/structure/index.md` | Writing guidelines and conventions |
| `docs/techdocs/` | Technical documentation section |
| `docs/techdocs/architecture.md` | System architecture overview |
| `docs/techdocs/api-contracts.md` | API endpoint specifications |
| `docs/techdocs/deployment.md` | Deployment flow and environments |
| `docs/techdocs/adr.md` | Architecture Decision Records |
| `docs/techdocs/development-guide.md` | Local development setup guide |
| `docs/product/` | Product documentation section |
| `docs/product/user-guide.md` | End-user guide with use cases |
| `docs/product/modules.md` | Module/component reference |
| `docs/ops-governance/` | Operations & governance section |
| `docs/ops-governance/runbooks.md` | Operational runbooks |
| `docs/ops-governance/security.md` | Security compliance docs |
| `docs/knowledge-base/` | Knowledge base section |
| `docs/knowledge-base/faq.md` | Frequently asked questions |
| `docs/knowledge-base/troubleshooting.md` | Troubleshooting guide |
| `mkdocs.yml` | MkDocs configuration with TechDocs Core plugin |
| `catalog-info.yaml` | Backstage component registration file |

## Development

```bash
pytest tests/ -v
```
