Skip to content

Commit fc96e5a

Browse files
sidey79sidey79
committed
docs: added examples
1 parent bbbca53 commit fc96e5a

15 files changed

Lines changed: 815 additions & 2 deletions

‎.github/workflows/docs.yml‎

Lines changed: 47 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,55 @@ jobs:
2424
with:
2525
version: 2.0.26
2626

27-
- name: run asciidoctor
27+
- name: run asciidoctor
2828
run: asciidoctor -R docs -D build/site/html -a docinfo=shared -a toc=left -a toclevels=2 'docs/index.adoc'
2929

30+
- name: Setup Python for Sitemap Generation
31+
uses: actions/setup-python@v5
32+
with:
33+
python-version: '3.11'
34+
35+
- name: Generate Sitemap
36+
id: generate-sitemap
37+
continue-on-error: true
38+
run: |
39+
python tools/generate_sitemap.py \
40+
--build-dir build/site/html \
41+
--output build/site/html/sitemap.xml \
42+
--branch ${{ github.ref_name }}
43+
env:
44+
GITHUB_REF: ${{ github.ref }}
45+
46+
- name: Copy robots.txt
47+
run: |
48+
# Branch-spezifische robots.txt generieren
49+
BRANCH="${{ github.ref_name }}"
50+
ROBOTS_SRC="docs/robots.txt"
51+
ROBOTS_DST="build/site/html/robots.txt"
52+
53+
cp "$ROBOTS_SRC" "$ROBOTS_DST"
54+
55+
# Sitemap-URL je nach Branch anpassen
56+
if [[ "$BRANCH" == "main" || "$BRANCH" == "gh-pages" ]]; then
57+
sed -i 's|Sitemap: .*|Sitemap: https://pysignalduino.rfd-fhem.github.io/sitemap.xml|' "$ROBOTS_DST"
58+
# Preview/Develop-Branches disallow
59+
echo -e "\n# Production branch - disallow preview/develop paths" >> "$ROBOTS_DST"
60+
echo "Disallow: /preview/" >> "$ROBOTS_DST"
61+
echo "Disallow: /develop/" >> "$ROBOTS_DST"
62+
echo "Disallow: /staging/" >> "$ROBOTS_DST"
63+
elif [[ "$BRANCH" == "preview" || "$BRANCH" == "gh-pages-preview" ]]; then
64+
sed -i 's|Sitemap: .*|Sitemap: https://preview.rfd-fhem.github.io/PySignalduino/sitemap.xml|' "$ROBOTS_DST"
65+
echo -e "\n# Preview branch - disallow preview path" >> "$ROBOTS_DST"
66+
echo "Disallow: /preview/" >> "$ROBOTS_DST"
67+
elif [[ "$BRANCH" == "develop" ]]; then
68+
sed -i 's|Sitemap: .*|Sitemap: https://develop.rfd-fhem.github.io/PySignalduino/sitemap.xml|' "$ROBOTS_DST"
69+
echo -e "\n# Develop branch - disallow develop path" >> "$ROBOTS_DST"
70+
echo "Disallow: /develop/" >> "$ROBOTS_DST"
71+
fi
72+
73+
echo "Generated robots.txt for branch: $BRANCH"
74+
cat "$ROBOTS_DST"
75+
3076
- name: Add CNAME file
3177
if: github.ref != 'refs/heads/main'
3278
run: echo 'preview.rfd-fhem.github.io' > "build/site/html/CNAME"

‎docs/02_developer_guide/architecture.adoc‎

Lines changed: 54 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,4 +110,57 @@ Die Architektur wurde von einer threading‑basierten Implementierung (Version 0
110110
* `async`/`await` in allen E/A‑Methoden
111111
* Asynchrone Kontextmanager für Ressourcenverwaltung
112112

113-
Details zur Migration sind im Dokument `ASYNCIO_MIGRATION.md` zu finden.
113+
Details zur Migration sind im Dokument `ASYNCIO_MIGRATION.md` zu finden.
114+
115+
== Dokumentations-Infrastruktur (Sitemap & SEO)
116+
117+
Die PySignalduino-Dokumentation wird automatisch mit einer dynamischen Sitemap und branch-spezifischen robots.txt-Dateien versehen, um die Auffindbarkeit in Suchmaschinen zu verbessern.
118+
119+
=== Sitemap-Generierung
120+
121+
Die Sitemap wird durch das Python-Skript `tools/generate_sitemap.py` generiert, das:
122+
123+
1. Den Build-Output-Ordner (`build/site/html`) nach HTML-Dateien scannt
124+
2. Prioritäten (0.1–1.0) und Update-Frequenzen (`changefreq`) basierend auf Dateipfaden zuweist
125+
3. Branch-spezifische Base-URLs unterstützt (main: `pysignalduino.rfd-fhem.github.io`, preview: `preview.rfd-fhem.github.io`)
126+
4. Gültige XML-Sitemap gemäß sitemaps.org-Schema generiert
127+
5. Fehlerbehandlung und Logging enthält
128+
129+
Das Skript kann manuell ausgeführt werden:
130+
131+
```bash
132+
python tools/generate_sitemap.py --build-dir build/site/html --output sitemap.xml --branch main
133+
```
134+
135+
=== robots.txt-Konfiguration
136+
137+
Die Datei `docs/robots.txt` wird im CI/CD-Workflow branch-spezifisch angepasst:
138+
139+
* **main-Branch:** Erlaubt Crawling aller Pfade, schließt Preview-/Develop-Pfade aus
140+
* **preview-Branch:** Verbietet Crawling des `/preview/`-Pfads
141+
* **develop-Branch:** Verbietet Crawling des `/develop/`-Pfads
142+
143+
Zusätzlich wird ein `Crawl-delay: 2` gesetzt, um Serverlast zu reduzieren.
144+
145+
=== Integration in den CI/CD-Workflow
146+
147+
Der GitHub Actions Workflow `.github/workflows/docs.yml` wurde erweitert, um:
148+
149+
1. Nach dem Asciidoctor-Build das Sitemap-Generierungsskript auszuführen
150+
2. Die robots.txt in das Ausgabeverzeichnis zu kopieren und branch-spezifisch anzupassen
151+
3. Bei Fehlern der Sitemap-Generierung nicht den gesamten Build fehlschlagen zu lassen (`continue-on-error: true`)
152+
153+
=== Statische Fallback-Dateien
154+
155+
Für den Fall, dass die dynamische Generierung fehlschlägt, stehen statische Vorlagen bereit:
156+
157+
* `docs/sitemap_template.xml` – Grundlegende Sitemap mit den wichtigsten URLs
158+
* `docs/robots.txt` – Generische robots.txt-Vorlage
159+
160+
Diese Dateien werden automatisch durch den CI/CD-Workflow verwendet.
161+
162+
=== SEO-Empfehlungen
163+
164+
* Die Sitemap wird unter `https://pysignalduino.rfd-fhem.github.io/sitemap.xml` verfügbar sein
165+
* Die robots.txt wird unter `https://pysignalduino.rfd-fhem.github.io/robots.txt` verfügbar sein
166+
* Es wird empfohlen, die Sitemap in der Google Search Console und Bing Webmaster Tools einzureichen

‎docs/examples/bash/coverage_report.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pytest --cov=signalduino --cov-report=html

‎docs/examples/bash/format_code.sh‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
black signalduino/ tests/
2+
ruff check signalduino/ tests/ --fix

‎docs/examples/bash/install_dev_deps.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pip install -r requirements-dev.txt

‎docs/examples/bash/install_dev_requirements.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pip install -r requirements-dev.txt

‎docs/examples/bash/install_requirements.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pip install -r requirements.txt

‎docs/examples/bash/install_via_pip.sh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
git clone https://github.com/Ein-Einfaches-Beispiel/PySignalduino.git
2+
cd PySignalduino
3+
pip install -e .

‎docs/examples/bash/mosquitto_pub_example.sh‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Firmware-Version abfragen
2+
mosquitto_pub -t "signalduino/commands/version" -m "GET"
3+
4+
# Empfänger aktivieren
5+
mosquitto_pub -t "signalduino/commands/set/XE" -m "1"

‎docs/examples/bash/run_pytest.sh‎

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

0 commit comments

Comments
 (0)