luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-13 15:56:23 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'ebassi/gdbus-codegen-rst' into 'main'

Browse Source 
Add reStructuredText documentation generator for gdbus-codegen

See merge request GNOME/glib!2448
This commit is contained in:
Emmanuele Bassi 2022-01-22 02:08:39 +00:00
commit 89c1ab2cce
8 changed files with 454 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
docs/reference/gio/gdbus-codegen.xml
View File

@ -35,6 +35,7 @@
<arg><option>--c-generate-autocleanup</option> none|objects|all</arg>
<arg><option>--output-directory</option> <replaceable>OUTDIR</replaceable></arg>
<arg><option>--generate-docbook</option> <replaceable>OUTFILES</replaceable></arg>
<arg><option>--generate-rst</option> <replaceable>OUTFILES</replaceable></arg>
<arg><option>--pragma-once</option></arg>
<arg><option>--xml-files</option> <replaceable>FILE</replaceable></arg>
<arg><option>--header</option></arg>
@ -168,6 +169,16 @@
</para>
</refsect1>
<refsect1>
<title>Generating reStructuredText documentation</title>
<para>
Each generated reStructuredText file (see the
<option>--generate-rst</option> option for details) is a plain text
<ulink url="https://docutils.sourceforge.io/rst.html">reStructuredText</ulink>
document describing the D-Bus interface.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
@ -212,8 +223,25 @@
<listitem>
<para>
Generate Docbook Documentation for each D-Bus interface and
put it in <filename>OUTFILES-NAME.xml</filename> where
<literal>NAME</literal> is a place-holder for the interface
put it in <filename><replaceable>OUTFILES</replaceable>-<replaceable>NAME</replaceable>.xml</filename>
where <literal>NAME</literal> is a place-holder for the interface
name, e.g. <literal>net.Corp.FooBar</literal> and so on.
</para>
<para>
Pass <option>--output-directory</option> to specify the directory
to put the output files in. By default the current directory
will be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-rst</option> <replaceable>OUTFILES</replaceable></term>
<listitem>
<para>
Generate reStructuredText Documentation for each D-Bus interface and
put it in <filename><replaceable>OUTFILES</replaceable>-<replaceanle>NAME</replaceanle>.rst</filename>
where <literal>NAME</literal> is a place-holder for the interface
name, e.g. <literal>net.Corp.FooBar</literal> and so on.
</para>
<para>

12
gio/gdbus-2.0/codegen/codegen_docbook.py
View File

@ -345,9 +345,17 @@ class DocbookCodeGenerator:
def expand_paras(self, s, expandParamsAndConstants):
s = self.expand(s, expandParamsAndConstants).strip()
res = []
if not s.startswith("<para"):
s = "<para>%s</para>" % s
return s
res.append("<para>")
for line in s.split("\n"):
line = line.strip()
if not line:
line = "</para><para>"
res.append(line)
if not s.endswith("</para>"):
res.append("</para>")
return "\n".join(res)
def generate_expand_dicts(self):
self.expand_member_dict = {}

17
gio/gdbus-2.0/codegen/codegen_main.py
View File

@ -30,6 +30,7 @@ from . import dbustypes
from . import parser
from . import codegen
from . import codegen_docbook
from . import codegen_rst
from .utils import print_error, print_warning
@ -211,6 +212,11 @@ def codegen_main():
metavar="OUTFILES",
help="Generate Docbook in OUTFILES-org.Project.IFace.xml",
)
arg_parser.add_argument(
"--generate-rst",
metavar="OUTFILES",
help="Generate reStructuredText in OUTFILES-org.Project.IFace.rst",
)
arg_parser.add_argument(
"--pragma-once",
action="store_true",
@ -287,10 +293,12 @@ def codegen_main():
)
if (
args.generate_c_code is not None or args.generate_docbook is not None
args.generate_c_code is not None
or args.generate_docbook is not None
or args.generate_rst is not None
) and args.output is not None:
print_error(
"Using --generate-c-code or --generate-docbook and "
"Using --generate-c-code or --generate-docbook or --generate-rst and "
"--output at the same time is not allowed"
)
@ -420,6 +428,11 @@ def codegen_main():
if docbook:
docbook_gen.generate(docbook, args.output_directory)
rst = args.generate_rst
rst_gen = codegen_rst.RstCodeGenerator(all_ifaces)
if rst:
rst_gen.generate(rst, args.output_directory)
if args.header:
with open(h_file, "w") as outfile:
gen = codegen.HeaderCodeGenerator(

332
gio/gdbus-2.0/codegen/codegen_rst.py Normal file
View File

@ -0,0 +1,332 @@
# SPDX-FileCopyrightText: 2022 Emmanuele Bassi
#
# SPDX-License-Identifier: LGPL-2.1-or-later
import os
import re
from . import utils
# Disable line length warnings as wrapping the templates would be hard
# flake8: noqa: E501
class RstCodeGenerator:
"""Generates documentation in reStructuredText format."""
def __init__(self, ifaces):
self.ifaces = ifaces
self._generate_expand_dicts()
def _expand(self, s, expandParamsAndConstants):
"""Expands parameters and constant literals."""
res = []
for line in s.split("\n"):
line = line.strip()
if line == "":
res.append("")
continue
for key in self._expand_member_dict_keys:
line = line.replace(key, self._expand_member_dict[key])
for key in self._expand_iface_dict_keys:
line = line.replace(key, self._expand_iface_dict[key])
if expandParamsAndConstants:
# replace @foo with ``foo``
line = re.sub(
"@[a-zA-Z0-9_]*",
lambda m: "``" + m.group(0)[1:] + "``",
line,
)
# replace e.g. %TRUE with ``TRUE``
line = re.sub(
"%[a-zA-Z0-9_]*",
lambda m: "``" + m.group(0)[1:] + "``",
line,
)
res.append(line)
return "\n".join(res)
def _generate_expand_dicts(self):
"""Generates the dictionaries used to expand gtk-doc sigils."""
self._expand_member_dict = {}
self._expand_iface_dict = {}
for i in self.ifaces:
key = f"#{i.name}"
value = f"`{i.name}`_"
self._expand_iface_dict[key] = value
for m in i.methods:
key = "%s.%s()" % (i.name, m.name)
value = f"`{i.name}.{m.name}`_"
self._expand_member_dict[key] = value
for s in i.signals:
key = "#%s::%s" % (i.name, s.name)
value = f"`{i.name}::{s.name}`_"
self._expand_member_dict[key] = value
for p in i.properties:
key = "#%s:%s" % (i.name, p.name)
value = f"`{i.name}:{p.name}`_"
self._expand_member_dict[key] = value
# Make sure to expand the keys in reverse order so e.g. #org.foo.Iface:MediaCompat
# is evaluated before #org.foo.Iface:Media ...
self._expand_member_dict_keys = sorted(
self._expand_member_dict.keys(), reverse=True
)
self._expand_iface_dict_keys = sorted(
self._expand_iface_dict.keys(), reverse=True
)
def _generate_header(self, iface):
"""Generates the header and preamble of the document."""
header_len = len(iface.name)
res = [
f".. _{iface.name}:",
"",
"=" * header_len,
iface.name,
"=" * header_len,
"",
"-----------",
"Description",
"-----------",
"",
f".. _{iface.name} Description:",
"",
iface.doc_string_brief.strip(),
"",
self._expand(iface.doc_string, True),
"",
]
if iface.since:
res += [
f"Interface available since: {iface.since}.",
"",
]
if iface.deprecated:
res += [
".. warning::",
"",
" This interface is deprecated.",
"",
"",
]
res += [""]
return "\n".join(res)
def _generate_section(self, title, name):
"""Generates a section with the given title."""
res = [
"-" * len(title),
title,
"-" * len(title),
"",
f".. {name} {title}:",
"",
"",
]
return "\n".join(res)
def _generate_properties(self, iface):
"""Generates the properties section."""
res = []
for p in iface.properties:
title = f"{iface.name}:{p.name}"
if p.readable and p.writable:
access = "readwrite"
elif p.writable:
access = "writable"
else:
access = "readable"
res += [
title,
"^" * len(title),
"",
"::",
"",
f" {p.name} {access} {p.signature}",
"",
"",
self._expand(p.doc_string, True),
"",
]
if p.since:
res += [
f"Property available since: {p.since}.",
"",
]
if p.deprecated:
res += [
".. warning::",
"",
" This property is deprecated.",
"",
"",
]
res += [""]
return "\n".join(res)
def _generate_method_signature(self, method):
"""Generates the method signature as a code block."""
res = [
"::",
"",
]
n_in_args = len(method.in_args)
n_out_args = len(method.out_args)
if n_in_args == 0 and n_out_args == 0:
res += [
f" {method.name} ()",
]
else:
res += [
f" {method.name} (",
]
for idx, arg in enumerate(method.in_args):
if idx == n_in_args - 1 and n_out_args == 0:
res += [
f" IN {arg.name} {arg.signature}",
]
else:
res += [
f" IN {arg.name} {arg.signature},",
]
for idx, arg in enumerate(method.out_args):
if idx == n_out_args - 1:
res += [
f" OUT {arg.name} {arg.signature}",
]
else:
res += [
f" OUT {arg.name} {arg.signature},",
]
res += [
" )",
"",
]
res += [""]
return "\n".join(res)
def _generate_methods(self, iface):
"""Generates the methods section."""
res = []
for m in iface.methods:
title = f"{iface.name}.{m.name}"
res += [
title,
"^" * len(title),
"",
self._generate_method_signature(m),
"",
self._expand(m.doc_string, True),
"",
]
for a in m.in_args:
arg_desc = self._expand(a.doc_string, True)
res += [
f"{a.name}",
f" {arg_desc}",
"",
]
res += [""]
if m.since:
res += [
f"Method available since: {m.since}.",
"",
]
if m.deprecated:
res += [
".. warning::",
"",
" This method is deprecated.",
"",
"",
]
res += [""]
return "\n".join(res)
def _generate_signal_signature(self, signal):
"""Generates the signal signature."""
res = [
"::",
"",
]
n_args = len(signal.args)
if n_args == 0:
res += [
f" {signal.name} ()",
]
else:
res += [
f" {signal.name} (",
]
for idx, arg in enumerate(signal.args):
if idx == n_args - 1:
res += [
f" {arg.name} {arg.signature}",
]
else:
res += [
f" {arg.name} {arg.signature},",
]
res += [
" )",
"",
]
res += [""]
return "\n".join(res)
def _generate_signals(self, iface):
"""Generates the signals section."""
res = []
for s in iface.signals:
title = f"{iface.name}::{s.name}"
res += [
title,
"^" * len(title),
"",
self._generate_signal_signature(s),
"",
self._expand(s.doc_string, True),
"",
]
for a in s.args:
arg_desc = self._expand(a.doc_string, True)
res += [
f"{a.name}",
f" {arg_desc}",
"",
]
res += [""]
if s.since:
res += [
f"Signal available since: {s.since}.",
"",
]
if s.deprecated:
res += [
".. warning::",
"",
" This signal is deprecated.",
"",
"",
]
res += [""]
return "\n".join(res)
def generate(self, rst, outdir):
"""Generates the reStructuredText file for each interface."""
for i in self.ifaces:
with open(os.path.join(outdir, f"{rst}-{i.name}.rst"), "w") as outfile:
outfile.write(self._generate_header(i))
if len(i.properties) > 0:
outfile.write(self._generate_section("Properties", i.name))
outfile.write(self._generate_properties(i))
if len(i.methods) > 0:
outfile.write(self._generate_section("Methods", i.name))
outfile.write(self._generate_methods(i))
if len(i.signals) > 0:
outfile.write(self._generate_section("Signals", i.name))
outfile.write(self._generate_signals(i))

1
gio/gdbus-2.0/codegen/meson.build
View File

@ -3,6 +3,7 @@ gdbus_codegen_files = [
'codegen.py',
'codegen_main.py',
'codegen_docbook.py',
'codegen_rst.py',
'dbustypes.py',
'parser.py',
'utils.py',

13
gio/gdbus-2.0/codegen/parser.py
View File

@ -85,7 +85,7 @@ class DBusXMLParser:
symbol = line[0:colon_index]
rest_of_line = line[colon_index + 2 :].strip()
if len(rest_of_line) > 0:
body += "<para>" + rest_of_line + "</para>"
body += f"{rest_of_line}\n"
comment_state = DBusXMLParser.COMMENT_STATE_PARAMS
elif comment_state == DBusXMLParser.COMMENT_STATE_PARAMS:
if line.startswith("@"):
@ -93,9 +93,9 @@ class DBusXMLParser:
if colon_index == -1:
comment_state = DBusXMLParser.COMMENT_STATE_BODY
if not in_para:
body += "<para>"
body += "\n"
in_para = True
body += orig_line + "\n"
body += f"{orig_line}\n"
else:
param = line[1:colon_index]
docs = line[colon_index + 2 :]
@ -104,21 +104,20 @@ class DBusXMLParser:
comment_state = DBusXMLParser.COMMENT_STATE_BODY
if len(line) > 0:
if not in_para:
body += "<para>"
body += "\n"
in_para = True
body += orig_line + "\n"
elif comment_state == DBusXMLParser.COMMENT_STATE_BODY:
if len(line) > 0:
if not in_para:
body += "<para>"
in_para = True
body += orig_line + "\n"
else:
if in_para:
body += "</para>"
body += "\n"
in_para = False
if in_para:
body += "</para>"
body += "\n"
if symbol != "":
self.doc_comment_last_symbol = symbol

40
gio/tests/codegen.py
View File

@ -382,6 +382,46 @@ G_END_DECLS
# The output should be the same.
self.assertEqual(result1.out, result2.out)
def test_generate_docbook(self):
"""Test the basic functionality of the docbook generator."""
xml_contents = """
<node>
<interface name="org.project.Bar.Frobnicator">
<method name="RandomMethod"/>
</interface>
</node>
"""
res = self.runCodegenWithInterface(
xml_contents,
"--generate-docbook",
"test",
)
self.assertEqual("", res.err)
self.assertEqual("", res.out)
with open("test-org.project.Bar.Frobnicator.xml", "r") as f:
xml_data = f.readlines()
self.assertTrue(len(xml_data) != 0)
def test_generate_rst(self):
"""Test the basic functionality of the rst generator."""
xml_contents = """
<node>
<interface name="org.project.Bar.Frobnicator">
<method name="RandomMethod"/>
</interface>
</node>
"""
res = self.runCodegenWithInterface(
xml_contents,
"--generate-rst",
"test",
)
self.assertEqual("", res.err)
self.assertEqual("", res.out)
with open("test-org.project.Bar.Frobnicator.rst", "r") as f:
rst = f.readlines()
self.assertTrue(len(rst) != 0)
def test_glib_min_required_invalid(self):
"""Test running with an invalid --glib-min-required."""
with self.assertRaises(subprocess.CalledProcessError):

21
gio/tests/gdbus-object-manager-example/meson.build
View File

@ -17,6 +17,22 @@ gdbus_example_objectmanager_generated = custom_target('objectmanager-gen',
'--symbol-decorator-define', 'HAVE_CONFIG_H',
'@INPUT@'])
gdbus_example_objectmanager_rst_gen = custom_target('objectmanager-rst-gen',
input: gdbus_example_objectmanager_xml,
output: [
'objectmanager-rst-gen-org.gtk.GDBus.Example.ObjectManager.Animal.rst',
'objectmanager-rst-gen-org.gtk.GDBus.Example.ObjectManager.Cat.rst',
],
command: [
python,
gdbus_codegen,
'--interface-prefix', 'org.gtk.GDBus.Example.ObjectManager.',
'--generate-rst', 'objectmanager-rst-gen',
'--output-directory', '@OUTDIR@',
'@INPUT@',
],
)
libgdbus_example_objectmanager = library('gdbus-example-objectmanager',
gdbus_example_objectmanager_generated,
c_args : test_c_args,
@ -25,6 +41,9 @@ libgdbus_example_objectmanager = library('gdbus-example-objectmanager',
install_dir : installed_tests_execdir)
libgdbus_example_objectmanager_dep = declare_dependency(
sources : gdbus_example_objectmanager_generated[0],
sources : [
gdbus_example_objectmanager_generated[0],
gdbus_example_objectmanager_rst_gen[0],
],
link_with : libgdbus_example_objectmanager,
dependencies : [libgio_dep])