From aff1a5023e382ef7401f795b68ad7c587f87aca3 Mon Sep 17 00:00:00 2001 From: Bouni Date: Thu, 12 Dec 2024 10:15:25 +0100 Subject: [PATCH 1/6] First attempt to auto generate docs --- .github/workflows/docs.yml | 43 +++++++ .github/workflows/scripts/docs/gen-docs.py | 43 +++++++ .../scripts/docs/templates/docs.jinja | 105 ++++++++++++++++++ 3 files changed, 191 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 .github/workflows/scripts/docs/gen-docs.py create mode 100644 .github/workflows/scripts/docs/templates/docs.jinja diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..58c50593 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,43 @@ +name: Deploy static content to Pages + +on: + push: + branches: ["main"] + + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Install uv + uses: astral-sh/setup-uv@v4 + - name: Set up Python + run: uv python install + - name: Install dependencies + run: uv pip install jinja2 + - name: Generate docs + run: uv run python .github/workflows/scripts/docs/gen-docs.py + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/scripts/docs/gen-docs.py b/.github/workflows/scripts/docs/gen-docs.py new file mode 100644 index 00000000..547b8203 --- /dev/null +++ b/.github/workflows/scripts/docs/gen-docs.py @@ -0,0 +1,43 @@ +#!/usr/bin/env python +import logging +import re +from pathlib import Path +from typing import Literal + +from jinja2 import Environment, FileSystemLoader, select_autoescape + +logging.basicConfig(level=logging.INFO) + +logger = logging.getLogger("doc-gen") + +BASEPATH = Path(__file__).resolve().parent + + +def parse_group(group: Literal["calculations", "parameters", "visibilities"]) -> list[dict]: + logger.info("parse group '%s'", group) + data = [] + with open(BASEPATH.parents[3] / f"luxtronik/{group}.py") as f: + raw = f.read() + regex = re.compile(r"(?P\d+):\s+(?P[^(]+)\(\"(?P[^\"]+)\"\)") + results = [m.groupdict() for m in regex.finditer(raw)] + logger.info("found %d entries", len(results)) + for r in results: + data.append({"number": r["number"], "type": r["type"], "name": r["name"]}) + return data + + +def render_docs(): + logger.info("render docs") + env = Environment(loader=FileSystemLoader(str(BASEPATH / "templates")), autoescape=select_autoescape()) + template = env.get_template("docs.jinja") + group_data = {} + for g in ("calculations", "parameters", "visibilities"): + group_data[g] = parse_group(g) + (BASEPATH.parents[3] / "docs").mkdir(exist_ok=True) + with open(BASEPATH.parents[3] / "docs/index.html", "w", encoding="UTF-8") as f: + f.write(template.render(data=group_data)) + + +if __name__ == "__main__": + print(BASEPATH) + render_docs() diff --git a/.github/workflows/scripts/docs/templates/docs.jinja b/.github/workflows/scripts/docs/templates/docs.jinja new file mode 100644 index 00000000..5001a5f1 --- /dev/null +++ b/.github/workflows/scripts/docs/templates/docs.jinja @@ -0,0 +1,105 @@ + + + + python-luxtronik docs + + + +
+
+
+

python-luxtronik docs

+

+ Latest info about calculations, parameters and visibilities of + python-luxtronik +

+
+
+
+ +
+ {% for group, items in data.items() %} +
+

+ {{ group.capitalize() }} +

+
+ {% for item in items %} +
+
+
+

+ {{ item.name }} +

+
+

Group: {{ group }}

+

Name: {{ item.name }}

+

Number: {{ item.number }}

+

Type: {{ item.type }}

+
+

+ Usage example in Home-Assitant config: +

+ 
+sensor:
+  - platform: luxtronik
+    sensors:
+      - group: {{ group }}
+        id: {{ item.name }}
+
+ +

or

+ + 
+sensor:
+  - platform: luxtronik
+    sensors:
+      - group: {{ group }}
+        id: {{ item.number }}
+
+
+
+
+
+
+ {% endfor %} +
+
+ {% endfor %} +
+ + + From 65813b3d223c3d35e154e218c1471c3949d7b752 Mon Sep 17 00:00:00 2001 From: Bouni Date: Thu, 12 Dec 2024 10:18:52 +0100 Subject: [PATCH 2/6] Comment branch constraint for testing purposes --- .github/workflows/docs.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 58c50593..ed0e7e86 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -2,8 +2,7 @@ name: Deploy static content to Pages on: push: - branches: ["main"] - + # branches: ["main"] workflow_dispatch: permissions: From 14b9bb30b4e723b488d766b98dbeba324e8a2693 Mon Sep 17 00:00:00 2001 From: Bouni Date: Thu, 12 Dec 2024 10:20:26 +0100 Subject: [PATCH 3/6] Trigger CI From 6ea6dfbf16b64b720499e7571b7c309b63f3c3df Mon Sep 17 00:00:00 2001 From: Bouni Date: Thu, 12 Dec 2024 10:21:30 +0100 Subject: [PATCH 4/6] Add uv venv --- .github/workflows/docs.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ed0e7e86..76f14ddb 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -28,7 +28,9 @@ jobs: - name: Set up Python run: uv python install - name: Install dependencies - run: uv pip install jinja2 + run: | + uv venv + uv pip install jinja2 - name: Generate docs run: uv run python .github/workflows/scripts/docs/gen-docs.py - name: Setup Pages From d5ba3f0ae714c6b93a39afb3420ecdcaa590080d Mon Sep 17 00:00:00 2001 From: Bouni Date: Mon, 16 Dec 2024 08:58:06 +0100 Subject: [PATCH 5/6] Import instead of regex --- .github/workflows/docs.yml | 1 + .github/workflows/scripts/docs/gen-docs.py | 54 +++++++++++++++------- 2 files changed, 39 insertions(+), 16 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 76f14ddb..278a1908 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -31,6 +31,7 @@ jobs: run: | uv venv uv pip install jinja2 + uv pip install -e . - name: Generate docs run: uv run python .github/workflows/scripts/docs/gen-docs.py - name: Setup Pages diff --git a/.github/workflows/scripts/docs/gen-docs.py b/.github/workflows/scripts/docs/gen-docs.py index 547b8203..d73ba284 100644 --- a/.github/workflows/scripts/docs/gen-docs.py +++ b/.github/workflows/scripts/docs/gen-docs.py @@ -1,43 +1,65 @@ #!/usr/bin/env python import logging -import re from pathlib import Path -from typing import Literal from jinja2 import Environment, FileSystemLoader, select_autoescape +from luxtronik.calculations import Calculations +from luxtronik.parameters import Parameters +from luxtronik.visibilities import Visibilities + logging.basicConfig(level=logging.INFO) logger = logging.getLogger("doc-gen") + BASEPATH = Path(__file__).resolve().parent -def parse_group(group: Literal["calculations", "parameters", "visibilities"]) -> list[dict]: - logger.info("parse group '%s'", group) - data = [] - with open(BASEPATH.parents[3] / f"luxtronik/{group}.py") as f: - raw = f.read() - regex = re.compile(r"(?P\d+):\s+(?P[^(]+)\(\"(?P[^\"]+)\"\)") - results = [m.groupdict() for m in regex.finditer(raw)] - logger.info("found %d entries", len(results)) - for r in results: - data.append({"number": r["number"], "type": r["type"], "name": r["name"]}) +# for no, parameter in p._data.items(): +# print(no, parameter.name) + + +def gather_data() -> dict: + p = Parameters() + c = Calculations() + v = Visibilities() + data = {"parameters": [], "calculations": [], "visibilities": []} + for number, parameter in p._data.items(): + data["parameters"].append({"number": number, "type": parameter.__class__.__name__, "name": parameter.name}) + for number, calculation in c._data.items(): + data["calculations"].append( + {"number": number, "type": calculation.__class__.__name__, "name": calculation.name} + ) + for number, visibility in v._data.items(): + data["visibilities"].append({"number": number, "type": visibility.__class__.__name__, "name": visibility.name}) return data +# def parse_group(group: Literal["calculations", "parameters", "visibilities"]) -> list[dict]: +# logger.info("parse group '%s'", group) +# data = [] +# with open(BASEPATH.parents[3] / f"luxtronik/{group}.py") as f: +# raw = f.read() +# regex = re.compile(r"(?P\d+):\s+(?P[^(]+)\(\"(?P[^\"]+)\"\)") +# results = [m.groupdict() for m in regex.finditer(raw)] +# logger.info("found %d entries", len(results)) +# for r in results: +# data.append({"number": r["number"], "type": r["type"], "name": r["name"]}) +# return data +# +# def render_docs(): logger.info("render docs") env = Environment(loader=FileSystemLoader(str(BASEPATH / "templates")), autoescape=select_autoescape()) template = env.get_template("docs.jinja") - group_data = {} - for g in ("calculations", "parameters", "visibilities"): - group_data[g] = parse_group(g) + group_data = gather_data() (BASEPATH.parents[3] / "docs").mkdir(exist_ok=True) with open(BASEPATH.parents[3] / "docs/index.html", "w", encoding="UTF-8") as f: f.write(template.render(data=group_data)) +# + if __name__ == "__main__": - print(BASEPATH) render_docs() From 1872ac9d4eec9c97baf9574a533f305610ef78fe Mon Sep 17 00:00:00 2001 From: Bouni Date: Mon, 16 Dec 2024 09:02:09 +0100 Subject: [PATCH 6/6] =?UTF-8?q?Cleanup=20=F0=9F=A7=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/scripts/docs/gen-docs.py | 22 ++-------------------- 1 file changed, 2 insertions(+), 20 deletions(-) diff --git a/.github/workflows/scripts/docs/gen-docs.py b/.github/workflows/scripts/docs/gen-docs.py index d73ba284..df4f98c1 100644 --- a/.github/workflows/scripts/docs/gen-docs.py +++ b/.github/workflows/scripts/docs/gen-docs.py @@ -10,17 +10,14 @@ logging.basicConfig(level=logging.INFO) -logger = logging.getLogger("doc-gen") +logger = logging.getLogger("docs generator") BASEPATH = Path(__file__).resolve().parent -# for no, parameter in p._data.items(): -# print(no, parameter.name) - - def gather_data() -> dict: + logger.info("gather docs data") p = Parameters() c = Calculations() v = Visibilities() @@ -36,19 +33,6 @@ def gather_data() -> dict: return data -# def parse_group(group: Literal["calculations", "parameters", "visibilities"]) -> list[dict]: -# logger.info("parse group '%s'", group) -# data = [] -# with open(BASEPATH.parents[3] / f"luxtronik/{group}.py") as f: -# raw = f.read() -# regex = re.compile(r"(?P\d+):\s+(?P[^(]+)\(\"(?P[^\"]+)\"\)") -# results = [m.groupdict() for m in regex.finditer(raw)] -# logger.info("found %d entries", len(results)) -# for r in results: -# data.append({"number": r["number"], "type": r["type"], "name": r["name"]}) -# return data -# -# def render_docs(): logger.info("render docs") env = Environment(loader=FileSystemLoader(str(BASEPATH / "templates")), autoescape=select_autoescape()) @@ -59,7 +43,5 @@ def render_docs(): f.write(template.render(data=group_data)) -# - if __name__ == "__main__": render_docs()