From 9a6c776f8fb145a602bcfe9046955d0d2f268416 Mon Sep 17 00:00:00 2001 From: Aylur Date: Tue, 22 Oct 2024 18:43:17 +0000 Subject: docs: notifd doc comments --- lib/gir.py | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 lib/gir.py (limited to 'lib/gir.py') diff --git a/lib/gir.py b/lib/gir.py new file mode 100644 index 0000000..8ec786f --- /dev/null +++ b/lib/gir.py @@ -0,0 +1,43 @@ +""" +Vala's generated gir does not contain comments, +so we use valadoc to generate them. However, they are formatted +for valadoc and not gi-docgen so we need to fix it. +""" + +import xml.etree.ElementTree as ET +import html +import sys +import subprocess + + +def fix_gir(gir: str): + namespaces = { + "": "http://www.gtk.org/introspection/core/1.0", + "c": "http://www.gtk.org/introspection/c/1.0", + "glib": "http://www.gtk.org/introspection/glib/1.0", + } + for prefix, uri in namespaces.items(): + ET.register_namespace(prefix, uri) + + tree = ET.parse(gir) + root = tree.getroot() + + for doc in root.findall(".//doc", namespaces): + if doc.text: + doc.text = ( + html.unescape(doc.text).replace("", "").replace("", "") + ) + + tree.write(gir, encoding="utf-8", xml_declaration=True) + + +def valadoc(gir: str, args: list[str]): + subprocess.run(["valadoc", "-o", "docs", "--gir", gir, *args]) + + +if __name__ == "__main__": + gir = sys.argv[1] + args = sys.argv[2:] + + valadoc(gir, args) + fix_gir(gir) -- cgit v1.2.3 From 02fdcbe57155bd62c632a75e08087177b7c66eb9 Mon Sep 17 00:00:00 2001 From: Aylur Date: Tue, 22 Oct 2024 22:27:42 +0000 Subject: docs: fixup notifd and apps --- lib/gir.py | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) (limited to 'lib/gir.py') diff --git a/lib/gir.py b/lib/gir.py index 8ec786f..ccfbbc1 100644 --- a/lib/gir.py +++ b/lib/gir.py @@ -10,7 +10,7 @@ import sys import subprocess -def fix_gir(gir: str): +def fix_gir(name: str, gir: str): namespaces = { "": "http://www.gtk.org/introspection/core/1.0", "c": "http://www.gtk.org/introspection/c/1.0", @@ -28,16 +28,28 @@ def fix_gir(gir: str): html.unescape(doc.text).replace("", "").replace("", "") ) + if (inc := root.find("c:include", namespaces)) is not None: + inc.set("name", f"{name}.h") + else: + print("no c:include tag found", file=sys.stderr) + exit(1) + tree.write(gir, encoding="utf-8", xml_declaration=True) -def valadoc(gir: str, args: list[str]): - subprocess.run(["valadoc", "-o", "docs", "--gir", gir, *args]) +def valadoc(name: str, gir: str, args: list[str]): + cmd = ["valadoc", "-o", "docs", "--package-name", name, "--gir", gir, *args] + try: + subprocess.run(cmd, check=True, text=True, capture_output=True) + except subprocess.CalledProcessError as e: + print(e.stderr, file=sys.stderr) + exit(1) if __name__ == "__main__": - gir = sys.argv[1] - args = sys.argv[2:] + name = sys.argv[1] + gir = sys.argv[2] + args = sys.argv[3:] - valadoc(gir, args) - fix_gir(gir) + valadoc(name, gir, args) + fix_gir(name, gir) -- cgit v1.2.3 From 306e64998c1bf1fb997c1098ae92d6edfef31cd2 Mon Sep 17 00:00:00 2001 From: Aylur Date: Wed, 23 Oct 2024 20:37:32 +0000 Subject: docs: astal3 and io comments --- lib/gir.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'lib/gir.py') diff --git a/lib/gir.py b/lib/gir.py index ccfbbc1..9ef680f 100644 --- a/lib/gir.py +++ b/lib/gir.py @@ -10,7 +10,7 @@ import sys import subprocess -def fix_gir(name: str, gir: str): +def fix_gir(name: str, gir: str, out: str): namespaces = { "": "http://www.gtk.org/introspection/core/1.0", "c": "http://www.gtk.org/introspection/c/1.0", @@ -34,7 +34,7 @@ def fix_gir(name: str, gir: str): print("no c:include tag found", file=sys.stderr) exit(1) - tree.write(gir, encoding="utf-8", xml_declaration=True) + tree.write(out, encoding="utf-8", xml_declaration=True) def valadoc(name: str, gir: str, args: list[str]): @@ -48,8 +48,11 @@ def valadoc(name: str, gir: str, args: list[str]): if __name__ == "__main__": name = sys.argv[1] - gir = sys.argv[2] + in_out = sys.argv[2].split(":") args = sys.argv[3:] + gir = in_out[0] + out = in_out[1] if len(in_out) > 1 else gir + valadoc(name, gir, args) - fix_gir(name, gir) + fix_gir(name, gir, out) -- cgit v1.2.3 From e8715aec5e05e0438192e611afea2fe6f10cb80f Mon Sep 17 00:00:00 2001 From: Aylur Date: Fri, 25 Oct 2024 14:09:04 +0000 Subject: docs: battery doc comments --- lib/gir.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'lib/gir.py') diff --git a/lib/gir.py b/lib/gir.py index 9ef680f..a0a81dc 100644 --- a/lib/gir.py +++ b/lib/gir.py @@ -8,6 +8,15 @@ import xml.etree.ElementTree as ET import html import sys import subprocess +import re + + +# valac fails on gi-docgen compliant markdown +# gi-docgen removes valac compliant ulink +# so we use vala notation and turn it into markdown +def ulink_to_markdown(text: str): + pattern = r'(.*?)' + return re.sub(pattern, r"[\2](\1)", text) def fix_gir(name: str, gir: str, out: str): @@ -24,7 +33,7 @@ def fix_gir(name: str, gir: str, out: str): for doc in root.findall(".//doc", namespaces): if doc.text: - doc.text = ( + doc.text = ulink_to_markdown( html.unescape(doc.text).replace("", "").replace("", "") ) -- cgit v1.2.3