Skip to content

Commit abe046f

Browse files
matheusvnmmatheusvnm
committed
docs: iterating over different docs formats
1 parent a9c3901 commit abe046f

File tree

77 files changed

+12706
-8747
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

77 files changed

+12706
-8747
lines changed

‎.github/workflows/release-notes.yml‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
name: Update Release Notes
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
permissions:
8+
contents: write
9+
10+
jobs:
11+
update-release-notes:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v5
15+
with:
16+
ref: main
17+
fetch-depth: 0
18+
19+
- name: Setup Python
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: '3.12'
23+
24+
- name: Generate Release Notes
25+
env:
26+
RELEASE_TAG: ${{ github.event.release.tag_name }}
27+
RELEASE_NAME: ${{ github.event.release.name }}
28+
RELEASE_BODY: ${{ github.event.release.body }}
29+
RELEASE_URL: ${{ github.event.release.html_url }}
30+
RELEASE_DATE: ${{ github.event.release.published_at }}
31+
run: |
32+
python << 'EOF'
33+
import os
34+
from datetime import datetime
35+
36+
tag = os.environ.get('RELEASE_TAG', '')
37+
name = os.environ.get('RELEASE_NAME', tag)
38+
body = os.environ.get('RELEASE_BODY', '')
39+
url = os.environ.get('RELEASE_URL', '')
40+
date_str = os.environ.get('RELEASE_DATE', '')
41+
42+
# Parse date
43+
if date_str:
44+
date = datetime.fromisoformat(date_str.replace('Z', '+00:00'))
45+
formatted_date = date.strftime('%Y-%m-%d')
46+
else:
47+
formatted_date = datetime.now().strftime('%Y-%m-%d')
48+
49+
# Read existing release notes
50+
release_notes_path = 'docs/src/about/release-notes.md'
51+
with open(release_notes_path, 'r') as f:
52+
content = f.read()
53+
54+
# Create new release entry
55+
new_entry = f"""
56+
## [{tag}]({url}) - {formatted_date}
57+
58+
{body}
59+
60+
---
61+
"""
62+
63+
# Insert after "## Version History" section
64+
marker = "## Version History"
65+
if marker in content:
66+
parts = content.split(marker, 1)
67+
# Find the next section after marker
68+
after_marker = parts[1]
69+
# Insert new entry after the info block
70+
if "!!! info" in after_marker:
71+
info_end = after_marker.find("\n\n## ")
72+
if info_end == -1:
73+
info_end = after_marker.find("\n\n---")
74+
if info_end == -1:
75+
# No existing releases, add after info block
76+
content = parts[0] + marker + after_marker + "\n" + new_entry
77+
else:
78+
# Insert before first existing release
79+
content = parts[0] + marker + after_marker[:info_end+2] + new_entry + after_marker[info_end+2:]
80+
else:
81+
content = parts[0] + marker + "\n" + new_entry + after_marker
82+
else:
83+
# No marker found, append at end
84+
content += "\n" + new_entry
85+
86+
with open(release_notes_path, 'w') as f:
87+
f.write(content)
88+
89+
print(f"Updated release notes with {tag}")
90+
EOF
91+
92+
- name: Commit and Push
93+
run: |
94+
git config --local user.email "github-actions[bot]@users.noreply.github.com"
95+
git config --local user.name "github-actions[bot]"
96+
git add docs/src/about/release-notes.md
97+
git diff --cached --quiet || git commit -m "docs: update release notes for ${{ github.event.release.tag_name }}"
98+
git push

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

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
name: Test Documentation
2+
3+
on:
4+
push:
5+
paths:
6+
- 'docs/src/snippets/**/*.py'
7+
- 'docs/src/**/*.md'
8+
- '.github/workflows/test-docs.yml'
9+
pull_request:
10+
paths:
11+
- 'docs/src/snippets/**/*.py'
12+
- 'docs/src/**/*.md'
13+
- '.github/workflows/test-docs.yml'
14+
15+
jobs:
16+
validate-snippets:
17+
name: Validate Code Snippets
18+
runs-on: ubuntu-latest
19+
steps:
20+
- uses: actions/checkout@v5
21+
22+
- name: Setup Python
23+
uses: actions/setup-python@v5
24+
with:
25+
python-version: '3.12'
26+
27+
- name: Install dependencies
28+
run: |
29+
pip install -e ".[dev]"
30+
31+
- name: Check Python syntax
32+
run: |
33+
echo "Checking Python syntax in docs/src/snippets/"
34+
python -m py_compile docs/src/snippets/**/*.py
35+
echo "All snippets have valid Python syntax"
36+
37+
- name: Run snippet imports
38+
run: |
39+
echo "Verifying all snippets can be imported"
40+
python << 'EOF'
41+
import importlib.util
42+
import sys
43+
from pathlib import Path
44+
45+
snippets_dir = Path("docs/src/snippets")
46+
errors = []
47+
48+
for py_file in snippets_dir.rglob("*.py"):
49+
if py_file.name == "__init__.py":
50+
continue
51+
52+
module_name = py_file.stem
53+
spec = importlib.util.spec_from_file_location(module_name, py_file)
54+
55+
if spec and spec.loader:
56+
try:
57+
module = importlib.util.module_from_spec(spec)
58+
# Don't execute, just verify it can be loaded
59+
print(f"✓ {py_file.relative_to(snippets_dir)}")
60+
except Exception as e:
61+
errors.append(f"✗ {py_file.relative_to(snippets_dir)}: {e}")
62+
63+
if errors:
64+
print("\nErrors found:")
65+
for error in errors:
66+
print(error)
67+
sys.exit(1)
68+
else:
69+
print(f"\nAll {len(list(snippets_dir.rglob('*.py')))} snippets validated successfully")
70+
EOF
71+
72+
build-docs:
73+
name: Build Documentation
74+
runs-on: ubuntu-latest
75+
steps:
76+
- uses: actions/checkout@v5
77+
78+
- name: Setup Python
79+
uses: actions/setup-python@v5
80+
with:
81+
python-version: '3.12'
82+
83+
- name: Install Zensical
84+
run: pip install zensical
85+
86+
- name: Build documentation
87+
run: |
88+
cd docs
89+
zensical build --clean
90+
echo "Documentation built successfully"
91+
92+
- name: Check for broken internal links
93+
run: |
94+
echo "Checking for broken links in documentation"
95+
python << 'EOF'
96+
import re
97+
from pathlib import Path
98+
99+
docs_dir = Path("docs/src")
100+
errors = []
101+
102+
# Pattern to match markdown links
103+
link_pattern = re.compile(r'\[([^\]]+)\]\(([^)]+)\)')
104+
105+
for md_file in docs_dir.rglob("*.md"):
106+
content = md_file.read_text()
107+
108+
for match in link_pattern.finditer(content):
109+
link_text, link_url = match.groups()
110+
111+
# Skip external links
112+
if link_url.startswith(('http://', 'https://', '#', 'mailto:')):
113+
continue
114+
115+
# Resolve relative path
116+
if link_url.startswith('../'):
117+
target = (md_file.parent / link_url).resolve()
118+
else:
119+
target = (md_file.parent / link_url).resolve()
120+
121+
# Remove anchor if present
122+
target_path = str(target).split('#')[0]
123+
124+
if not Path(target_path).exists():
125+
errors.append(f"{md_file.relative_to(docs_dir)}: broken link '{link_url}'")
126+
127+
if errors:
128+
print("Broken links found:")
129+
for error in errors:
130+
print(f" ✗ {error}")
131+
# Warning only, don't fail the build
132+
print(f"\nFound {len(errors)} broken links (warning only)")
133+
else:
134+
print("No broken links found")
135+
EOF

‎docs/site/404.html‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -308,7 +308,7 @@
308308

309309

310310
<li class="md-tabs__item">
311-
<a href="/" class="md-tabs__link">
311+
<a href="/about/release-notes/" class="md-tabs__link">
312312

313313

314314
Release Notes
@@ -1718,12 +1718,10 @@
17181718

17191719

17201720
<li class="md-nav__item">
1721-
<a href="/" class="md-nav__link">
1721+
<a href="/about/release-notes/" class="md-nav__link">
17221722

17231723

17241724

1725-
<svg xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" class="lucide lucide-zap" viewBox="0 0 24 24"><path d="M4 14a1 1 0 0 1-.78-1.63l9.9-10.2a.5.5 0 0 1 .86.46l-1.92 6.02A1 1 0 0 0 13 10h7a1 1 0 0 1 .78 1.63l-9.9 10.2a.5.5 0 0 1-.86-.46l1.92-6.02A1 1 0 0 0 11 14z"/></svg>
1726-
17271725
<span class="md-ellipsis">
17281726

17291727

‎docs/site/about/project/index.html‎

Lines changed: 7 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -321,7 +321,7 @@
321321

322322

323323
<li class="md-tabs__item">
324-
<a href="../.." class="md-tabs__link">
324+
<a href="../release-notes/" class="md-tabs__link">
325325

326326

327327
Release Notes
@@ -1772,17 +1772,6 @@
17721772
</span>
17731773
</a>
17741774

1775-
</li>
1776-
1777-
<li class="md-nav__item">
1778-
<a href="#in-this-section" class="md-nav__link">
1779-
<span class="md-ellipsis">
1780-
1781-
In This Section
1782-
1783-
</span>
1784-
</a>
1785-
17861775
</li>
17871776

17881777
</ul>
@@ -1846,12 +1835,10 @@
18461835

18471836

18481837
<li class="md-nav__item">
1849-
<a href="../.." class="md-nav__link">
1838+
<a href="../release-notes/" class="md-nav__link">
18501839

18511840

18521841

1853-
<svg xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" class="lucide lucide-zap" viewBox="0 0 24 24"><path d="M4 14a1 1 0 0 1-.78-1.63l9.9-10.2a.5.5 0 0 1 .86.46l-1.92 6.02A1 1 0 0 0 13 10h7a1 1 0 0 1 .78 1.63l-9.9 10.2a.5.5 0 0 1-.86-.46l1.92-6.02A1 1 0 0 0 11 14z"/></svg>
1854-
18551842
<span class="md-ellipsis">
18561843

18571844

@@ -1937,17 +1924,6 @@
19371924
</span>
19381925
</a>
19391926

1940-
</li>
1941-
1942-
<li class="md-nav__item">
1943-
<a href="#in-this-section" class="md-nav__link">
1944-
<span class="md-ellipsis">
1945-
1946-
In This Section
1947-
1948-
</span>
1949-
</a>
1950-
19511927
</li>
19521928

19531929
</ul>
@@ -2042,36 +2018,31 @@
20422018

20432019

20442020

2045-
<h1 id="about-fastpubsub">About FastPubSub<a class="headerlink" href="#about-fastpubsub" title="Permanent link">&para;</a></h1>
2021+
<h1 id="about-fastpubsub">About FastPubSub</h1>
20462022
<p>FastPubSub is a modern, high-performance framework for building applications that process event messages on Google Cloud Pub/Sub.</p>
2047-
<h2 id="project-goals">Project Goals<a class="headerlink" href="#project-goals" title="Permanent link">&para;</a></h2>
2023+
<h2 id="project-goals">Project Goals</h2>
20482024
<p>FastPubSub was created to simplify the development of Pub/Sub consumers by:</p>
20492025
<ul>
20502026
<li>Handling the complexities of asynchronous message processing</li>
20512027
<li>Providing an intuitive, decorator-based API for defining subscribers and publishers</li>
20522028
<li>Integrating seamlessly with FastAPI for hybrid REST + Pub/Sub applications</li>
20532029
<li>Offering production-ready features out of the box</li>
20542030
</ul>
2055-
<h2 id="design-philosophy">Design Philosophy<a class="headerlink" href="#design-philosophy" title="Permanent link">&para;</a></h2>
2031+
<h2 id="design-philosophy">Design Philosophy</h2>
20562032
<ul>
20572033
<li><strong>Developer Experience First</strong>: Simple, intuitive APIs that feel natural to Python developers</li>
20582034
<li><strong>Performance</strong>: Built on asyncio for high-throughput, concurrent message processing</li>
20592035
<li><strong>Production Ready</strong>: Built-in health checks, structured logging, and graceful shutdown</li>
20602036
<li><strong>Flexible</strong>: Support for dead-letter topics, filtering, ordering, and exactly-once delivery</li>
20612037
</ul>
2062-
<h2 id="links">Links<a class="headerlink" href="#links" title="Permanent link">&para;</a></h2>
2038+
<h2 id="links">Links</h2>
20632039
<ul>
20642040
<li><strong>GitHub</strong>: <a href="https://github.com/matheusvnm/fastpubsub">github.com/matheusvnm/fastpubsub</a></li>
20652041
<li><strong>PyPI</strong>: <a href="https://pypi.org/project/fastpubsub/">pypi.org/project/fastpubsub</a></li>
20662042
<li><strong>Issues</strong>: <a href="https://github.com/matheusvnm/fastpubsub/issues">GitHub Issues</a></li>
20672043
</ul>
2068-
<h2 id="license">License<a class="headerlink" href="#license" title="Permanent link">&para;</a></h2>
2044+
<h2 id="license">License</h2>
20692045
<p>FastPubSub is open source software licensed under the <a href="https://github.com/matheusvnm/fastpubsub/blob/master/LICENSE">Apache 2.0 License</a>.</p>
2070-
<hr />
2071-
<h2 id="in-this-section">In This Section<a class="headerlink" href="#in-this-section" title="Permanent link">&para;</a></h2>
2072-
<ul>
2073-
<li><a href="../versions/">Versions</a> - Version management and upgrade guidelines</li>
2074-
</ul>
20752046

20762047

20772048

0 commit comments

Comments
 (0)