qwiki-builder 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- qwiki_builder-1.0.0/LICENSE +21 -0
- qwiki_builder-1.0.0/PKG-INFO +406 -0
- qwiki_builder-1.0.0/README.md +377 -0
- qwiki_builder-1.0.0/pyproject.toml +58 -0
- qwiki_builder-1.0.0/qwiki_builder.egg-info/PKG-INFO +406 -0
- qwiki_builder-1.0.0/qwiki_builder.egg-info/SOURCES.txt +55 -0
- qwiki_builder-1.0.0/qwiki_builder.egg-info/dependency_links.txt +1 -0
- qwiki_builder-1.0.0/qwiki_builder.egg-info/entry_points.txt +3 -0
- qwiki_builder-1.0.0/qwiki_builder.egg-info/top_level.txt +1 -0
- qwiki_builder-1.0.0/qwikibuilder/__init__.py +25 -0
- qwiki_builder-1.0.0/qwikibuilder/__main__.py +9 -0
- qwiki_builder-1.0.0/qwikibuilder/assets.py +201 -0
- qwiki_builder-1.0.0/qwikibuilder/cli.py +890 -0
- qwiki_builder-1.0.0/qwikibuilder/client.py +517 -0
- qwiki_builder-1.0.0/qwikibuilder/config.py +172 -0
- qwiki_builder-1.0.0/qwikibuilder/dedup.py +106 -0
- qwiki_builder-1.0.0/qwikibuilder/links.py +173 -0
- qwiki_builder-1.0.0/qwikibuilder/manifest.py +330 -0
- qwiki_builder-1.0.0/qwikibuilder/publisher.py +322 -0
- qwiki_builder-1.0.0/qwikibuilder/sync.py +442 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/equipment-manual/docs/01-specifications/01-system-overview.md +23 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/equipment-manual/docs/01-specifications/02-technical-data.md +20 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/equipment-manual/docs/02-safety/01-safety-precautions.md +23 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/equipment-manual/docs/03-operation/01-startup-and-controls.md +20 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/equipment-manual/docs/04-maintenance/01-preventive-maintenance.md +21 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/equipment-manual/qwiki-project.json +70 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/quality-manual/docs/01-scope-policy/01-quality-policy-and-scope.md +27 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/quality-manual/docs/02-leadership/01-leadership-and-roles.md +24 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/quality-manual/docs/03-processes/01-core-operations-process.md +27 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/quality-manual/docs/04-improvement/01-audit-and-continuous-improvement.md +22 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/quality-manual/qwiki-project.json +63 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/safety-handbook/docs/01-policy/01-ehs-commitment-and-rules.md +11 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/safety-handbook/docs/02-emergency/01-emergency-procedures.md +23 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/safety-handbook/docs/03-hazards-ppe/01-hazard-control-and-ppe.md +12 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/safety-handbook/docs/04-incident-reporting/01-incident-investigation.md +13 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/safety-handbook/qwiki-project.json +63 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/sop/docs/01-framework/01-sop-management-framework.md +26 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/sop/docs/02-procedures/01-standard-change-control.md +23 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/sop/docs/02-procedures/02-routine-production-cycle.md +16 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/sop/qwiki-project.json +46 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/user-guide/docs/00-getting-started/01-introduction.md +30 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/user-guide/docs/00-getting-started/02-quick-start.md +34 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/user-guide/docs/01-core-features/01-dashboard-and-navigation.md +17 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/user-guide/docs/01-core-features/02-managing-resources.md +22 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/user-guide/docs/02-troubleshooting/01-faq-and-support.md +14 -0
- qwiki_builder-1.0.0/qwikibuilder/templates/user-guide/qwiki-project.json +65 -0
- qwiki_builder-1.0.0/qwikibuilder/validator.py +270 -0
- qwiki_builder-1.0.0/setup.cfg +4 -0
- qwiki_builder-1.0.0/tests/test_assets.py +94 -0
- qwiki_builder-1.0.0/tests/test_cli.py +31 -0
- qwiki_builder-1.0.0/tests/test_client.py +128 -0
- qwiki_builder-1.0.0/tests/test_config.py +77 -0
- qwiki_builder-1.0.0/tests/test_links.py +66 -0
- qwiki_builder-1.0.0/tests/test_manifest.py +80 -0
- qwiki_builder-1.0.0/tests/test_sync.py +188 -0
- qwiki_builder-1.0.0/tests/test_themes.py +140 -0
- qwiki_builder-1.0.0/tests/test_validator.py +127 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Qwiki Community & Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,406 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: qwiki-builder
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Generalised CLI, Python engine, and AI agent workflow to create, manage, and remotely deploy online documentation suites, equipment manuals, user guides, quality manuals, and safety handbooks to Standalone Qwiki.
|
|
5
|
+
Author-email: Franco Benedetti <franco@growthhq.net>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/FrancoBenedetti/qwiki-builder
|
|
8
|
+
Project-URL: Repository, https://github.com/FrancoBenedetti/qwiki-builder
|
|
9
|
+
Keywords: qwiki,documentation,user-guide,manual,safety-handbook,quality-manual,sop,automation,publishing,ai-agent
|
|
10
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Intended Audience :: Information Technology
|
|
14
|
+
Classifier: Intended Audience :: Manufacturing
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Topic :: Documentation
|
|
24
|
+
Classifier: Topic :: Software Development :: Documentation
|
|
25
|
+
Requires-Python: >=3.8
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
License-File: LICENSE
|
|
28
|
+
Dynamic: license-file
|
|
29
|
+
|
|
30
|
+
# ๐ Qwiki Builder
|
|
31
|
+
|
|
32
|
+
> **Generalised CLI, Python Engine, and AI Agent Workflow for Automated Creation and Remote Deployment of Online Documentation Suites to [Standalone Qwiki](https://github.com/qwiki-wiki/standalone-qwiki).**
|
|
33
|
+
|
|
34
|
+
[](https://www.python.org/)
|
|
35
|
+
[](LICENSE)
|
|
36
|
+
[]()
|
|
37
|
+
[](https://github.com/qwiki-wiki/standalone-qwiki)
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## ๐ Overview
|
|
42
|
+
|
|
43
|
+
**Qwiki Builder** turns raw documents, specifications, user guides, standard operating procedures, and engineering notes into production-ready online documentation portals hosted on **Standalone Qwiki**.
|
|
44
|
+
|
|
45
|
+
This framework was born from the production rollout of the **MoBioplus Agricultural & GeoCRM User Documentation** (`wiki.mobioplus.co.za/user-docs`), where 24 canonical technical and operational chapters were systematically published and synced via Qwiki's headless publishing REST API.
|
|
46
|
+
|
|
47
|
+
**Qwiki Builder generalises this entire workflow into an open-source toolchain** that can be used directly from the command line, imported as a Python library, incorporated into CI/CD pipelines, or driven autonomously by AI Agents (Antigravity, Claude, Cursor, Copilot, Gemini).
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## ๐ Supported Documentation Suites & Templates
|
|
52
|
+
|
|
53
|
+
Qwiki Builder ships with production-grade templates tailored to standard business and industrial documentation needs:
|
|
54
|
+
|
|
55
|
+
| Template Preset | Use Case | Included Default Sections |
|
|
56
|
+
| :--- | :--- | :--- |
|
|
57
|
+
| **`user-guide`** | SaaS, Mobile Apps, Enterprise Platforms | Welcome, Quick Start, Dashboard, Resource Management, FAQ |
|
|
58
|
+
| **`equipment-manual`** | Machinery, Hardware, Medical, Electronics | Architecture, Technical Data, Safety (LOTO), Operation, Maintenance |
|
|
59
|
+
| **`quality-manual`** | ISO 9001, QA/QC Systems, Compliance | Quality Policy, Leadership Roles, Core Processes, Auditing & CAPA |
|
|
60
|
+
| **`safety-handbook`** | EHS, OSHA, Factory / Field Workplaces | Golden Rules, Emergency Evacuation, Mandatory PPE, Incident Reporting |
|
|
61
|
+
| **`sop`** | Standard Operating Procedures Library | SOP Authoring Standard, Numbering, Change Control, Handover Protocols |
|
|
62
|
+
| **`blank`** | Custom / Bespoke Portals | Clean foundation for custom information architectures |
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## โจ Key Features
|
|
67
|
+
|
|
68
|
+
- **Zero External Dependencies**: Engineered entirely on the Python Standard Library (`urllib`, `json`, `argparse`, `pathlib`, `re`). Zero `pip` headaches or dependency bloat.
|
|
69
|
+
- **Pre-Built Industry Templates**: Scaffold rich, compliant manual structures in seconds with `qwiki-builder init`.
|
|
70
|
+
- **Pre-Flight Validation Engine**: Validates missing files, broken image paths, duplicate slugs, undeclared categories, and Mermaid diagram formatting *before* touching the remote server.
|
|
71
|
+
- **Automatic Asset Upload & URL Rewriting**: Recursively uploads screenshots and diagrams (`.png`, `.jpg`, `.webp`, `.svg`, `.gif`) via Qwiki's multipart API, caching uploads and automatically rewriting relative Markdown paths to remote URLs.
|
|
72
|
+
- **In-Place Updates & Stable Slugs**: Preserves document slugs, internal cross-links, and cryptographic share keys across continuous edits.
|
|
73
|
+
- **Automated Deduplication & Clean Reload**: Intelligently identifies and deletes accidental remote chapter duplicates and suffixed slugs (`doc-1`, `doc-2`), or performs a pristine purge-and-reload.
|
|
74
|
+
- **Multi-Profile Configuration**: Store and switch between multiple remote wiki environments (`production`, `staging`, `safety-wiki`) globally in `~/.config/qwiki-builder/config.json`.
|
|
75
|
+
- **First-Class AI Agent Support**: Comes pre-packaged with [`AGENTS.md`](AGENTS.md) and an Antigravity Skill (`skills/qwiki-doc-builder/SKILL.md`) for autonomous agents to research, author, validate, and deploy complete manuals.
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## โก Quick Start
|
|
80
|
+
|
|
81
|
+
### 1. Installation
|
|
82
|
+
|
|
83
|
+
You can install Qwiki Builder via `pip`, run it directly from checkout, or install it system-wide:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
# Clone the repository
|
|
87
|
+
git clone https://github.com/FrancoBenedetti/qwiki-builder.git
|
|
88
|
+
cd qwiki-builder
|
|
89
|
+
|
|
90
|
+
# Option A: Install into your active Python environment
|
|
91
|
+
pip install .
|
|
92
|
+
|
|
93
|
+
# Option B: Run directly from checkout
|
|
94
|
+
./bin/qwiki-builder --help
|
|
95
|
+
|
|
96
|
+
# Option C: Global system install (links CLI to ~/.local/bin and installs Agent Skill)
|
|
97
|
+
./scripts/install-global.sh
|
|
98
|
+
|
|
99
|
+
# Option D: Install directly from GitHub
|
|
100
|
+
pip install git+https://github.com/FrancoBenedetti/qwiki-builder.git
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### 2. Scaffold a New Manual Project
|
|
104
|
+
|
|
105
|
+
Create a new directory and scaffold your desired template:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
# Scaffold an Industrial Equipment Manual
|
|
109
|
+
qwiki-builder init my-titan-manual --template equipment-manual --name "Titan 5000 Operator Manual"
|
|
110
|
+
|
|
111
|
+
cd my-titan-manual
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
The resulting directory structure:
|
|
115
|
+
|
|
116
|
+
```
|
|
117
|
+
my-titan-manual/
|
|
118
|
+
โโโ qwiki-project.json # Project manifest & category hierarchy
|
|
119
|
+
โโโ README.md # Project quick reference
|
|
120
|
+
โโโ docs/
|
|
121
|
+
โโโ assets/ # Screenshots, diagrams, and PDFs
|
|
122
|
+
โโโ 01-specifications/ # Technical data and system overview
|
|
123
|
+
โโโ 02-safety/ # Safety precautions and LOTO protocols
|
|
124
|
+
โโโ 03-operation/ # Startup sequence and controls
|
|
125
|
+
โโโ 04-maintenance/ # Preventive inspection schedule
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### 3. Configure Remote Qwiki Connection
|
|
129
|
+
|
|
130
|
+
Save your target wiki's URL and API key into your global configuration profile:
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
# Store credentials in ~/.config/qwiki-builder/config.json
|
|
134
|
+
qwiki-builder config --url https://wiki.example.com/manuals --key qwk_llm_your_secret_key
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
*(Alternatively, you can provide `wiki_url` and `api_key` in `qwiki-project.json`, or via environment variables `QWIKI_URL` and `QWIKI_API_KEY`.)*
|
|
138
|
+
|
|
139
|
+
### 4. Validate & Publish
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
# 1. Run local pre-flight checks
|
|
143
|
+
qwiki-builder validate
|
|
144
|
+
|
|
145
|
+
# 2. Preview publish actions without modifying remote server
|
|
146
|
+
qwiki-builder publish --dry-run
|
|
147
|
+
|
|
148
|
+
# 3. Synchronize live to remote Qwiki
|
|
149
|
+
qwiki-builder publish
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## ๐ป CLI Command Reference
|
|
155
|
+
|
|
156
|
+
### `qwiki-builder init [path] [--template TYPE] [--name TITLE]`
|
|
157
|
+
Scaffolds a new project with starter markdown documents and `qwiki-project.json`.
|
|
158
|
+
- `--template`: `user-guide` (default), `equipment-manual`, `quality-manual`, `safety-handbook`, `sop`, or `blank`.
|
|
159
|
+
- `--name`: Display title for the manual.
|
|
160
|
+
- `--url`: Remote wiki endpoint.
|
|
161
|
+
- `--key`: Remote API key.
|
|
162
|
+
|
|
163
|
+
### `qwiki-builder config`
|
|
164
|
+
Manages global connection profiles in `~/.config/qwiki-builder/config.json`.
|
|
165
|
+
- `qwiki-builder config --list`: Show all saved profiles.
|
|
166
|
+
- `qwiki-builder config --profile production --url <url> --key <key>`: Add or update a profile.
|
|
167
|
+
- `qwiki-builder config --delete --profile <name>`: Remove a profile.
|
|
168
|
+
- `qwiki-builder config --show-path`: Print location of global configuration.
|
|
169
|
+
|
|
170
|
+
### `qwiki-builder validate [manifest]`
|
|
171
|
+
Runs local pre-flight checks:
|
|
172
|
+
- Verifies all declared document files exist on disk.
|
|
173
|
+
- Validates category references and slug uniqueness.
|
|
174
|
+
- Checks local image references and flags missing files.
|
|
175
|
+
- Inspects Mermaid diagram formatting for common syntax issues.
|
|
176
|
+
|
|
177
|
+
### `qwiki-builder publish [manifest] [--dry-run] [--reload] [--force]`
|
|
178
|
+
Synchronizes the entire documentation suite:
|
|
179
|
+
- Creates missing categories on the remote wiki automatically.
|
|
180
|
+
- Pre-uploads image and media assets (screenshots, diagrams, MP4/WebM videos) from `assets_dir` and rewrites paths in Markdown and HTML.
|
|
181
|
+
- Publishes or updates documents in-place using stable slugs with optimistic SHA-256 and active UI lock protection.
|
|
182
|
+
- `--dry-run`: Simulates the publication without network mutations.
|
|
183
|
+
- `--reload`: Purges existing chapters in target categories and performs a pristine reload.
|
|
184
|
+
- `--force`: Bypasses optimistic SHA-256 and active UI editor lock guards.
|
|
185
|
+
|
|
186
|
+
### `qwiki-builder pull [target] [manifest] [--all] [--overwrite] [--sync-meta]`
|
|
187
|
+
Downloads already-published document(s), live Comments (`tool-comments`), Talk Page topics (`tool-talk`), and active lock state from Standalone Qwiki before amending:
|
|
188
|
+
- Saves live discussions to `.qwiki-sync/feedback/<bookId>__<slug>.feedback.md` and `.json` (never mixing discussions into document files).
|
|
189
|
+
- Tracks remote SHA-256 and 3-way merge base in `.qwiki-sync/`; auto-merges via `diff3` when clean, or preserves local edits and writes the remote copy to `.qwiki-sync/conflicts/` on overlapping edits.
|
|
190
|
+
- `--sync-meta`: Aligns `title`, `status`, and `description` in `qwiki-project.json` with remote metadata.
|
|
191
|
+
|
|
192
|
+
### `qwiki-builder diff <file-or-slug> [manifest]`
|
|
193
|
+
Shows a unified diff between your local file and the live remote document, plus metadata diffs, active UI editor lock status, and Comment/Talk topic counts.
|
|
194
|
+
|
|
195
|
+
### `qwiki-builder update <file-or-slug> [manifest] [--force] [--expected-sha256 HASH]`
|
|
196
|
+
Updates a single document in place on Qwiki without re-publishing the rest of the suite, enforcing tracked SHA-256 concurrency and active editor lock checks unless `--force` is specified.
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
qwiki-builder pull docs/01-specifications/01-system-overview.md --sync-meta
|
|
200
|
+
qwiki-builder update docs/01-specifications/01-system-overview.md
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### `qwiki-builder upload-assets [manifest]`
|
|
204
|
+
Uploads all images, screenshots, generated visuals, and video assets located in `assets_dir` to Qwiki.
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## ๐ธ Visual Media, Screenshots & Video Embedding
|
|
209
|
+
|
|
210
|
+
Qwiki Builder and Standalone Qwiki treat visual media as first-class documentation elements:
|
|
211
|
+
|
|
212
|
+
1. **Screenshots & UI Mockups**:
|
|
213
|
+
- Save screenshots directly in `docs/assets/images/`.
|
|
214
|
+
- Reference via standard markdown: ``.
|
|
215
|
+
- Automatically uploaded to `uploads/images/` and rewritten to permanent URLs during publishing.
|
|
216
|
+
- Reference example: see `/Documents/MobioPlus/user-docs` deployed to `https://wiki.mobioplus.co.za/user-docs`.
|
|
217
|
+
|
|
218
|
+
2. **Generated Images & Diagrams**:
|
|
219
|
+
- Complex architectural schemas, data flows, and infographics can be saved as `.png`, `.svg`, or `.webp` in `docs/assets/images/`.
|
|
220
|
+
- Native Mermaid diagrams (` ```mermaid `) render client-side without external dependencies.
|
|
221
|
+
|
|
222
|
+
3. **Video Walkthroughs & Screencasts**:
|
|
223
|
+
- Local videos (`.mp4`, `.webm`, `.ogg`, `.mov`) stored in `docs/assets/videos/` are automatically uploaded to `uploads/videos/`.
|
|
224
|
+
- Standalone Markdown video links convert into embedded HTML5 players:
|
|
225
|
+
```markdown
|
|
226
|
+
[Watch Territory Planning Demo](assets/videos/demo.mp4)
|
|
227
|
+
```
|
|
228
|
+
- External videos (YouTube, Vimeo, Loom) convert automatically into responsive embeds when their URL is placed on its own line:
|
|
229
|
+
```markdown
|
|
230
|
+
https://www.youtube.com/watch?v=dQw4w9WgXcQ
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
### `qwiki-builder list [manifest] [--book-id ID]`
|
|
234
|
+
Queries the remote Qwiki API, lists registered chapters, and highlights duplicate titles or suffixed slugs.
|
|
235
|
+
|
|
236
|
+
### `qwiki-builder dedup [manifest] [--dry-run]`
|
|
237
|
+
Scans the remote wiki for duplicates (e.g., chapters with identical titles or suffixed slugs like `overview-1`) and safely removes them.
|
|
238
|
+
|
|
239
|
+
### `qwiki-builder reload [manifest]`
|
|
240
|
+
Cleanly purges all chapters under the project's categories on the remote wiki and re-uploads all canonical documents.
|
|
241
|
+
|
|
242
|
+
### `qwiki-builder delete <slug> [manifest] [--book-id ID]`
|
|
243
|
+
Deletes a specific chapter from the remote wiki by slug.
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
## ๐๏ธ Manifest Schema (`qwiki-project.json`)
|
|
248
|
+
|
|
249
|
+
```json
|
|
250
|
+
{
|
|
251
|
+
"name": "Titan 5000 Operator Manual",
|
|
252
|
+
"slug": "titan-5000-manual",
|
|
253
|
+
"version": "1.0.0",
|
|
254
|
+
"doc_type_preset": "equipment-manual",
|
|
255
|
+
"description": "Comprehensive operation and safety manual.",
|
|
256
|
+
"wiki_url": "https://wiki.example.com/manuals",
|
|
257
|
+
"docs_dir": "docs",
|
|
258
|
+
"assets_dir": "docs/assets",
|
|
259
|
+
"default_status": "published",
|
|
260
|
+
"public_shareable": true,
|
|
261
|
+
"categories": [
|
|
262
|
+
{
|
|
263
|
+
"id": "specifications",
|
|
264
|
+
"title": "System Specifications",
|
|
265
|
+
"description": "General machine architecture and parameters"
|
|
266
|
+
},
|
|
267
|
+
{
|
|
268
|
+
"id": "safety",
|
|
269
|
+
"title": "Safety & Warnings",
|
|
270
|
+
"description": "Mandatory PPE, emergency stops, and lockout/tagout"
|
|
271
|
+
}
|
|
272
|
+
],
|
|
273
|
+
"documents": [
|
|
274
|
+
{
|
|
275
|
+
"file": "01-specifications/01-system-overview.md",
|
|
276
|
+
"category": "specifications",
|
|
277
|
+
"slug": "equipment-system-overview",
|
|
278
|
+
"title": "Equipment Overview & Architecture",
|
|
279
|
+
"status": "published"
|
|
280
|
+
},
|
|
281
|
+
{
|
|
282
|
+
"file": "02-safety/01-safety-precautions.md",
|
|
283
|
+
"category": "safety",
|
|
284
|
+
"slug": "equipment-safety-warnings-loto",
|
|
285
|
+
"title": "Safety Precautions & LOTO Protocols",
|
|
286
|
+
"status": "published"
|
|
287
|
+
}
|
|
288
|
+
]
|
|
289
|
+
}
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
> [!TIP]
|
|
293
|
+
> **Auto-Discovery Mode**: If you omit the `"documents"` array or leave it empty, `qwiki-builder` automatically discovers all `.md` and `.html` files in `docs_dir`, using subdirectories as category IDs and extracting H1 headings as document titles!
|
|
294
|
+
|
|
295
|
+
---
|
|
296
|
+
|
|
297
|
+
## ๐ Credential Resolution Priority
|
|
298
|
+
|
|
299
|
+
Qwiki Builder resolves the target Wiki URL and API Key in the following order:
|
|
300
|
+
|
|
301
|
+
1. **Explicit CLI flags**: `--url` and `--key`
|
|
302
|
+
2. **Explicit CLI profile**: `--profile <name>`
|
|
303
|
+
3. **Project manifest**: `wiki_url` and `api_key` in `qwiki-project.json`
|
|
304
|
+
4. **Environment variables**: `QWIKI_URL` and `QWIKI_API_KEY`
|
|
305
|
+
5. **Global default profile**: `~/.config/qwiki-builder/config.json`
|
|
306
|
+
|
|
307
|
+
---
|
|
308
|
+
|
|
309
|
+
## ๐ Python Library SDK
|
|
310
|
+
|
|
311
|
+
You can embed Qwiki Builder directly into your Python tools, web services, or data pipelines:
|
|
312
|
+
|
|
313
|
+
```python
|
|
314
|
+
from pathlib import Path
|
|
315
|
+
from qwikibuilder import QwikiClient, QwikiProjectManifest, QwikiPublisher, ProjectValidator
|
|
316
|
+
|
|
317
|
+
# Load project
|
|
318
|
+
manifest = QwikiProjectManifest.load(Path("qwiki-project.json"))
|
|
319
|
+
|
|
320
|
+
# Validate
|
|
321
|
+
validator = ProjectValidator(manifest)
|
|
322
|
+
report = validator.validate()
|
|
323
|
+
if not report.is_valid:
|
|
324
|
+
print(f"Validation errors: {report.errors}")
|
|
325
|
+
exit(1)
|
|
326
|
+
|
|
327
|
+
# Connect and deploy
|
|
328
|
+
client = QwikiClient(base_url="https://wiki.example.com/docs", api_key="qwk_llm_...")
|
|
329
|
+
publisher = QwikiPublisher(manifest, client)
|
|
330
|
+
|
|
331
|
+
# Publish all chapters
|
|
332
|
+
result = publisher.publish_all()
|
|
333
|
+
print(f"Successfully published {result['synced']}/{result['total']} chapters.")
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
---
|
|
337
|
+
|
|
338
|
+
## ๐ค AI Agent Workflow & Autonomous Authoring
|
|
339
|
+
|
|
340
|
+
Qwiki Builder is designed to be paired with AI Agents (Antigravity, Claude, Cursor, Copilot, Gemini CLI).
|
|
341
|
+
|
|
342
|
+
- Read [`AGENTS.md`](AGENTS.md) for full agent operating instructions.
|
|
343
|
+
- An Antigravity / Agent Skill definition is available at [`skills/qwiki-doc-builder/SKILL.md`](skills/qwiki-doc-builder/SKILL.md).
|
|
344
|
+
|
|
345
|
+
Agents can autonomously:
|
|
346
|
+
1. Interview users or ingest raw specifications, PRDs, and codebase docs.
|
|
347
|
+
2. Select the right template preset (`equipment-manual`, `quality-manual`, etc.).
|
|
348
|
+
3. Generate compliant Markdown with Mermaid diagrams and structured tables.
|
|
349
|
+
4. Run `qwiki-builder validate` to check for syntax or link errors.
|
|
350
|
+
5. Deploy to Standalone Qwiki via `qwiki-builder publish`.
|
|
351
|
+
|
|
352
|
+
---
|
|
353
|
+
|
|
354
|
+
## ๐ CI/CD Automation (GitHub Actions)
|
|
355
|
+
|
|
356
|
+
Deploy documentation automatically on every `git push`:
|
|
357
|
+
|
|
358
|
+
Create `.github/workflows/deploy-docs.yml`:
|
|
359
|
+
|
|
360
|
+
```yaml
|
|
361
|
+
name: Deploy Documentation to Qwiki
|
|
362
|
+
|
|
363
|
+
on:
|
|
364
|
+
push:
|
|
365
|
+
branches: [main]
|
|
366
|
+
paths:
|
|
367
|
+
- 'docs/**'
|
|
368
|
+
- 'qwiki-project.json'
|
|
369
|
+
|
|
370
|
+
jobs:
|
|
371
|
+
deploy-qwiki:
|
|
372
|
+
runs-on: ubuntu-latest
|
|
373
|
+
steps:
|
|
374
|
+
- uses: actions/checkout@v4
|
|
375
|
+
- uses: actions/setup-python@v5
|
|
376
|
+
with:
|
|
377
|
+
python-version: '3.12'
|
|
378
|
+
|
|
379
|
+
- name: Install Qwiki Builder
|
|
380
|
+
run: pip install git+https://github.com/FrancoBenedetti/qwiki-builder.git
|
|
381
|
+
|
|
382
|
+
- name: Validate Documentation
|
|
383
|
+
run: qwiki-builder validate
|
|
384
|
+
|
|
385
|
+
- name: Publish to Qwiki
|
|
386
|
+
env:
|
|
387
|
+
QWIKI_URL: ${{ secrets.QWIKI_URL }}
|
|
388
|
+
QWIKI_API_KEY: ${{ secrets.QWIKI_API_KEY }}
|
|
389
|
+
run: qwiki-builder publish
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
---
|
|
393
|
+
|
|
394
|
+
## ๐งช Testing
|
|
395
|
+
|
|
396
|
+
Run the full automated test suite:
|
|
397
|
+
|
|
398
|
+
```bash
|
|
399
|
+
python3 -m unittest discover tests -v
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
---
|
|
403
|
+
|
|
404
|
+
## ๐ License
|
|
405
|
+
|
|
406
|
+
Released under the [MIT License](LICENSE). Built for the global Qwiki and Antigravity community.
|