Skip to content

Commit 7ad254f

Browse files
dmealingdmealing
committed
Add complete documentation deployment infrastructure
- GitHub Actions workflow for automatic deployment - Professional MkDocs site with Material theme - Custom CSS/JS for enhanced user experience - Python dependencies and deployment guides - GitHub Pages redirect and documentation README - Issue template for documentation feedback Ready for live documentation website deployment.
1 parent 18d4c71 commit 7ad254f

22 files changed

Lines changed: 9746 additions & 9 deletions

‎.github/ISSUE_TEMPLATE/documentation.yml‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
name: 📚 Documentation Issue
2+
description: Report issues with documentation content, website, or deployment
3+
title: "[DOCS]: "
4+
labels: ["documentation", "triage"]
5+
assignees: []
6+
7+
body:
8+
- type: markdown
9+
attributes:
10+
value: |
11+
Thanks for helping improve the MetaObjects documentation!
12+
13+
Please provide details about the documentation issue you've encountered.
14+
15+
- type: dropdown
16+
id: issue-type
17+
attributes:
18+
label: Issue Type
19+
description: What type of documentation issue is this?
20+
options:
21+
- Content Error (incorrect information)
22+
- Missing Documentation (feature not documented)
23+
- Broken Link (internal or external link not working)
24+
- Code Example Error (example doesn't work)
25+
- Website Issue (styling, navigation, search problems)
26+
- Deployment Issue (documentation site not building/deploying)
27+
- Accessibility Issue (screen reader, keyboard navigation problems)
28+
- Performance Issue (slow loading, large files)
29+
- Mobile/Responsive Issue (doesn't work on mobile devices)
30+
- Other
31+
validations:
32+
required: true
33+
34+
- type: input
35+
id: page-url
36+
attributes:
37+
label: Page URL
38+
description: URL of the documentation page with the issue
39+
placeholder: "https://metaobjectsdev.github.io/metaobjects-core/user-guide/..."
40+
validations:
41+
required: false
42+
43+
- type: textarea
44+
id: description
45+
attributes:
46+
label: Description
47+
description: Detailed description of the issue
48+
placeholder: |
49+
Please describe:
50+
- What you expected to see or happen
51+
- What actually happened or what's wrong
52+
- Steps to reproduce (if applicable)
53+
- Browser/device information (for website issues)
54+
validations:
55+
required: true
56+
57+
- type: textarea
58+
id: current-content
59+
attributes:
60+
label: Current Content (if applicable)
61+
description: Copy/paste the current incorrect content
62+
render: markdown
63+
validations:
64+
required: false
65+
66+
- type: textarea
67+
id: suggested-content
68+
attributes:
69+
label: Suggested Fix/Content
70+
description: How should this be corrected or what content should be added?
71+
render: markdown
72+
validations:
73+
required: false
74+
75+
- type: textarea
76+
id: code-example
77+
attributes:
78+
label: Code Example (if applicable)
79+
description: If reporting a code example issue, paste the code that doesn't work
80+
render: java
81+
validations:
82+
required: false
83+
84+
- type: input
85+
id: framework-version
86+
attributes:
87+
label: MetaObjects Version
88+
description: Which version of the MetaObjects framework does this relate to?
89+
placeholder: "6.2.0"
90+
validations:
91+
required: false
92+
93+
- type: checkboxes
94+
id: environment
95+
attributes:
96+
label: Environment (for website issues)
97+
description: Where did you encounter this issue?
98+
options:
99+
- label: Desktop browser (Chrome)
100+
- label: Desktop browser (Firefox)
101+
- label: Desktop browser (Safari)
102+
- label: Desktop browser (Edge)
103+
- label: Mobile browser (iOS Safari)
104+
- label: Mobile browser (Android Chrome)
105+
- label: Screen reader
106+
- label: Local development (mkdocs serve)
107+
- label: Documentation build process
108+
109+
- type: dropdown
110+
id: priority
111+
attributes:
112+
label: Priority
113+
description: How would you rate the severity of this issue?
114+
options:
115+
- Low (cosmetic, enhancement)
116+
- Medium (affects usability)
117+
- High (incorrect information, broken functionality)
118+
- Critical (documentation completely inaccessible)
119+
validations:
120+
required: true
121+
122+
- type: textarea
123+
id: additional-context
124+
attributes:
125+
label: Additional Context
126+
description: Any other information that might be helpful
127+
placeholder: |
128+
- Related issues or pages
129+
- Screenshots (if helpful)
130+
- Error messages
131+
- Browser console errors
132+
- Build logs (for deployment issues)
133+
validations:
134+
required: false
135+
136+
- type: checkboxes
137+
id: contribution
138+
attributes:
139+
label: Contribution
140+
description: Are you willing to help fix this issue?
141+
options:
142+
- label: I can provide a pull request to fix this issue
143+
- label: I can help test a fix for this issue
144+
- label: I can provide additional information if needed
145+
146+
- type: markdown
147+
attributes:
148+
value: |
149+
---
150+
151+
## 📚 Documentation Resources
152+
153+
- **Documentation Plan**: [docs/DOCUMENTATION_PLAN.md](https://github.com/metaobjectsdev/metaobjects-core/blob/main/docs/DOCUMENTATION_PLAN.md)
154+
- **Deployment Guide**: [docs/DEPLOYMENT.md](https://github.com/metaobjectsdev/metaobjects-core/blob/main/docs/DEPLOYMENT.md)
155+
- **Local Development**: [docs/README.md](https://github.com/metaobjectsdev/metaobjects-core/blob/main/docs/README.md)
156+
- **Writing Guidelines**: Available in DOCUMENTATION_PLAN.md
157+
158+
## 🚀 Quick Fixes
159+
160+
**For content errors**: Most documentation content is in `docs/src/site/documentation/docs/`
161+
**For website issues**: Check `docs/src/site/documentation/mkdocs.yml` configuration
162+
**For deployment issues**: Review `.github/workflows/deploy-docs.yml` workflow
163+
164+
Thank you for helping improve the MetaObjects documentation! 🎉

‎.github/workflows/deploy-docs.yml‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [ main, master, develop ]
6+
paths:
7+
- 'docs/**'
8+
- '.github/workflows/deploy-docs.yml'
9+
pull_request:
10+
branches: [ main, master ]
11+
paths:
12+
- 'docs/**'
13+
14+
# Allow manual triggering
15+
workflow_dispatch:
16+
17+
permissions:
18+
contents: read
19+
pages: write
20+
id-token: write
21+
22+
# Allow only one concurrent deployment
23+
concurrency:
24+
group: "pages"
25+
cancel-in-progress: false
26+
27+
jobs:
28+
# Build job
29+
build:
30+
runs-on: ubuntu-latest
31+
steps:
32+
- name: Checkout repository
33+
uses: actions/checkout@v4
34+
with:
35+
fetch-depth: 0 # Fetch full history for git-revision-date-localized plugin
36+
37+
- name: Setup Python
38+
uses: actions/setup-python@v4
39+
with:
40+
python-version: '3.11'
41+
cache: 'pip'
42+
43+
- name: Install dependencies
44+
run: |
45+
pip install --upgrade pip
46+
pip install -r docs/requirements.txt
47+
48+
- name: Configure Git for git-revision-date-localized
49+
run: |
50+
git config --global user.name "GitHub Actions"
51+
git config --global user.email "actions@github.com"
52+
53+
- name: Build documentation
54+
run: |
55+
cd docs/src/site/documentation
56+
mkdocs build --strict --verbose
57+
58+
- name: Upload documentation artifacts
59+
uses: actions/upload-pages-artifact@v3
60+
with:
61+
path: docs/src/site/documentation/site
62+
63+
# Deploy job - only on main/master branch pushes
64+
deploy:
65+
if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
66+
environment:
67+
name: github-pages
68+
url: ${{ steps.deployment.outputs.page_url }}
69+
runs-on: ubuntu-latest
70+
needs: build
71+
steps:
72+
- name: Deploy to GitHub Pages
73+
id: deployment
74+
uses: actions/deploy-pages@v4
75+
76+
# Validation job for PRs
77+
validate:
78+
if: github.event_name == 'pull_request'
79+
runs-on: ubuntu-latest
80+
needs: build
81+
steps:
82+
- name: Documentation build validation
83+
run: |
84+
echo "✅ Documentation builds successfully"
85+
echo "📝 Review the documentation changes in this PR"
86+
echo "🚀 Documentation will be deployed when PR is merged"

0 commit comments

Comments
 (0)