glib/gio/gdbus-2.0/codegen/codegen_docbook.py
André 9a6ca0ef75
gdbus-codegen: preserve relative indentation in doc comments
This commit also changes the generators for rst, xml and dockbook
to preserve indentation.

Closes #3032
2023-08-14 23:46:09 -03:00

482 lines
18 KiB
Python

# -*- Mode: Python -*-
# GDBus - GLib D-Bus Library
#
# Copyright (C) 2008-2011 Red Hat, Inc.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General
# Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
#
# Author: David Zeuthen <davidz@redhat.com>
import re
import textwrap
from os import path
from . import utils
# ----------------------------------------------------------------------------------------------------
class DocbookCodeGenerator:
def __init__(self, ifaces):
self.ifaces = ifaces
self.generate_expand_dicts()
def print_method_prototype(self, i, m, in_synopsis):
max_method_len = 0
if in_synopsis:
for _m in i.methods:
max_method_len = max(len(_m.name), max_method_len)
else:
max_method_len = max(len(m.name), max_method_len)
max_signature_len = 0
if in_synopsis:
for _m in i.methods:
for a in _m.in_args:
max_signature_len = max(len(a.signature), max_signature_len)
for a in _m.out_args:
max_signature_len = max(len(a.signature), max_signature_len)
else:
for a in m.in_args:
max_signature_len = max(len(a.signature), max_signature_len)
for a in m.out_args:
max_signature_len = max(len(a.signature), max_signature_len)
if in_synopsis:
self.out.write(
'<link linkend="gdbus-method-%s.%s">%s</link>%*s ('
% (
utils.dots_to_hyphens(i.name),
m.name,
m.name,
max_method_len - len(m.name),
"",
)
)
else:
self.out.write("%s%*s (" % (m.name, max_method_len - len(m.name), ""))
count = 0
for a in m.in_args:
if count > 0:
self.out.write(",\n%*s" % (max_method_len + 2, ""))
self.out.write(
"IN %s%*s %s"
% (a.signature, max_signature_len - len(a.signature), "", a.name)
)
count = count + 1
for a in m.out_args:
if count > 0:
self.out.write(",\n%*s" % (max_method_len + 2, ""))
self.out.write(
"OUT %s%*s %s"
% (a.signature, max_signature_len - len(a.signature), "", a.name)
)
count = count + 1
self.out.write(");\n")
def print_signal_prototype(self, i, s, in_synopsis):
max_signal_len = 0
if in_synopsis:
for _s in i.signals:
max_signal_len = max(len(_s.name), max_signal_len)
else:
max_signal_len = max(len(s.name), max_signal_len)
max_signature_len = 0
if in_synopsis:
for _s in i.signals:
for a in _s.args:
max_signature_len = max(len(a.signature), max_signature_len)
else:
for a in s.args:
max_signature_len = max(len(a.signature), max_signature_len)
if in_synopsis:
self.out.write(
'<link linkend="gdbus-signal-%s.%s">%s</link>%*s ('
% (
utils.dots_to_hyphens(i.name),
s.name,
s.name,
max_signal_len - len(s.name),
"",
)
)
else:
self.out.write("%s%*s (" % (s.name, max_signal_len - len(s.name), ""))
count = 0
for a in s.args:
if count > 0:
self.out.write(",\n%*s" % (max_signal_len + 2, ""))
self.out.write(
"%s%*s %s"
% (a.signature, max_signature_len - len(a.signature), "", a.name)
)
count = count + 1
self.out.write(");\n")
def print_property_prototype(self, i, p, in_synopsis):
max_property_len = 0
if in_synopsis:
for _p in i.properties:
max_property_len = max(len(_p.name), max_property_len)
else:
max_property_len = max(len(p.name), max_property_len)
max_signature_len = 0
if in_synopsis:
for _p in i.properties:
max_signature_len = max(len(_p.signature), max_signature_len)
else:
max_signature_len = max(len(p.signature), max_signature_len)
if in_synopsis:
self.out.write(
'<link linkend="gdbus-property-%s.%s">%s</link>%*s'
% (
utils.dots_to_hyphens(i.name),
p.name,
p.name,
max_property_len - len(p.name),
"",
)
)
else:
self.out.write("%s%*s" % (p.name, max_property_len - len(p.name), ""))
if p.readable and p.writable:
access = "readwrite"
elif p.readable:
access = "readable "
else:
access = "writable "
self.out.write(" %s %s\n" % (access, p.signature))
def print_synopsis_methods(self, i):
self.out.write(' <refsynopsisdiv role="synopsis">\n')
self.out.write(' <title role="synopsis.title">Methods</title>\n')
self.out.write(" <synopsis>\n")
for m in i.methods:
self.print_method_prototype(i, m, in_synopsis=True)
self.out.write("</synopsis>\n")
self.out.write(" </refsynopsisdiv>\n")
def print_synopsis_signals(self, i):
self.out.write(' <refsect1 role="signal_proto">\n')
self.out.write(' <title role="signal_proto.title">Signals</title>\n')
self.out.write(" <synopsis>\n")
for s in i.signals:
self.print_signal_prototype(i, s, in_synopsis=True)
self.out.write("</synopsis>\n")
self.out.write(" </refsect1>\n")
def print_synopsis_properties(self, i):
self.out.write(' <refsect1 role="properties">\n')
self.out.write(' <title role="properties.title">Properties</title>\n')
self.out.write(" <synopsis>\n")
for p in i.properties:
self.print_property_prototype(i, p, in_synopsis=True)
self.out.write("</synopsis>\n")
self.out.write(" </refsect1>\n")
def print_method(self, i, m):
self.out.write(
'<refsect2 role="method" id="gdbus-method-%s.%s">\n'
% (utils.dots_to_hyphens(i.name), m.name)
)
self.out.write(" <title>The %s() method</title>\n" % (m.name))
self.out.write(
' <indexterm zone="gdbus-method-%s.%s"><primary sortas="%s.%s">%s.%s()</primary></indexterm>\n'
% (
utils.dots_to_hyphens(i.name),
m.name,
i.name_without_prefix,
m.name,
i.name,
m.name,
)
)
self.out.write("<programlisting>\n")
self.print_method_prototype(i, m, in_synopsis=False)
self.out.write("</programlisting>\n")
self.out.write("%s\n" % (self.expand_paras(m.doc_string, True)))
if m.in_args or m.out_args:
self.out.write('<variablelist role="params">\n')
for a in m.in_args:
self.out.write("<varlistentry>\n")
self.out.write(
" <term><literal>IN %s <parameter>%s</parameter></literal>:</term>\n"
% (a.signature, a.name)
)
self.out.write(
" <listitem>%s</listitem>\n"
% (self.expand_paras(a.doc_string, True))
)
self.out.write("</varlistentry>\n")
for a in m.out_args:
self.out.write("<varlistentry>\n")
self.out.write(
" <term><literal>OUT %s <parameter>%s</parameter></literal>:</term>\n"
% (a.signature, a.name)
)
self.out.write(
" <listitem>%s</listitem>\n"
% (self.expand_paras(a.doc_string, True))
)
self.out.write("</varlistentry>\n")
self.out.write("</variablelist>\n")
if len(m.since) > 0:
self.out.write('<para role="since">Since %s</para>\n' % (m.since))
if m.deprecated:
self.out.write(
"<warning><para>The %s() method is deprecated.</para></warning>"
% (m.name)
)
self.out.write("</refsect2>\n")
def print_signal(self, i, s):
self.out.write(
'<refsect2 role="signal" id="gdbus-signal-%s.%s">\n'
% (utils.dots_to_hyphens(i.name), s.name)
)
self.out.write(' <title>The "%s" signal</title>\n' % (s.name))
self.out.write(
' <indexterm zone="gdbus-signal-%s.%s"><primary sortas="%s::%s">%s::%s</primary></indexterm>\n'
% (
utils.dots_to_hyphens(i.name),
s.name,
i.name_without_prefix,
s.name,
i.name,
s.name,
)
)
self.out.write("<programlisting>\n")
self.print_signal_prototype(i, s, in_synopsis=False)
self.out.write("</programlisting>\n")
self.out.write("%s\n" % (self.expand_paras(s.doc_string, True)))
if s.args:
self.out.write('<variablelist role="params">\n')
for a in s.args:
self.out.write("<varlistentry>\n")
self.out.write(
" <term><literal>%s <parameter>%s</parameter></literal>:</term>\n"
% (a.signature, a.name)
)
self.out.write(
" <listitem>%s</listitem>\n"
% (self.expand_paras(a.doc_string, True))
)
self.out.write("</varlistentry>\n")
self.out.write("</variablelist>\n")
if len(s.since) > 0:
self.out.write('<para role="since">Since %s</para>\n' % (s.since))
if s.deprecated:
self.out.write(
'<warning><para>The "%s" signal is deprecated.</para></warning>'
% (s.name)
)
self.out.write("</refsect2>\n")
def print_property(self, i, p):
self.out.write(
'<refsect2 role="property" id="gdbus-property-%s.%s">\n'
% (utils.dots_to_hyphens(i.name), p.name)
)
self.out.write(' <title>The "%s" property</title>\n' % (p.name))
self.out.write(
' <indexterm zone="gdbus-property-%s.%s"><primary sortas="%s:%s">%s:%s</primary></indexterm>\n'
% (
utils.dots_to_hyphens(i.name),
p.name,
i.name_without_prefix,
p.name,
i.name,
p.name,
)
)
self.out.write("<programlisting>\n")
self.print_property_prototype(i, p, in_synopsis=False)
self.out.write("</programlisting>\n")
self.out.write("%s\n" % (self.expand_paras(p.doc_string, True)))
if len(p.since) > 0:
self.out.write('<para role="since">Since %s</para>\n' % (p.since))
if p.deprecated:
self.out.write(
'<warning><para>The "%s" property is deprecated.</para></warning>'
% (p.name)
)
self.out.write("</refsect2>\n")
def expand(self, s, expandParamsAndConstants):
for key in self.expand_member_dict_keys:
s = s.replace(key, self.expand_member_dict[key])
for key in self.expand_iface_dict_keys:
s = s.replace(key, self.expand_iface_dict[key])
if expandParamsAndConstants:
# replace @foo with <parameter>foo</parameter>
s = re.sub(
"@[a-zA-Z0-9_]*",
lambda m: "<parameter>" + m.group(0)[1:] + "</parameter>",
s,
)
# replace e.g. %TRUE with <constant>TRUE</constant>
s = re.sub(
"%[a-zA-Z0-9_]*",
lambda m: "<constant>" + m.group(0)[1:] + "</constant>",
s,
)
return s
def expand_paras(self, s, expandParamsAndConstants):
s = textwrap.dedent(self.expand(s, expandParamsAndConstants)).rstrip()
res = []
if not s.startswith("<para>"):
res.append("<para>")
for line in s.split("\n"):
line = line.rstrip()
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 = {}
self.expand_iface_dict = {}
for i in self.ifaces:
key = "#%s" % (i.name)
value = '<link linkend="gdbus-interface-%s.top_of_page">%s</link>' % (
utils.dots_to_hyphens(i.name),
i.name,
)
self.expand_iface_dict[key] = value
for m in i.methods:
key = "%s.%s()" % (i.name, m.name)
value = '<link linkend="gdbus-method-%s.%s">%s()</link>' % (
utils.dots_to_hyphens(i.name),
m.name,
m.name,
)
self.expand_member_dict[key] = value
for s in i.signals:
key = "#%s::%s" % (i.name, s.name)
value = '<link linkend="gdbus-signal-%s.%s">"%s"</link>' % (
utils.dots_to_hyphens(i.name),
s.name,
s.name,
)
self.expand_member_dict[key] = value
for p in i.properties:
key = "#%s:%s" % (i.name, p.name)
value = '<link linkend="gdbus-property-%s.%s">"%s"</link>' % (
utils.dots_to_hyphens(i.name),
p.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(self, docbook, outdir):
for i in self.ifaces:
self.out = open(path.join(outdir, "%s-%s.xml" % (docbook, i.name)), "w")
self.out.write("")
self.out.write('<?xml version="1.0" encoding="utf-8"?>\n')
self.out.write(
'<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"\n'
)
self.out.write(
' "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [\n'
)
self.out.write("]>\n")
self.out.write('<refentry id="gdbus-%s">\n' % (i.name))
self.out.write(" <refmeta>")
self.out.write(
' <refentrytitle role="top_of_page" id="gdbus-interface-%s.top_of_page">%s</refentrytitle>\n'
% (utils.dots_to_hyphens(i.name), i.name)
)
self.out.write(
' <indexterm zone="gdbus-interface-%s.top_of_page"><primary sortas="%s">%s</primary></indexterm>\n'
% (utils.dots_to_hyphens(i.name), i.name_without_prefix, i.name)
)
self.out.write(" </refmeta>")
self.out.write(" <refnamediv>")
self.out.write(" <refname>%s</refname>" % (i.name))
self.out.write(" <refpurpose>%s</refpurpose>" % (i.doc_string_brief))
self.out.write(" </refnamediv>")
if len(i.methods) > 0:
self.print_synopsis_methods(i)
if len(i.signals) > 0:
self.print_synopsis_signals(i)
if len(i.properties) > 0:
self.print_synopsis_properties(i)
self.out.write(
'<refsect1 role="desc" id="gdbus-interface-%s">\n'
% (utils.dots_to_hyphens(i.name))
)
self.out.write(' <title role="desc.title">Description</title>\n')
self.out.write(" %s\n" % (self.expand_paras(i.doc_string, True)))
if len(i.since) > 0:
self.out.write(' <para role="since">Since %s</para>\n' % (i.since))
if i.deprecated:
self.out.write(
"<warning><para>The %s interface is deprecated.</para></warning>"
% (i.name)
)
self.out.write("</refsect1>\n")
if len(i.methods) > 0:
self.out.write(
'<refsect1 role="details" id="gdbus-methods-%s">\n' % (i.name)
)
self.out.write(' <title role="details.title">Method Details</title>\n')
for m in i.methods:
self.print_method(i, m)
self.out.write("</refsect1>\n")
if len(i.signals) > 0:
self.out.write(
'<refsect1 role="details" id="gdbus-signals-%s">\n' % (i.name)
)
self.out.write(' <title role="details.title">Signal Details</title>\n')
for s in i.signals:
self.print_signal(i, s)
self.out.write("</refsect1>\n")
if len(i.properties) > 0:
self.out.write(
'<refsect1 role="details" id="gdbus-properties-%s">\n' % (i.name)
)
self.out.write(
' <title role="details.title">Property Details</title>\n'
)
for s in i.properties:
self.print_property(i, s)
self.out.write("</refsect1>\n")
self.out.write("</refentry>\n")
self.out.write("\n")