Skip to content

First attempt to auto generate docs #192

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

First attempt to auto generate docs #192

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
aff1a50
First attempt to auto generate docs
Bouni Dec 12, 2024
65813b3
Comment branch constraint for testing purposes
Bouni Dec 12, 2024
14b9bb3
Trigger CI
Bouni Dec 12, 2024
6ea6dfb
Add uv venv
Bouni Dec 12, 2024
d5ba3f0
Import instead of regex
Bouni Dec 16, 2024
1872ac9
Cleanup 🧹
Bouni Dec 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions .github/workflows/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
name: Deploy static content to Pages

Check warning on line 1 in .github/workflows/docs.yml

View workflow job for this annotation

GitHub Actions / yamllint 

1:1 [document-start] missing document start "---"

on:

Check warning on line 3 in .github/workflows/docs.yml

View workflow job for this annotation

GitHub Actions / yamllint 

3:1 [truthy] truthy value should be one of [false, true]
push:
# branches: ["main"]

Check warning on line 5 in .github/workflows/docs.yml

View workflow job for this annotation

GitHub Actions / yamllint 

5:5 [comments-indentation] comment not indented like content
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 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
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
47 changes: 47 additions & 0 deletions .github/workflows/scripts/docs/gen-docs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
#!/usr/bin/env python
import logging
from pathlib import Path

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("docs generator")


BASEPATH = Path(__file__).resolve().parent


def gather_data() -> dict:
logger.info("gather docs data")
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 render_docs():
logger.info("render docs")
env = Environment(loader=FileSystemLoader(str(BASEPATH / "templates")), autoescape=select_autoescape())
template = env.get_template("docs.jinja")
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__":
render_docs()
105 changes: 105 additions & 0 deletions .github/workflows/scripts/docs/templates/docs.jinja
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
<!doctype html>
<html lang="en">
<head>
<title>python-luxtronik docs</title>
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/[email protected]/css/bulma.min.css"
/>
</head>
<body>
<div class="container">
<section class="hero">
<div class="hero-body">
<p class="title">python-luxtronik docs</p>
<p class="subtitle">
Latest info about calculations, parameters and visibilities of
python-luxtronik
</p>
</div>
</section>
<section>
<input class="input search" type="text" placeholder="Search" />
</section>
{% for group, items in data.items() %}
<section class="section">
<h1 class="title" id="{{ group }}">
<a href="#{{group}}">{{ group.capitalize() }}</a>
</h1>
<div class="columns is-multiline">
{% for item in items %}
<div
class="column is-full item"
data-name="{{ item.name }}"
data-number="{{ item.number }}"
data-type="{{ item.type }}"
>
<div class="card" id="{{ group }}-{{ item.name }}">
<div class="card-content">
<p class="title is-4">
<a href="#{{ group }}-{{ item.name }}">{{ item.name }}</a>
</p>
<div class="content">
<p>Group: {{ group }}</p>
<p>Name: {{ item.name }}</p>
<p>Number: {{ item.number }}</p>
<p>Type: {{ item.type }}</p>
<div>
<p class="title is-6">
Usage example in Home-Assitant config:
</p>
<pre>
<!-- -->sensor:
<!-- --> - platform: luxtronik
<!-- --> sensors:
<!-- --> - group: {{ group }}
<!-- --> id: {{ item.name }}
</pre>

<p>or</p>

<pre>
<!-- -->sensor:
<!-- --> - platform: luxtronik
<!-- --> sensors:
<!-- --> - group: {{ group }}
<!-- --> id: {{ item.number }}
</pre>
</div>
</div>
</div>
</div>
</div>
{% endfor %}
</div>
</section>
{% endfor %}
</div>
<script lang="javascript">
const searchbar = document.querySelector(".search");

searchbar.addEventListener("keyup", () => {
let searchword = searchbar.value.toString().toLowerCase();
if (searchword.length < 1) {
let items = document.querySelectorAll(".item");
Array.from(items, (el) => {
el.style.display = "block";
});
} else {
let items = document.querySelectorAll(".item");
Array.from(items, (el) => {
if (
!el.dataset.type.toLowerCase().includes(searchword) &&
!el.dataset.number.toString().toLowerCase().includes(searchword) &&
!el.dataset.name.toLowerCase().includes(searchword)
) {
el.style.display = "none";
} else {
el.style.display = "block";
}
});
}
});
</script>
</body>
</html>
Loading