Debian Codegraph @

docs/assemble_man.py

raw
1 #!/usr/bin/env python3
2 # -*- coding: utf-8 -*-
3 #
4 # Copyright (C) 2018-2022 Matthias Klumpp <[email protected]>
5 #
6 # SPDX-License-Identifier: LGPL-3.0-or-later
7
8 import os
9 import sys
10 from functools import reduce
11 from subprocess import check_call
12 from xml.sax.saxutils import escape as xml_escape
13
14 sys.path.append("..")
15
16
17 class DocbookEditor:
18 def __init__(self):
19 self._replacements = {}
20
21 def add_substvar(self, name, replacement):
22 self._replacements['@{}@'.format(name)] = replacement
23
24 def register_command_flag_synopsis(self, actions, command_name):
25 flags_text = ''
26 flags_entries = ''
27 for item in actions:
28 options_text = xml_escape('|'.join(item.option_strings))
29 flags_text += '<arg>{}</arg>\n'.format(options_text)
30
31 oid = item.option_strings[0]
32 desc_text = None
33 if oid == '-h':
34 desc_text = 'Print brief help information about available commands.'
35 if command_name != 'create':
36 if oid == '--variant':
37 desc_text = 'Set the variant of the selected image, that was used for bootstrapping.'
38 elif oid == '-a':
39 desc_text = 'The architecture of the base image that should be selected.'
40
41 if not desc_text:
42 desc_text = item.help
43 desc_text = xml_escape(desc_text)
44
45 if desc_text.startswith('CF|'):
46 desc_text = desc_text[3:]
47 desc_text = desc_text.replace('binary:', '<option>binary</option>:', 1)
48 desc_text = desc_text.replace('arch:', '<option>arch</option>:', 1)
49 desc_text = desc_text.replace('indep:', '<option>indep</option>:', 1)
50 desc_text = desc_text.replace('source:', '<option>source</option>:', 1)
51
52 flags_entries += '''<varlistentry>
53 <term>{}</term>
54 <listitem>
55 <para>
56 {}
57 </para>
58 </listitem>
59 </varlistentry>'''.format(options_text, desc_text)
60
61 self.add_substvar('{}_FLAGS_SYNOPSIS'.format(command_name.upper()), flags_text)
62 self.add_substvar('{}_FLAGS_ENTRIES'.format(command_name.upper()), flags_entries)
63
64 def process_file(self, input_fname, output_fname):
65 with open(input_fname, 'r') as f:
66 template_content = f.read()
67
68 result = reduce(
69 lambda x, y: x.replace(y, self._replacements[y]), self._replacements, template_content
70 )
71
72 with open(output_fname, 'w') as f:
73 f.write(result)
74
75 return output_fname
76
77
78 def generate_docbook_pages(build_dir):
79 from debspawn.cli import create_parser
80
81 build_dir = os.path.abspath(build_dir)
82
83 parser = create_parser()
84 editor = DocbookEditor()
85 editor.register_command_flag_synopsis(parser._get_optional_actions(), 'BASE')
86
87 xml_manpages = []
88 xml_manpages.append(editor.process_file('docs/debspawn.1.xml', os.path.join(build_dir, 'debspawn.1.xml')))
89
90 for command, sp in parser._get_positional_actions()[0]._name_parser_map.items():
91 editor.register_command_flag_synopsis(sp._get_optional_actions(), command)
92 template_fname = 'docs/debspawn-{}.1.xml'.format(command)
93 if not os.path.isfile(template_fname):
94 if command in ['ls', 'b']:
95 continue # the ls and b shorthands need to manual page
96 print('Manual page template {} is missing! Skipping it.'.format(template_fname))
97 continue
98
99 xml_manpages.append(
100 editor.process_file(template_fname, os.path.join(build_dir, os.path.basename(template_fname)))
101 )
102
103 return xml_manpages
104
105
106 def create_manpage(xml_src, out_dir):
107 man_name = os.path.splitext(os.path.basename(xml_src))[0]
108 out_fname = os.path.join(out_dir, man_name)
109
110 print('Generating manual page {}'.format(man_name))
111 check_call(
112 [
113 'xsltproc',
114 '--nonet',
115 '--stringparam',
116 'man.output.quietly',
117 '1',
118 '--stringparam',
119 'funcsynopsis.style',
120 'ansi',
121 '--stringparam',
122 'man.th.extra1.suppress',
123 '1',
124 '-o',
125 out_fname,
126 'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl',
127 xml_src,
128 ]
129 )
130 return out_fname
131
132
133 if __name__ == '__main__':
134 generate_docbook_pages('/tmp')