Skip to content

Commit 812fe7d

Browse files
Copilotdannywillems
Copilot
and
dannywillems
committed
Implement Docusaurus versioning for website documentation
Co-authored-by: dannywillems <[email protected]>
1 parent 5ba8f5d commit 812fe7d

File tree

5 files changed

+250
-4
lines changed

5 files changed

+250
-4
lines changed

‎Makefile‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -536,6 +536,40 @@ docs-clean: ## Clean documentation build artifacts
536536
@rm -rf website/build website/.docusaurus website/static/api-docs target/doc
537537
@echo "Documentation artifacts cleaned!"
538538

539+
# Documentation versioning targets
540+
541+
.PHONY: docs-version-create
542+
docs-version-create: docs-install ## Create a new documentation version (requires VERSION=x.y.z)
543+
@if [ -z "$(VERSION)" ]; then \
544+
echo "Error: VERSION is required. Usage: make docs-version-create VERSION=1.2.3"; \
545+
exit 1; \
546+
fi
547+
@echo "Creating documentation version $(VERSION)..."
548+
@cd website && npx docusaurus docs:version "$(VERSION)"
549+
@echo "Documentation version $(VERSION) created successfully!"
550+
@echo "Files created in website/versioned_docs/version-$(VERSION)/"
551+
552+
.PHONY: docs-version-list
553+
docs-version-list: docs-install ## List all documentation versions
554+
@echo "Available documentation versions:"
555+
@cd website && if [ -f versions.json ]; then cat versions.json | jq -r '.[]' | sed 's/^/ - /'; else echo " No versions found. Current version only."; fi
556+
557+
.PHONY: docs-version-clean
558+
docs-version-clean: ## Clean all versioned documentation (WARNING: destructive)
559+
@echo "WARNING: This will remove all versioned documentation!"
560+
@echo "Files to be removed:"
561+
@echo " - website/versioned_docs/"
562+
@echo " - website/versioned_sidebars/"
563+
@echo " - website/versions.json"
564+
@echo ""
565+
@echo "Use 'make docs-version-clean-force' to proceed without confirmation"
566+
567+
.PHONY: docs-version-clean-force
568+
docs-version-clean-force: ## Force clean all versioned documentation (no confirmation)
569+
@echo "Removing all versioned documentation..."
570+
@rm -rf website/versioned_docs website/versioned_sidebars website/versions.json
571+
@echo "All versioned documentation removed!"
572+
539573
# Release management targets
540574

541575
.PHONY: release-validate
@@ -571,6 +605,14 @@ release-create-tag: ## Create and push git tag (requires TAG=version MESSAGE="de
571605
release-merge-back: ## Merge main back to develop after release
572606
@website/docs/developers/scripts/release/merge-back.sh
573607

608+
.PHONY: release-docs-version
609+
release-docs-version: ## Create documentation version for release (requires VERSION=x.y.z)
610+
@if [ -z "$(VERSION)" ]; then \
611+
echo "Error: VERSION is required. Usage: make release-docs-version VERSION=1.2.3"; \
612+
exit 1; \
613+
fi
614+
@make docs-version-create VERSION="$(VERSION)"
615+
574616
.PHONY: release-help
575617
release-help: ## Show release management commands
576618
@echo "Release Management Commands:"
@@ -579,12 +621,21 @@ release-help: ## Show release management commands
579621
@echo " release-update-version - Update Cargo.toml versions (requires VERSION=x.y.z)"
580622
@echo " release-create-tag - Create and push git tag (requires TAG=vx.y.z MESSAGE='...')"
581623
@echo " release-docker-verify - Verify Docker images (requires TAG=vx.y.z)"
624+
@echo " release-docs-version - Create documentation version (requires VERSION=x.y.z)"
582625
@echo " release-merge-back - Merge main back to develop"
583626
@echo ""
627+
@echo "Documentation Versioning Commands:"
628+
@echo ""
629+
@echo " docs-version-create - Create new docs version (requires VERSION=x.y.z)"
630+
@echo " docs-version-list - List all documentation versions"
631+
@echo " docs-version-clean - Show files that would be removed (safe)"
632+
@echo " docs-version-clean-force - Remove all versioned docs (WARNING: destructive)"
633+
@echo ""
584634
@echo "Example workflow:"
585635
@echo " make release-validate"
586636
@echo " make release-update-version VERSION=1.2.3"
587637
@echo " # Create PR, get approval, merge to main"
588638
@echo " make release-create-tag TAG=v1.2.3 MESSAGE='Release v1.2.3'"
639+
@echo " make release-docs-version VERSION=1.2.3"
589640
@echo " make release-docker-verify TAG=v1.2.3"
590641
@echo " make release-merge-back"

‎website/docs/appendix/documentation-versioning.mdx‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
title: Documentation Versioning
3+
description:
4+
Guide to managing and using versioned documentation in the Mina Rust project
5+
sidebar_position: 3
6+
---
7+
8+
# Documentation Versioning
9+
10+
The Mina Rust documentation uses
11+
[Docusaurus versioning](https://docusaurus.io/docs/versioning) to maintain
12+
documentation for multiple releases. This allows users to access documentation
13+
for specific versions of the software.
14+
15+
## How Versioning Works
16+
17+
### Version Structure
18+
19+
- **Current Version (`develop`)**: The latest development documentation,
20+
available at the root path (`/docs/`)
21+
- **Released Versions**: Specific release versions (e.g., `1.0.0`), available at
22+
versioned paths (`/docs/1.0.0/`)
23+
24+
### Accessing Different Versions
25+
26+
Users can switch between documentation versions using the version dropdown in
27+
the navigation bar. Each version maintains its own complete documentation tree.
28+
29+
## Managing Documentation Versions
30+
31+
### Creating a New Version
32+
33+
Create a new documentation version during the release process:
34+
35+
```bash
36+
# Create version for release 1.2.3
37+
make docs-version-create VERSION=1.2.3
38+
39+
# Or as part of the release workflow
40+
make release-docs-version VERSION=1.2.3
41+
```
42+
43+
This command:
44+
45+
- Takes a snapshot of the current `docs/` directory
46+
- Creates versioned copies in `website/versioned_docs/version-1.2.3/`
47+
- Updates `website/versions.json` to include the new version
48+
- Makes the version available in the dropdown menu
49+
50+
### Listing Available Versions
51+
52+
```bash
53+
# List all available documentation versions
54+
make docs-version-list
55+
```
56+
57+
### Cleaning Up Versions
58+
59+
:::warning Destructive Operation This command permanently removes all versioned
60+
documentation. Use with caution. :::
61+
62+
```bash
63+
# Remove all versioned documentation (interactive confirmation)
64+
make docs-version-clean
65+
```
66+
67+
## Version Behavior
68+
69+
### Current Version (develop)
70+
71+
- Always shows the latest documentation from the `docs/` directory
72+
- Available at the root documentation path
73+
- Labeled as "develop" in the version dropdown
74+
- No version banners or warnings
75+
76+
### Released Versions
77+
78+
- Snapshot of documentation at the time of release
79+
- Available at `/docs/{version}/` paths
80+
- Shows a banner indicating the version is no longer actively maintained
81+
- Provides a link back to the current (develop) version
82+
83+
### Version Dropdown
84+
85+
The version dropdown in the navigation bar:
86+
87+
- Lists all available versions
88+
- Shows the current selection
89+
- Allows quick switching between versions
90+
- Maintains the current page context when switching (if the page exists in the
91+
target version)
92+
93+
## Best Practices
94+
95+
### When to Create Versions
96+
97+
- **Always** create a documentation version as part of the release process
98+
- Create versions for major and minor releases
99+
- Consider creating versions for significant patch releases with documentation
100+
changes
101+
- Do not create versions for minor documentation updates between releases
102+
103+
### Maintaining Version Quality
104+
105+
- Ensure documentation is complete and accurate before creating a version
106+
- Test all links and examples in the documentation before versioning
107+
- Update any version-specific information (installation instructions,
108+
compatibility notes)
109+
110+
### Documentation Updates
111+
112+
- **Current documentation**: Edit files in `website/docs/`
113+
- **Versioned documentation**: Edit files in
114+
`website/versioned_docs/version-{version}/`
115+
- **Sidebar configuration**: Versioned sidebars are stored in
116+
`website/versioned_sidebars/`
117+
118+
## File Structure
119+
120+
```
121+
website/
122+
├── docs/ # Current (develop) documentation
123+
├── versioned_docs/
124+
│ └── version-1.0.0/ # Versioned documentation
125+
├── versioned_sidebars/
126+
│ └── version-1.0.0-sidebars.json # Versioned sidebars
127+
└── versions.json # List of available versions
128+
```
129+
130+
## Integration with Release Process
131+
132+
Documentation versioning is integrated into the release workflow:
133+
134+
1. **Version Creation**: Part of the release process after tag creation
135+
2. **Automated**: Uses the same version number as the software release
136+
3. **Consistent**: Ensures documentation versions match software versions
137+
4. **Preserved**: Maintains historical documentation for all releases
138+
139+
For complete release process details, see the
140+
[Release Process](./release-process.mdx) guide.
141+
142+
## Troubleshooting
143+
144+
### Version Not Appearing in Dropdown
145+
146+
1. Check that `website/versions.json` includes the version
147+
2. Verify files exist in `website/versioned_docs/version-{version}/`
148+
3. Rebuild the documentation site
149+
150+
### Broken Links in Versioned Docs
151+
152+
- Versioned documentation uses absolute paths within the version
153+
- Links between versions are not automatically updated
154+
- Test documentation thoroughly before creating versions
155+
156+
### Large Repository Size
157+
158+
- Versioned documentation duplicates content
159+
- Consider the trade-off between version history and repository size
160+
- Remove very old versions if repository size becomes problematic
161+
162+
## Related Commands
163+
164+
```bash
165+
# Documentation building and serving
166+
make docs-build # Build with API docs
167+
make docs-serve # Serve locally with hot reload
168+
make docs-clean # Clean build artifacts
169+
170+
# Release integration
171+
make release-help # Show all release commands
172+
make release-docs-version VERSION=x.y.z # Create docs version for release
173+
```

‎website/docs/appendix/release-process.mdx‎

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,7 @@ Copy and paste this checklist when announcing a release in progress:
8282
- [ ] Required approvals obtained
8383
- [ ] PR merged to main
8484
- [ ] Git tag created and pushed
85+
- [ ] Documentation version created
8586
- [ ] Docker images building (automated)
8687
- [ ] GitHub release draft created
8788

@@ -301,7 +302,25 @@ This automatically:
301302
- Creates an annotated tag with the provided message
302303
- Pushes the tag to origin (which triggers Docker image builds)
303304

304-
### 6. Create GitHub Release
305+
### 6. Create Documentation Version
306+
307+
```bash
308+
# Create a versioned copy of the documentation
309+
make release-docs-version VERSION=1.5.0
310+
```
311+
312+
This command:
313+
314+
- Creates a snapshot of the current documentation under
315+
`website/versioned_docs/version-1.5.0/`
316+
- Preserves the exact state of documentation at the time of release
317+
- Allows users to access documentation for previous versions
318+
- Updates the version dropdown to include the new version
319+
320+
The versioned documentation will be available at `/docs/1.5.0/` and can be
321+
accessed through the version dropdown in the website navigation.
322+
323+
### 7. Create GitHub Release
305324

306325
```bash
307326
# Create GitHub release from tag
@@ -317,7 +336,7 @@ gh release create v1.5.0 \
317336
--draft
318337
```
319338

320-
### 7. Verify Automated Processes
339+
### 8. Verify Automated Processes
321340

322341
After pushing the tag, verify:
323342

@@ -353,7 +372,7 @@ After pushing the tag, verify:
353372
- Visit
354373
[Docker Hub - mina-rust-frontend](https://hub.docker.com/r/o1labs/mina-rust-frontend/tags)
355374

356-
### 8. Publish GitHub Release
375+
### 9. Publish GitHub Release
357376

358377
Once verification is complete:
359378

@@ -362,7 +381,7 @@ Once verification is complete:
362381
gh release edit v1.5.0 --draft=false
363382
```
364383

365-
### 9. Update Documentation
384+
### 10. Update Documentation
366385

367386
- Update any documentation that references version numbers
368387
- Announce release in relevant channels

‎website/docusaurus.config.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ const config: Config = {
5252
versions: {
5353
current: {
5454
label: 'develop',
55+
path: '/', // Current version at root path
56+
badge: true,
5557
},
5658
},
5759
// Enable edit links to GitHub

‎website/sidebars.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -164,6 +164,7 @@ const sidebars: SidebarsConfig = {
164164
label: 'Development Processes',
165165
items: [
166166
'appendix/release-process',
167+
'appendix/documentation-versioning',
167168
],
168169
},
169170
],

0 commit comments

Comments
 (0)