generating-documentation

Name: generating-documentation
Author: ancoleman

48installs59forks

How to install generating-documentation?

ancoleman/ai-design-components/generating-documentation

$npx -y skills add ancoleman/ai-design-components --skill generating-documentation

Installs into the current project.

Summary

Generate comprehensive technical documentation including API docs (OpenAPI/Swagger), code documentation (TypeDoc/Sphinx), documentation sites (Docusaurus/MkDocs), Architecture Decision Records (ADRs), and diagrams (Mermaid/PlantUML). Use when documenting APIs, libraries, systems

Files · 1

View on GitHub

SKILL.md

1	# Documentation Generation
2
3	Generate comprehensive technical documentation across multiple layers: API documentation, code documentation, documentation sites, architecture decisions, and system diagrams.
4
5	## When to Use This Skill
6
7	Use this skill when:
8
9	- Documenting REST or GraphQL APIs with OpenAPI specifications
10	- Creating code documentation for libraries (TypeScript, Python, Go, Rust)
11	- Building documentation sites for projects or products
12	- Recording architectural decisions (ADRs) for system design choices
13	- Generating diagrams to visualize system architecture or data flows
14	- Setting up automated documentation pipelines in CI/CD
15
16	## Documentation Layers Overview
17
18	Technical documentation operates at five distinct layers:
19
20	Layer 1: API Documentation - OpenAPI specs for REST/GraphQL APIs (Swagger UI, Redoc, Scalar)
21	Layer 2: Code Documentation - Generated from code comments (TypeDoc, Sphinx, godoc, rustdoc)
22	Layer 3: Documentation Sites - Comprehensive guides and tutorials (Docusaurus, MkDocs)
23	Layer 4: Architecture Decisions - ADRs using MADR template format
24	Layer 5: Diagrams - Visual architecture (Mermaid, PlantUML, D2)
25
26	See `references/api-documentation.md`, `references/code-documentation.md`, and `references/documentation-sites.md` for detailed guides.
27
28	## Quick Decision Framework
29
30	### Which Documentation Layer?
31
32	```
33	API for external consumers?
34	→ Layer 1: API Documentation (OpenAPI + Swagger UI/Redoc)
35
36	Code for maintainers?
37	→ Layer 2: Code Documentation (TypeDoc/Sphinx/godoc/rustdoc)
38
39	Comprehensive guides?
40	→ Layer 3: Documentation Site (Docusaurus/MkDocs)
41
42	Architectural decision?
43	→ Layer 4: ADR (MADR template)
44
45	Visual system design?
46	→ Layer 5: Diagrams (Mermaid/PlantUML/D2)
47	```
48
49	### Tool Selection Matrix
50
51	\| Need \| Primary Tool \| Best For \|
52	\|------\|-------------\|----------\|
53	\| Doc Site \| Docusaurus \| Feature-rich React sites \|
54	\| Doc Site \| MkDocs Material \| Simple Python docs \|
55	\| API Docs (Interactive) \| Swagger UI \| Testing \|
56	\| API Docs (Read-Only) \| Redoc \| Professional design \|
57	\| TypeScript \| TypeDoc \| All TS projects \|
58	\| Python \| Sphinx \| All Python projects \|
59	\| Go \| godoc \| Built-in \|
60	\| Rust \| rustdoc \| Built-in \|
61	\| Diagrams \| Mermaid \| All-purpose \|
62
63	## API Documentation Quick Start
64
65	Create OpenAPI specification:
66
67	```yaml
68	openapi: 3.1.0
69	info:
70	title: User API
71	version: 1.0.0
72
73	servers:
74	- url: https://api.example.com/v1
75
76	paths:
77	/users/{userId}:
78	get:
79	summary: Get a user
80	parameters:
81	- name: userId
82	in: path
83	required: true
84	schema:
85	type: string
86	responses:
87	'200':
88	description: Success
89	content:
90	application/json:
91	schema:
92	$ref: '#/components/schemas/User'
93
94	components:
95	schemas:
96	User:
97	type: object
98	required: [id, email, name]
99	properties:
100	id:
101	type: string
102	email:
103	type: string
104	format: email
105	name:
106	type: string
107
108	securitySchemes:
109	bearerAuth:
110	type: http
111	scheme: bearer
112	bearerFormat: JWT
113
114	security:
115	- bearerAuth: []
116	```
117
118	Render with Swagger UI, Redoc, or Scalar. See `references/api-documentation.md` for complete examples and `templates/openapi-template.yaml` for starter template.
119
120	## Code Documentation Quick Start
121
122	### TypeScript
123
124	```typescript
125	/**
126	* Calculate the sum of two numbers.
127	*
128	* @param a - The first number
129	* @param b - The second number
130	* @returns The sum of a and b
131	*
132	* @example
133	* ```typescript
134	* const result = add(2, 3);
135	* console.log(result); // 5
136	* ```
137	*/
138	export function add(a: number, b: number): number {
139	return a + b;
140	}
141	```
142
143	Generate docs:
144
145	```bash
146	npm install -D typedoc
147	npx typedoc --entryPoints src/index.ts --out docs
148	```
149
150	### Python
151
152	```python
153	def calculate_total(items: list[dict], tax_rate: float = 0.0) -> float:
154	"""Calculate the total price including tax.
155
156	Args:
157	items: List of items with 'price' and 'quantity' keys.
158	tax_rate: Tax rate as decimal (e.g., 0.1 for 10%).
159
160	Returns:
161	Total price including tax.
162
163	Example:
164	>>> items = [{'price': 10, 'quantity': 2}]
165	>>> calculate_total(items, tax_rate=0.1)
166	22.0
167	"""
168	subtotal = sum(item['price'] * item['quantity'] for item in items)
169	return subtotal * (1 + tax_rate)
170	```
171
172	Generate docs:
173
174	```bash
175	pip install sphinx sphinx-rtd-theme
176	sphinx-quickstart docs
177	cd docs && make html
178	```
179
180	See `references/code-documentation.md` for Go and Rust examples.
181
182	## Documentation Site Quick S

People who liked this also viewed

6 picks

Type

generating-documentation

48installs59forks

View on GitHub

How to install generating-documentation?

ancoleman/ai-design-components/generating-documentation

$npx -y skills add ancoleman/ai-design-components --skill generating-documentation

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Documentation Generation
2
3	Generate comprehensive technical documentation across multiple layers: API documentation, code documentation, documentation sites, architecture decisions, and system diagrams.
4
5	## When to Use This Skill
6
7	Use this skill when:
8
9	- Documenting REST or GraphQL APIs with OpenAPI specifications
10	- Creating code documentation for libraries (TypeScript, Python, Go, Rust)
11	- Building documentation sites for projects or products
12	- Recording architectural decisions (ADRs) for system design choices
13	- Generating diagrams to visualize system architecture or data flows
14	- Setting up automated documentation pipelines in CI/CD
15
16	## Documentation Layers Overview
17
18	Technical documentation operates at five distinct layers:
19
20	Layer 1: API Documentation - OpenAPI specs for REST/GraphQL APIs (Swagger UI, Redoc, Scalar)
21	Layer 2: Code Documentation - Generated from code comments (TypeDoc, Sphinx, godoc, rustdoc)
22	Layer 3: Documentation Sites - Comprehensive guides and tutorials (Docusaurus, MkDocs)
23	Layer 4: Architecture Decisions - ADRs using MADR template format
24	Layer 5: Diagrams - Visual architecture (Mermaid, PlantUML, D2)
25
26	See `references/api-documentation.md`, `references/code-documentation.md`, and `references/documentation-sites.md` for detailed guides.
27
28	## Quick Decision Framework
29
30	### Which Documentation Layer?
31
32	```
33	API for external consumers?
34	→ Layer 1: API Documentation (OpenAPI + Swagger UI/Redoc)
35
36	Code for maintainers?
37	→ Layer 2: Code Documentation (TypeDoc/Sphinx/godoc/rustdoc)
38
39	Comprehensive guides?
40	→ Layer 3: Documentation Site (Docusaurus/MkDocs)
41
42	Architectural decision?
43	→ Layer 4: ADR (MADR template)
44
45	Visual system design?
46	→ Layer 5: Diagrams (Mermaid/PlantUML/D2)
47	```
48
49	### Tool Selection Matrix
50
51	\| Need \| Primary Tool \| Best For \|
52	\|------\|-------------\|----------\|
53	\| Doc Site \| Docusaurus \| Feature-rich React sites \|
54	\| Doc Site \| MkDocs Material \| Simple Python docs \|
55	\| API Docs (Interactive) \| Swagger UI \| Testing \|
56	\| API Docs (Read-Only) \| Redoc \| Professional design \|
57	\| TypeScript \| TypeDoc \| All TS projects \|
58	\| Python \| Sphinx \| All Python projects \|
59	\| Go \| godoc \| Built-in \|
60	\| Rust \| rustdoc \| Built-in \|
61	\| Diagrams \| Mermaid \| All-purpose \|
62
63	## API Documentation Quick Start
64
65	Create OpenAPI specification:
66
67	```yaml
68	openapi: 3.1.0
69	info:
70	title: User API
71	version: 1.0.0
72
73	servers:
74	- url: https://api.example.com/v1
75
76	paths:
77	/users/{userId}:
78	get:
79	summary: Get a user
80	parameters:
81	- name: userId
82	in: path
83	required: true
84	schema:
85	type: string
86	responses:
87	'200':
88	description: Success
89	content:
90	application/json:
91	schema:
92	$ref: '#/components/schemas/User'
93
94	components:
95	schemas:
96	User:
97	type: object
98	required: [id, email, name]
99	properties:
100	id:
101	type: string
102	email:
103	type: string
104	format: email
105	name:
106	type: string
107
108	securitySchemes:
109	bearerAuth:
110	type: http
111	scheme: bearer
112	bearerFormat: JWT
113
114	security:
115	- bearerAuth: []
116	```
117
118	Render with Swagger UI, Redoc, or Scalar. See `references/api-documentation.md` for complete examples and `templates/openapi-template.yaml` for starter template.
119
120	## Code Documentation Quick Start
121
122	### TypeScript
123
124	```typescript
125	/**
126	* Calculate the sum of two numbers.
127	*
128	* @param a - The first number
129	* @param b - The second number
130	* @returns The sum of a and b
131	*
132	* @example
133	* ```typescript
134	* const result = add(2, 3);
135	* console.log(result); // 5
136	* ```
137	*/
138	export function add(a: number, b: number): number {
139	return a + b;
140	}
141	```
142
143	Generate docs:
144
145	```bash
146	npm install -D typedoc
147	npx typedoc --entryPoints src/index.ts --out docs
148	```
149
150	### Python
151
152	```python
153	def calculate_total(items: list[dict], tax_rate: float = 0.0) -> float:
154	"""Calculate the total price including tax.
155
156	Args:
157	items: List of items with 'price' and 'quantity' keys.
158	tax_rate: Tax rate as decimal (e.g., 0.1 for 10%).
159
160	Returns:
161	Total price including tax.
162
163	Example:
164	>>> items = [{'price': 10, 'quantity': 2}]
165	>>> calculate_total(items, tax_rate=0.1)
166	22.0
167	"""
168	subtotal = sum(item['price'] * item['quantity'] for item in items)
169	return subtotal * (1 + tax_rate)
170	```
171
172	Generate docs:
173
174	```bash
175	pip install sphinx sphinx-rtd-theme
176	sphinx-quickstart docs
177	cd docs && make html
178	```
179
180	See `references/code-documentation.md` for Go and Rust examples.
181
182	## Documentation Site Quick S

People who liked this also viewed

6 picks

Type