diff options
| -rw-r--r-- | doc/docgen.py | 290 |
1 files changed, 143 insertions, 147 deletions
diff --git a/doc/docgen.py b/doc/docgen.py index ac5bd7b42..a8f91c4c8 100644 --- a/doc/docgen.py +++ b/doc/docgen.py @@ -1,4 +1,4 @@ -# -*- coding: utf-8 -*- +#!/usr/bin/env python3 # # Copyright (C) 2008-2020 Sébastien Helleu <flashcode@flashtux.org> # @@ -31,6 +31,8 @@ Documentation generator for WeeChat: build include files with: - URL options - plugins priority. +This script requires Python 3.6+. + Instructions to build config files yourself in WeeChat directories (replace "path" with the path to the docgen.py script in WeeChat repository): @@ -39,11 +41,9 @@ Instructions to build config files yourself in WeeChat directories Output files are in /path/xx/autogen/ (where xx is language). """ -from __future__ import print_function - SCRIPT_NAME = 'docgen' SCRIPT_AUTHOR = 'Sébastien Helleu <flashcode@flashtux.org>' -SCRIPT_VERSION = '0.2' +SCRIPT_VERSION = '0.3' SCRIPT_LICENSE = 'GPL3' SCRIPT_DESC = 'Documentation generator for WeeChat' @@ -59,8 +59,8 @@ try: import re from collections import defaultdict from operator import itemgetter -except ImportError as message: - print('Missing package(s) for {0}: {1}'.format(SCRIPT_NAME, message)) +except ImportError as exc: + print(f'Missing package(s) for {SCRIPT_NAME}: {exc}') IMPORT_OK = False try: @@ -156,16 +156,20 @@ class AutogenDoc(object): def __init__(self, directory, doc, name): """Initialize auto-generated doc file.""" self.filename = os.path.join(directory, doc, name + '.adoc') - self.filename_tmp = self.filename + '.tmp' + self.filename_tmp = f'{self.filename}.tmp' self._file = open(self.filename_tmp, 'w') - self.write('//\n') - self.write('// This file is auto-generated by script docgen.py.\n') - self.write('// DO NOT EDIT BY HAND!\n') - self.write('//\n') + self.write('//') + self.write('// This file is auto-generated by script docgen.py.') + self.write('// DO NOT EDIT BY HAND!') + self.write('//') - def write(self, string): + def write(self, string=None, *args): """Write a line in auto-generated doc file.""" - self._file.write(string) + if string: + if args: + string %= args + self._file.write(string) + self._file.write('\n') def update(self, obj_name, num_files, num_files_updated): """Update doc file if needed (if content has changed).""" @@ -301,7 +305,7 @@ def get_hdata(): hdata[plugin][hdata_name]['description'] = \ weechat.infolist_string(infolist, 'description') variables = '' - variables_update = '' + vars_update = '' lists = '' ptr_hdata = weechat.hdata_get(hdata_name) if ptr_hdata: @@ -316,33 +320,33 @@ def get_hdata(): key) if var_array_size: var_array_size = \ - ', array_size: "{0}"'.format(var_array_size) + f', array_size: "{var_array_size}"' var_hdata = weechat.hdata_get_var_hdata(ptr_hdata, key) if var_hdata: - var_hdata = ', hdata: "{0}"'.format(var_hdata) + var_hdata = f', hdata: "{var_hdata}"' type_string = weechat.hdata_get_var_type_string(ptr_hdata, key) hdata2.append({ 'offset': var_offset, - 'text': '_{0}_ ({1})'.format(key, type_string), - 'textlong': '_{0}_ ({1}{2}{3})'.format( - key, type_string, var_array_size, var_hdata), + 'text': f'_{key}_ ({type_string})', + 'textlong': (f'_{key}_ ({type_string}' + f'{var_array_size}{var_hdata})'), 'update': weechat.hdata_update( ptr_hdata, '', {'__update_allowed': key}), }) hdata2 = sorted(hdata2, key=itemgetter('offset')) for item in hdata2: - variables += '{0} +\n'.format(item['textlong']) + variables += f'{item["textlong"]} +\n' if item['update']: - variables_update += ' {0} +\n'.format(item['text']) + vars_update += f' {item["text"]} +\n' if weechat.hdata_update(ptr_hdata, '', {'__create_allowed': ''}): - variables_update += ' _{hdata_update_create}_ +\n' + vars_update += ' _{hdata_update_create}_ +\n' if weechat.hdata_update(ptr_hdata, '', {'__delete_allowed': ''}): - variables_update += ' _{hdata_update_delete}_ +\n' + vars_update += ' _{hdata_update_delete}_ +\n' hdata[plugin][hdata_name]['vars'] = variables - hdata[plugin][hdata_name]['vars_update'] = variables_update + hdata[plugin][hdata_name]['vars_update'] = vars_update.rstrip() string = weechat.hdata_get_string(ptr_hdata, 'list_keys') if string: @@ -352,7 +356,7 @@ def get_hdata(): lists_last = [l for l in list_lists if l.startswith('last_')] for item in sorted(lists_std) + sorted(lists_last): - lists += '_{0}_ +\n'.format(item) + lists += f'_{item}_ +\n' hdata[plugin][hdata_name]['lists'] = lists weechat.infolist_free(infolist) return hdata @@ -446,10 +450,10 @@ def get_plugins_priority(): def print_counters(label, files, updated): """Print a line with counters.""" color = weechat.color('*lightred') if updated > 0 else '' + color_reset = weechat.color('reset') weechat.prnt('', - 'docgen: {0}: {1} files, {2}{3}{4} updated' - ''.format(label, files, color, updated, - weechat.color('reset'))) + f'docgen: {label}: {files} files, ' + f'{color}{updated}{color_reset} updated') # pylint: disable=too-many-locals, too-many-branches, too-many-statements @@ -489,52 +493,52 @@ def docgen_cmd_cb(data, buf, args): num_files_updated[key] = 0 trans = gettext.translation('weechat', weechat.info_get('weechat_localedir', ''), - languages=[locale + '.UTF-8'], + languages=[f'{locale}.UTF-8'], fallback=True) trans.install() directory = os.path.join(os.path.dirname(data), locale[0:2], 'autogen') if not os.path.isdir(directory): + error = weechat.prefix('error') weechat.prnt('', - '{0}docgen error: directory "{1}" does not exist' - ''.format(weechat.prefix('error'), directory)) + f'{error}docgen error: directory "{directory}" ' + f'does not exist') continue # write commands for plugin in commands: - doc = AutogenDoc(directory, 'user', plugin + '_commands') + doc = AutogenDoc(directory, 'user', f'{plugin}_commands') for i, command in enumerate(sorted(commands[plugin])): if i > 0: - doc.write('\n') + doc.write() _cmd = commands[plugin][command] args = translate(_cmd['args']) args_formats = args.split(' || ') desc = translate(_cmd['description']) args_desc = translate(_cmd['args_description']) - doc.write('[[command_{0}_{1}]]\n'.format(plugin, command)) - doc.write('* `+{0}+`: {1}\n\n'.format(command, desc)) - doc.write('----\n') + doc.write(f'[[command_{plugin}_{command}]]') + doc.write(f'* `+{command}+`: {desc}\n') + doc.write('----') prefix = '/' + command + ' ' if args_formats != ['']: for fmt in args_formats: - doc.write(prefix + fmt + '\n') + doc.write(prefix + fmt) prefix = ' ' * len(prefix) if args_desc: - doc.write('\n') - for line in args_desc.split('\n'): - doc.write(line + '\n') - doc.write('----\n') + doc.write() + doc.write(args_desc) + doc.write('----') doc.update('commands', num_files, num_files_updated) # write config options for config in options: - doc = AutogenDoc(directory, 'user', config + '_options') + doc = AutogenDoc(directory, 'user', f'{config}_options') i = 0 for section in sorted(options[config]): for option in sorted(options[config][section]): if i > 0: - doc.write('\n') + doc.write() i += 1 _opt = options[config][section][option] opt_type = _opt['type'] @@ -552,20 +556,20 @@ def docgen_cmd_cb(data, buf, args): if string_values: values = string_values.replace('|', ', ') else: - values = '{0} .. {1}'.format(opt_min, opt_max) + values = f'{opt_min} .. {opt_max}' elif opt_type == 'string': if opt_max <= 0: values = _('any string') elif opt_max == 1: values = _('any char') elif opt_max > 1: - values = '{0} ({1}: {2})'.format(_('any string'), - _('max chars'), - opt_max) + values = (_('any string') + + '(' + _('max chars') + ': ' + + opt_max + ')') else: values = _('any string') - default_value = '"{0}"'.format( - default_value.replace('"', '\\"')) + default_value = ('"%s"' % + default_value.replace('"', '\\"')) elif opt_type == 'color': values = _('a WeeChat color name (default, black, ' '(dark)gray, white, (light)red, ' @@ -576,176 +580,168 @@ def docgen_cmd_cb(data, buf, args): 'only, not background): \"*\" for bold, ' '\"!\" for reverse, \"/\" for italic, ' '\"_\" for underline') - doc.write('* [[option_{0}.{1}.{2}]] *{3}.{4}.{5}*\n' - ''.format(config, section, option, config, - section, option)) - doc.write('** {0}: pass:none[{1}]\n'.format( - _('description'), desc.replace(']', '\\]'))) - doc.write('** {0}: {1}\n'.format(_('type'), type_nls)) - doc.write('** {0}: {1}\n'.format(_('values'), values)) - doc.write('** {0}: `+{1}+`\n' - ''.format(_('default value'), default_value)) + doc.write(f'* [[option_{config}.{section}.{option}]] ' + f'*{config}.{section}.{option}*') + doc.write('** %s: pass:none[%s]', + _('description'), desc.replace(']', '\\]')) + doc.write('** %s: %s', _('type'), type_nls) + doc.write('** %s: %s', _('values'), values) + doc.write('** %s: `+%s+`', + _('default value'), default_value) if null_value_allowed: - doc.write('** {0}\n'.format( - _('undefined value allowed (null)'))) + doc.write('** %s', + _('undefined value allowed (null)')) doc.update('options', num_files, num_files_updated) # write default aliases doc = AutogenDoc(directory, 'user', 'alias_default_aliases') - doc.write('[width="100%",cols="2m,5m,5",options="header"]\n') - doc.write('|===\n') - doc.write('| {0} | {1} | {2}\n\n' - ''.format(_('Alias'), _('Command'), _('Completion'))) + doc.write('[width="100%",cols="2m,5m,5",options="header"]') + doc.write('|===') + doc.write('| %s | %s | %s\n', + _('Alias'), _('Command'), _('Completion')) for alias in default_aliases: - doc.write('| {0} | {1} | {2}\n' - ''.format(escape(alias['name']), - escape(alias['command']), - escape(alias['completion'] or '-'))) - doc.write('|===\n') + doc.write('| %s | %s | %s', + escape(alias['name']), + escape(alias['command']), + escape(alias['completion'] or '-')) + doc.write('|===') doc.update('alias_default_aliases', num_files, num_files_updated) # write IRC colors doc = AutogenDoc(directory, 'user', 'irc_colors') - doc.write('[width="50%",cols="^2m,3",options="header"]\n') - doc.write('|===\n') - doc.write('| {0} | {1}\n\n' - ''.format(_('IRC color'), _('WeeChat color'))) + doc.write('[width="50%",cols="^2m,3",options="header"]') + doc.write('|===') + doc.write('| %s | %s\n', _('IRC color'), _('WeeChat color')) for color in irc_colors: - doc.write('| {0} | {1}\n' - ''.format(escape(color['color_irc']), - escape(color['color_weechat']))) - doc.write('|===\n') + doc.write('| %s | %s', + escape(color['color_irc']), + escape(color['color_weechat'])) + doc.write('|===') doc.update('irc_colors', num_files, num_files_updated) # write infos hooked doc = AutogenDoc(directory, 'plugin_api', 'infos') - doc.write('[width="100%",cols="^1,^2,6,6",options="header"]\n') - doc.write('|===\n') - doc.write('| {0} | {1} | {2} | {3}\n\n' - ''.format(_('Plugin'), _('Name'), _('Description'), - _('Arguments'))) + doc.write('[width="100%",cols="^1,^2,6,6",options="header"]') + doc.write('|===') + doc.write('| %s | %s | %s | %s\n', + _('Plugin'), _('Name'), _('Description'), _('Arguments')) for plugin in sorted(infos): for info in sorted(infos[plugin]): _inf = infos[plugin][info] desc = translate(_inf['description']) args_desc = translate(_inf['args_description'] or '-') - doc.write('| {0} | {1} | {2} | {3}\n\n' - ''.format(escape(plugin), escape(info), - escape(desc), escape(args_desc))) - doc.write('|===\n') + doc.write('| %s | %s | %s | %s\n', + escape(plugin), escape(info), escape(desc), + escape(args_desc)) + doc.write('|===') doc.update('infos', num_files, num_files_updated) # write infos (hashtable) hooked doc = AutogenDoc(directory, 'plugin_api', 'infos_hashtable') - doc.write('[width="100%",cols="^1,^2,6,6,8",options="header"]\n') - doc.write('|===\n') - doc.write('| {0} | {1} | {2} | {3} | {4}\n\n' - ''.format(_('Plugin'), _('Name'), _('Description'), - _('Hashtable (input)'), _('Hashtable (output)'))) + doc.write('[width="100%",cols="^1,^2,6,6,8",options="header"]') + doc.write('|===') + doc.write('| %s | %s | %s | %s | %s\n', + _('Plugin'), _('Name'), _('Description'), + _('Hashtable (input)'), _('Hashtable (output)')) for plugin in sorted(infos_hashtable): for info in sorted(infos_hashtable[plugin]): _inh = infos_hashtable[plugin][info] desc = translate(_inh['description']) args_desc = translate(_inh['args_description']) output_desc = translate(_inh['output_description']) or '-' - doc.write('| {0} | {1} | {2} | {3} | {4}\n\n' - ''.format(escape(plugin), escape(info), - escape(desc), escape(args_desc), - escape(output_desc))) - doc.write('|===\n') + doc.write('| %s | %s | %s | %s | %s\n', + escape(plugin), escape(info), escape(desc), + escape(args_desc), escape(output_desc)) + doc.write('|===') doc.update('infos_hashtable', num_files, num_files_updated) # write infolists hooked doc = AutogenDoc(directory, 'plugin_api', 'infolists') - doc.write('[width="100%",cols="^1,^2,5,5,5",options="header"]\n') - doc.write('|===\n') - doc.write('| {0} | {1} | {2} | {3} | {4}\n\n' - ''.format(_('Plugin'), _('Name'), _('Description'), - _('Pointer'), _('Arguments'))) + doc.write('[width="100%",cols="^1,^2,5,5,5",options="header"]') + doc.write('|===') + doc.write('| %s | %s | %s | %s | %s\n', + _('Plugin'), _('Name'), _('Description'), _('Pointer'), + _('Arguments')) for plugin in sorted(infolists): for infolist in sorted(infolists[plugin]): _inl = infolists[plugin][infolist] desc = translate(_inl['description']) pointer_desc = translate(_inl['pointer_description']) or '-' args_desc = translate(_inl['args_description']) or '-' - doc.write('| {0} | {1} | {2} | {3} | {4}\n\n' - ''.format(escape(plugin), escape(infolist), - escape(desc), escape(pointer_desc), - escape(args_desc))) - doc.write('|===\n') + doc.write('| %s | %s | %s | %s | %s\n', + escape(plugin), escape(infolist), escape(desc), + escape(pointer_desc), escape(args_desc)) + doc.write('|===') doc.update('infolists', num_files, num_files_updated) # write hdata hooked doc = AutogenDoc(directory, 'plugin_api', 'hdata') - doc.write(':hdata_update_create: __create\n') - doc.write(':hdata_update_delete: __delete\n') - doc.write('[width="100%",cols="^1,^2,2,2,5",options="header"]\n') - doc.write('|===\n') - doc.write('| {0} | {1} | {2} | {3} | {4}\n\n' - ''.format(_('Plugin'), _('Name'), _('Description'), - _('Lists'), _('Variables'))) + doc.write(':hdata_update_create: __create') + doc.write(':hdata_update_delete: __delete') + doc.write('[width="100%",cols="^1,^2,2,2,5",options="header"]') + doc.write('|===') + doc.write('| %s | %s | %s | %s | %s\n', + _('Plugin'), _('Name'), _('Description'), _('Lists'), + _('Variables')) for plugin in sorted(hdata): for hdata_name in sorted(hdata[plugin]): _hda = hdata[plugin][hdata_name] - anchor = 'hdata_{0}'.format(hdata_name) + anchor = f'hdata_{hdata_name}' desc = translate(_hda['description']) variables = _hda['vars'] - variables_update = _hda['vars_update'] + vars_update = _hda['vars_update'] lists = _hda['lists'] - doc.write('| {0}\n'.format(escape(plugin))) - doc.write('| [[{0}]]<<{0},{1}>>\n' - ''.format(escape(anchor), escape(hdata_name))) - doc.write('| {0}\n'.format(escape(desc))) - doc.write('| {0}\n'.format(escape(lists) if lists else '-')) - doc.write('| {0}\n'.format(escape(variables))) - if variables_update: - doc.write('*{0}* +\n{1}'.format( - _('Update allowed:'), - escape(variables_update))) - doc.write('\n') - doc.write('|===\n') + doc.write(f'| {escape(plugin)}') + doc.write(f'| [[{escape(anchor)}]]<<{escape(anchor)},' + f'{escape(hdata_name)}>>') + doc.write(f'| {escape(desc)}') + str_lists = escape(lists) if lists else '-' + doc.write(f'| {str_lists}') + doc.write(f'| {escape(variables)}') + if vars_update: + doc.write('*%s* +\n%s', + _('Update allowed:'), escape(vars_update)) + doc.write() + doc.write('|===') doc.update('hdata', num_files, num_files_updated) # write completions hooked doc = AutogenDoc(directory, 'plugin_api', 'completions') - doc.write('[width="100%",cols="^1,^2,7",options="header"]\n') - doc.write('|===\n') - doc.write('| {0} | {1} | {2}\n\n' - ''.format(_('Plugin'), _('Name'), _('Description'))) + doc.write('[width="100%",cols="^1,^2,7",options="header"]') + doc.write('|===') + doc.write('| %s | %s | %s\n', + _('Plugin'), _('Name'), _('Description')) for plugin in sorted(completions): for completion_item in sorted(completions[plugin]): _cmp = completions[plugin][completion_item] desc = translate(_cmp['description']) - doc.write('| {0} | {1} | {2}\n\n' - ''.format(escape(plugin), escape(completion_item), - escape(desc))) - doc.write('|===\n') + doc.write('| %s | %s | %s\n', + escape(plugin), escape(completion_item), + escape(desc)) + doc.write('|===') doc.update('completions', num_files, num_files_updated) # write URL options doc = AutogenDoc(directory, 'plugin_api', 'url_options') - doc.write('[width="100%",cols="2,^1,7",options="header"]\n') - doc.write('|===\n') - doc.write('| {0} | {1} | {2}\n\n' - ''.format(_('Option'), - _('Type') + ' ^(1)^', - _('Constants') + ' ^(2)^')) + doc.write('[width="100%",cols="2,^1,7",options="header"]') + doc.write('|===') + doc.write('| %s | %s ^(1)^ | %s ^(2)^\n', + _('Option'), _('Type'), _('Constants')) for option in url_options: constants = option['constants'] if constants: constants = ' ' + constants - doc.write('| {0} | {1} |{2}\n\n' - ''.format(escape(option['name']), - escape(option['type']), - escape(constants))) - doc.write('|===\n') + doc.write('| %s | %s |%s\n', + escape(option['name']), escape(option['type']), + escape(constants)) + doc.write('|===') doc.update('url_options', num_files, num_files_updated) # write plugins priority doc = AutogenDoc(directory, 'plugin_api', 'plugins_priority') for priority in sorted(plugins_priority, reverse=True): plugins = ', '.join(sorted(plugins_priority[priority])) - doc.write('. {0} ({1})\n'.format(escape(plugins), priority)) + doc.write('. %s (%s)', escape(plugins), priority) doc.update('plugins_priority', num_files, num_files_updated) # write counters |