157 lines
4.2 KiB
Python
Executable File
157 lines
4.2 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
"""
|
|
Initialize the docs/ directory structure for document lifecycle management.
|
|
Creates all required directories and initial README.md.
|
|
"""
|
|
|
|
import os
|
|
import sys
|
|
from pathlib import Path
|
|
from datetime import datetime
|
|
|
|
|
|
DIRECTORY_STRUCTURE = {
|
|
'ai_docs': 'Reference materials for Claude Code: SDKs, API docs, repo context',
|
|
'specs': 'Feature and migration specifications',
|
|
'analysis': 'Investigation outputs: bug hunting, optimization, cleanup',
|
|
'plans': 'Implementation plans from specs, analysis, or ad-hoc tasks',
|
|
'templates': 'Reusable document templates',
|
|
'archive': 'Historical and completed documents'
|
|
}
|
|
|
|
|
|
README_TEMPLATE = """# Documentation Structure
|
|
|
|
This directory contains project documentation organized by purpose and lifecycle stage.
|
|
|
|
## Directory Structure
|
|
|
|
{directory_descriptions}
|
|
|
|
## Document Lifecycle
|
|
|
|
Documents follow a lifecycle managed through YAML frontmatter:
|
|
|
|
1. **Draft** → Document is being created
|
|
2. **Active** → Document is current and relevant
|
|
3. **Complete** → Work is done, kept for reference
|
|
4. **Archived** → Moved to archive/ when no longer relevant
|
|
|
|
## Metadata Requirements
|
|
|
|
All documents should include YAML frontmatter:
|
|
|
|
```yaml
|
|
---
|
|
title: Document Title
|
|
category: specs|analysis|plans|ai_docs|templates
|
|
status: draft|active|complete|archived
|
|
created: YYYY-MM-DD
|
|
last_updated: YYYY-MM-DD
|
|
tags: [tag1, tag2]
|
|
---
|
|
```
|
|
|
|
See INDEX.md for a complete list of all documents.
|
|
|
|
## Temporary Documents
|
|
|
|
Ephemeral/scratch documents should be created in `/tmp` or system temp directories,
|
|
NOT in this docs/ directory. The docs/ directory is for persistent documentation only.
|
|
|
|
---
|
|
Last updated: {timestamp}
|
|
"""
|
|
|
|
|
|
def create_directory_structure(base_path: Path) -> None:
|
|
"""Create the docs directory structure."""
|
|
docs_path = base_path / 'docs'
|
|
|
|
# Create main docs directory
|
|
docs_path.mkdir(exist_ok=True)
|
|
print(f"✅ Created: {docs_path}")
|
|
|
|
# Create category directories
|
|
for directory, description in DIRECTORY_STRUCTURE.items():
|
|
dir_path = docs_path / directory
|
|
dir_path.mkdir(exist_ok=True)
|
|
print(f"✅ Created: {dir_path}")
|
|
|
|
# Create .gitkeep for empty directories
|
|
gitkeep = dir_path / '.gitkeep'
|
|
if not any(dir_path.iterdir()):
|
|
gitkeep.touch()
|
|
|
|
|
|
def create_readme(base_path: Path) -> None:
|
|
"""Create the README.md file."""
|
|
docs_path = base_path / 'docs'
|
|
readme_path = docs_path / 'README.md'
|
|
|
|
# Format directory descriptions
|
|
descriptions = []
|
|
for directory, description in DIRECTORY_STRUCTURE.items():
|
|
descriptions.append(f"- **{directory}/** - {description}")
|
|
|
|
readme_content = README_TEMPLATE.format(
|
|
directory_descriptions='\n'.join(descriptions),
|
|
timestamp=datetime.now().strftime('%Y-%m-%d')
|
|
)
|
|
|
|
readme_path.write_text(readme_content)
|
|
print(f"✅ Created: {readme_path}")
|
|
|
|
|
|
def create_index(base_path: Path) -> None:
|
|
"""Create initial INDEX.md file."""
|
|
docs_path = base_path / 'docs'
|
|
index_path = docs_path / 'INDEX.md'
|
|
|
|
index_content = f"""# Documentation Index
|
|
|
|
Auto-generated index of all documents. Last updated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
|
|
|
|
Run `python scripts/index_docs.py` to regenerate this index.
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Total documents: 0
|
|
|
|
---
|
|
|
|
_No documents found. Add documents to the category directories and regenerate the index._
|
|
"""
|
|
|
|
index_path.write_text(index_content)
|
|
print(f"✅ Created: {index_path}")
|
|
|
|
|
|
def main():
|
|
"""Main entry point."""
|
|
if len(sys.argv) > 1:
|
|
base_path = Path(sys.argv[1]).resolve()
|
|
else:
|
|
base_path = Path.cwd()
|
|
|
|
print(f"Initializing docs structure at: {base_path}")
|
|
print()
|
|
|
|
create_directory_structure(base_path)
|
|
create_readme(base_path)
|
|
create_index(base_path)
|
|
|
|
print()
|
|
print("🎉 Documentation structure initialized successfully!")
|
|
print()
|
|
print("Next steps:")
|
|
print("1. Add documents to the category directories")
|
|
print("2. Run 'python scripts/index_docs.py' to update the index")
|
|
print("3. Run 'python scripts/archive_docs.py' periodically to maintain the archive")
|
|
|
|
|
|
if __name__ == '__main__':
|
|
main()
|