Skip to content

Commit cab7536

Browse files
irangareddyirangareddy
committed
setup docs
0 parents  commit cab7536

File tree

21 files changed

+4640
-0
lines changed

21 files changed

+4640
-0
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- "docs/**"
9+
- "mkdocs.yml"
10+
- "pyproject.toml"
11+
- ".github/workflows/docs.yml"
12+
workflow_dispatch:
13+
14+
permissions:
15+
contents: write # Allow commits for auto-fixing
16+
pages: write
17+
id-token: write
18+
19+
concurrency:
20+
group: "pages"
21+
cancel-in-progress: false
22+
23+
jobs:
24+
lint:
25+
runs-on: ubuntu-latest
26+
steps:
27+
- name: Checkout
28+
uses: actions/checkout@v4
29+
with:
30+
fetch-depth: 0
31+
32+
- name: Setup Python
33+
id: setup-python-lint
34+
uses: actions/setup-python@v4
35+
with:
36+
python-version: "3.11"
37+
38+
- name: Install Poetry
39+
uses: snok/install-poetry@v1
40+
with:
41+
version: latest
42+
virtualenvs-create: true
43+
virtualenvs-in-project: true
44+
45+
- name: Load cached venv
46+
id: cached-poetry-dependencies
47+
uses: actions/cache@v3
48+
with:
49+
path: .venv
50+
key: venv-lint-${{ runner.os }}-${{ steps.setup-python-lint.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
51+
52+
- name: Install dependencies
53+
if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
54+
run: poetry install --no-interaction --no-root
55+
56+
- name: Run pre-commit hooks
57+
run: poetry run pre-commit run --all-files --show-diff-on-failure
58+
59+
- name: Test documentation build
60+
run: |
61+
echo "🏗️ Testing if documentation builds successfully..."
62+
poetry run mkdocs build --strict
63+
echo "✅ Documentation builds successfully!"
64+
65+
- name: Validate navigation and links
66+
run: |
67+
echo "🔍 Validating navigation structure..."
68+
# Check if all nav items have corresponding files
69+
poetry run python -c "
70+
import yaml
71+
import os
72+
73+
with open('mkdocs.yml', 'r') as f:
74+
config = yaml.safe_load(f)
75+
76+
def check_nav_item(item, path=''):
77+
if isinstance(item, dict):
78+
for key, value in item.items():
79+
if isinstance(value, str):
80+
file_path = os.path.join('docs', value)
81+
if not os.path.exists(file_path):
82+
print(f'❌ Missing file: {file_path}')
83+
exit(1)
84+
else:
85+
print(f'✅ Found: {file_path}')
86+
elif isinstance(value, list):
87+
for sub_item in value:
88+
check_nav_item(sub_item, path)
89+
elif isinstance(item, list):
90+
for sub_item in item:
91+
check_nav_item(sub_item, path)
92+
93+
if 'nav' in config:
94+
check_nav_item(config['nav'])
95+
print('✅ All navigation files exist!')
96+
else:
97+
print('⚠️ No navigation section found in mkdocs.yml')
98+
"
99+
100+
- name: Check for broken internal links
101+
run: |
102+
echo "🔗 Checking for broken internal links in markdown files..."
103+
find docs -name "*.md" -exec grep -l "\[\[.*\]\]" {} \; | while read file; do
104+
echo "⚠️ Found wiki-style links in $file - consider converting to standard markdown links"
105+
done
106+
107+
# Check for common broken link patterns
108+
find docs -name "*.md" -exec grep -Hn "](\.\./" {} \; | while read line; do
109+
echo "⚠️ Potential relative link issue: $line"
110+
done
111+
112+
- name: Check if files were modified
113+
id: verify-changed-files
114+
run: |
115+
if [ -n "$(git status --porcelain)" ]; then
116+
echo "changed=true" >> $GITHUB_OUTPUT
117+
echo "Files were modified by pre-commit hooks:"
118+
git status --porcelain
119+
else
120+
echo "changed=false" >> $GITHUB_OUTPUT
121+
echo "No files were modified by pre-commit hooks"
122+
fi
123+
124+
- name: Commit and push changes
125+
if: steps.verify-changed-files.outputs.changed == 'true'
126+
run: |
127+
git config --local user.email "[email protected]"
128+
git config --local user.name "GitHub Action"
129+
git add .
130+
git commit -m "🔧 Auto-fix markdown linting issues [skip ci]"
131+
git push
132+
133+
build:
134+
runs-on: ubuntu-latest
135+
needs: lint
136+
if: needs.lint.result == 'success'
137+
steps:
138+
- name: Checkout
139+
uses: actions/checkout@v4
140+
with:
141+
fetch-depth: 0 # Needed for git revision date plugin
142+
143+
- name: Setup Python
144+
id: setup-python-build
145+
uses: actions/setup-python@v4
146+
with:
147+
python-version: "3.11"
148+
149+
- name: Install Poetry
150+
uses: snok/install-poetry@v1
151+
with:
152+
version: latest
153+
virtualenvs-create: true
154+
virtualenvs-in-project: true
155+
156+
- name: Load cached venv
157+
id: cached-poetry-dependencies
158+
uses: actions/cache@v3
159+
with:
160+
path: .venv
161+
key: venv-${{ runner.os }}-${{ steps.setup-python-build.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
162+
163+
- name: Install dependencies
164+
if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
165+
run: poetry install --no-interaction --no-root
166+
167+
- name: Build documentation
168+
run: poetry run mkdocs build
169+
170+
- name: Setup Pages
171+
uses: actions/configure-pages@v3
172+
173+
- name: Upload artifact
174+
uses: actions/upload-pages-artifact@v2
175+
with:
176+
path: ./site
177+
178+
deploy:
179+
environment:
180+
name: github-pages
181+
url: ${{ steps.deployment.outputs.page_url }}
182+
runs-on: ubuntu-latest
183+
needs: build
184+
steps:
185+
- name: Deploy to GitHub Pages
186+
id: deployment
187+
uses: actions/deploy-pages@v2
188+
189+
notify:
190+
runs-on: ubuntu-latest
191+
needs: [build, deploy]
192+
if: always() && needs.deploy.result == 'success'
193+
steps:
194+
- name: Checkout
195+
uses: actions/checkout@v4
196+
with:
197+
fetch-depth: 10 # Get recent commits for changelog
198+
199+
- name: Get latest changes
200+
id: changes
201+
run: |
202+
# Get the latest commit info
203+
COMMIT_MESSAGE=$(git log -1 --pretty=format:"%s")
204+
COMMIT_AUTHOR=$(git log -1 --pretty=format:"%an")
205+
COMMIT_SHA=$(git log -1 --pretty=format:"%h")
206+
COMMIT_URL="https://github.com/${{ github.repository }}/commit/${{ github.sha }}"
207+
208+
# Get changed files related to documentation
209+
CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD | grep -E '\.(md|yml|yaml)$' | head -10 || echo "No documentation files changed")
210+
211+
# Get recent commits (last 5)
212+
RECENT_COMMITS=$(git log --oneline -5 --pretty=format:"• %s (%an)")
213+
214+
echo "commit_message=$COMMIT_MESSAGE" >> $GITHUB_OUTPUT
215+
echo "commit_author=$COMMIT_AUTHOR" >> $GITHUB_OUTPUT
216+
echo "commit_sha=$COMMIT_SHA" >> $GITHUB_OUTPUT
217+
echo "commit_url=$COMMIT_URL" >> $GITHUB_OUTPUT
218+
echo "changed_files<<EOF" >> $GITHUB_OUTPUT
219+
echo "$CHANGED_FILES" >> $GITHUB_OUTPUT
220+
echo "EOF" >> $GITHUB_OUTPUT
221+
echo "recent_commits<<EOF" >> $GITHUB_OUTPUT
222+
echo "$RECENT_COMMITS" >> $GITHUB_OUTPUT
223+
echo "EOF" >> $GITHUB_OUTPUT
224+
225+
- name: Send Discord notification
226+
env:
227+
DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
228+
run: |
229+
# Check if webhook URL is set
230+
if [ -z "$DISCORD_WEBHOOK_URL" ]; then
231+
echo "Discord webhook URL not set, skipping notification"
232+
exit 0
233+
fi
234+
# Create the Discord message payload
235+
cat << EOF > discord_payload.json
236+
{
237+
"embeds": [
238+
{
239+
"title": "📚 Documentation Updated",
240+
"description": "The Beet product documentation has been successfully updated and deployed!",
241+
"color": 3447003,
242+
"url": "https://alter-dimensions.github.io/beetween",
243+
"thumbnail": {
244+
"url": "https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png"
245+
},
246+
"fields": [
247+
{
248+
"name": "🔄 Latest Commit",
249+
"value": "**${{ steps.changes.outputs.commit_message }}**\nby ${{ steps.changes.outputs.commit_author }} (\`${{ steps.changes.outputs.commit_sha }}\`)",
250+
"inline": false
251+
},
252+
{
253+
"name": "📝 Changed Files",
254+
"value": "\`\`\`${{ steps.changes.outputs.changed_files }}\`\`\`",
255+
"inline": false
256+
},
257+
{
258+
"name": "📋 Recent Changes",
259+
"value": "${{ steps.changes.outputs.recent_commits }}",
260+
"inline": false
261+
},
262+
{
263+
"name": "🔗 Links",
264+
"value": "[📖 View Documentation](https://alter-dimensions.github.io/beetween) • [💻 View Commit](${{ steps.changes.outputs.commit_url }}) • [🔧 Repository](https://github.com/${{ github.repository }})",
265+
"inline": false
266+
}
267+
],
268+
"footer": {
269+
"text": "Beetween Documentation • Deployed via GitHub Actions",
270+
"icon_url": "https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png"
271+
},
272+
"timestamp": "$(date -u +%Y-%m-%dT%H:%M:%S.000Z)"
273+
}
274+
]
275+
}
276+
EOF
277+
278+
# Send the webhook
279+
curl -H "Content-Type: application/json" \
280+
-d @discord_payload.json \
281+
"$DISCORD_WEBHOOK_URL"

‎.gitignore‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Created by Poetry
2+
/dist/
3+
/site/
4+
/.venv/
5+
__pycache__/
6+
*.py[cod]
7+
*$py.class
8+
9+
# MkDocs
10+
/site/
11+
.cache/
12+
13+
# Environment files
14+
.env
15+
.env.local
16+
.env.*.local
17+
18+
# IDE
19+
.vscode/
20+
.idea/
21+
*.swp
22+
*.swo
23+
*~
24+
25+
# OS
26+
.DS_Store
27+
Thumbs.db
28+
29+
# Logs
30+
*.log
31+
32+
# Coverage
33+
htmlcov/
34+
.coverage
35+
.coverage.*
36+
coverage.xml
37+
38+
# pytest
39+
.pytest_cache/
40+
41+
# mypy
42+
.mypy_cache/
43+
.dmypy.json
44+
dmypy.json

‎.markdownlint.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"default": true,
3+
"MD013": false,
4+
"MD024": false,
5+
"MD033": true,
6+
"MD036": false,
7+
"MD040": false,
8+
"MD041": false,
9+
"MD046": false
10+
}

‎.pre-commit-config.yaml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
repos:
2+
# Basic file cleanup
3+
- repo: https://github.com/pre-commit/pre-commit-hooks
4+
rev: v4.4.0
5+
hooks:
6+
- id: trailing-whitespace
7+
- id: end-of-file-fixer
8+
- id: check-merge-conflict
9+
10+
# Single auto-formatter for markdown
11+
- repo: https://github.com/igorshubovych/markdownlint-cli
12+
rev: v0.37.0
13+
hooks:
14+
- id: markdownlint
15+
args: ["--fix", "--config", ".markdownlint.json"]
16+
files: \.(md|markdown)$

‎.python-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
3.11.9

0 commit comments

Comments
 (0)