WIP: Expand the developer documentation #27

Draft
gremond wants to merge 62 commits from develop into developer_docs
5 changed files with 118 additions and 35 deletions
Showing only changes of commit db565527ec - Show all commits

View file

@ -136,6 +136,12 @@ class _RougailConfig:
class FakeRougailConvert(RougailConvert): class FakeRougailConvert(RougailConvert):
def __init__(self,
add_extra_options: bool,
) -> None:
self.add_extra_options = add_extra_options
super().__init__({})
def load_config(self, def load_config(self,
rougailconfig: 'RougailConfig', rougailconfig: 'RougailConfig',
) -> None: ) -> None:
@ -149,10 +155,12 @@ class FakeRougailConvert(RougailConvert):
self.export_with_import = True self.export_with_import = True
self.internal_functions = [] self.internal_functions = []
self.plugins = ['structural_commandline'] self.plugins = ['structural_commandline']
self.add_extra_options = self.add_extra_options
def get_rougail_config(*, def get_rougail_config(*,
backward_compatibility=True, backward_compatibility: bool=True,
add_extra_options: bool=True,
) -> _RougailConfig: ) -> _RougailConfig:
if backward_compatibility: if backward_compatibility:
main_namespace_default = 'rougail' main_namespace_default = 'rougail'
@ -178,7 +186,7 @@ main_dictionaries:
main_namespace: main_namespace:
description: Main namespace name description: Main namespace name
default: MAIN_MAMESPACE_DEFAULT default: MAIN_MAMESPACE_DEFAULT
alternative_name: n alternative_name: s
mandatory: false mandatory: false
extra_dictionaries: extra_dictionaries:
description: Extra namespaces description: Extra namespaces
@ -191,12 +199,12 @@ extra_dictionaries:
{% endif %} {% endif %}
names: names:
description: 'Extra namespace name' description: 'Extra namespace name'
# alternative_name: e alternative_name: e
multi: true multi: true
mandatory: false mandatory: false
directories: directories:
description: Directories where extra dictionary files are placed description: Directories where extra dictionary files are placed
# alternative_name: d alternative_name: d
type: unix_filename type: unix_filename
params: params:
allow_relative: true allow_relative: true
@ -279,9 +287,9 @@ suffix:
mandatory: false mandatory: false
commandline: false commandline: false
""".replace('MAIN_MAMESPACE_DEFAULT', main_namespace_default) """.replace('MAIN_MAMESPACE_DEFAULT', main_namespace_default)
processes = {'output': [], processes = {'structural': [],
'output': [],
'user data': [], 'user data': [],
# 'structural': [],
} }
for module in get_sub_modules().values(): for module in get_sub_modules().values():
data = module.get_rougail_config() data = module.get_rougail_config()
@ -302,13 +310,15 @@ suffix:
) )
for obj in objects: for obj in objects:
rougail_process += f" - {obj['name']}\n" rougail_process += f" - {obj['name']}\n"
if process == 'user data': if process == 'structural':
rougail_process +=""" multi: true rougail_process += " commandline: false"
elif process == 'user data':
rougail_process += """ multi: true
mandatory: false mandatory: false
""" """
hidden_outputs = [process['name'] for process in processes['output'] if not process.get('allow_user_data', True)] hidden_outputs = [process['name'] for process in processes['output'] if not process.get('allow_user_data', True)]
if hidden_outputs: if hidden_outputs:
rougail_process +=""" hidden: rougail_process += """ hidden:
type: jinja type: jinja
jinja: | jinja: |
""" """
@ -329,7 +339,7 @@ suffix:
""".format(NAME=normalize_family(process), """.format(NAME=normalize_family(process),
) )
rougail_options += rougail_process rougail_options += rougail_process
convert = FakeRougailConvert({}) convert = FakeRougailConvert(add_extra_options)
convert._init() convert._init()
convert.namespace = None convert.namespace = None
convert.parse_root_file( convert.parse_root_file(

View file

@ -317,6 +317,7 @@ class Informations:
class ParserVariable: class ParserVariable:
def __init__(self, rougailconfig): def __init__(self, rougailconfig):
self.load_config(rougailconfig) self.load_config(rougailconfig)
self.rougailconfig = rougailconfig
self.paths = Paths(self.main_namespace) self.paths = Paths(self.main_namespace)
self.families = [] self.families = []
self.variables = [] self.variables = []
@ -332,9 +333,6 @@ class ParserVariable:
self.convert_options = list(CONVERT_OPTION) self.convert_options = list(CONVERT_OPTION)
self.convert_options.extend(self.custom_types) self.convert_options.extend(self.custom_types)
# #
self.family = Family
self.dynamic = Dynamic
#
self.exclude_imports = [] self.exclude_imports = []
self.informations = Informations() self.informations = Informations()
self.properties = Property() self.properties = Property()
@ -363,12 +361,14 @@ class ParserVariable:
self.base_option_name = rougailconfig["base_option_name"] self.base_option_name = rougailconfig["base_option_name"]
self.export_with_import = rougailconfig["export_with_import"] self.export_with_import = rougailconfig["export_with_import"]
self.internal_functions = rougailconfig["internal_functions"] self.internal_functions = rougailconfig["internal_functions"]
self.add_extra_options = rougailconfig["structural_commandline.add_extra_options"]
self.plugins = [] self.plugins = []
def _init(self): def _init(self):
if self.is_init: if self.is_init:
return return
variable = Variable variable = Variable
family = Family
if self.plugins: if self.plugins:
root = Path(__file__).parent root = Path(__file__).parent
for plugin in self.plugins: for plugin in self.plugins:
@ -376,13 +376,15 @@ class ParserVariable:
if not module_path.is_file(): if not module_path.is_file():
continue continue
module = load_modules(f'rougail.{plugin}.object_model', str(module_path)) module = load_modules(f'rougail.{plugin}.object_model', str(module_path))
if 'Variable' not in module.__all__: if 'Variable' in module.__all__:
continue variable = type(variable.__name__ + '_' + plugin, (variable, module.Variable), {})
variable = type(variable.__name__ + '_' + plugin, (Variable, module.Variable), {}) if 'Family' in module.__all__:
family = type(family.__name__ + '_' + plugin, (family, module.Family), {})
self.variable = variable self.variable = variable
self.family = family
self.dynamic = type(Dynamic.__name__, (Dynamic, family), {})
hint = get_type_hints(self.dynamic) hint = get_type_hints(self.dynamic)
# FIXME: only for format 1.0 # FIXME: only for format 1.0
hint["variable"] = str
self.family_types = hint["type"].__args__ # pylint: disable=W0201 self.family_types = hint["type"].__args__ # pylint: disable=W0201
self.family_attrs = frozenset( # pylint: disable=W0201 self.family_attrs = frozenset( # pylint: disable=W0201
set(hint) - {"name", "path", "xmlfiles"} | {"redefine"} set(hint) - {"name", "path", "xmlfiles"} | {"redefine"}

View file

@ -20,34 +20,58 @@ along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
""" """
from rougail.annotator.variable import Walk from rougail.annotator.variable import Walk
from rougail.utils import _
from rougail.error import DictConsistencyError
class Annotator(Walk): class Annotator(Walk):
"""Annotate value""" """Annotate value"""
level = 5 level = 80
def __init__(self, objectspace, *args) -> None: def __init__(self, objectspace, *args) -> None:
if not objectspace.paths: if not objectspace.paths:
return return
self.objectspace = objectspace self.objectspace = objectspace
self.manage_alternative_name() not_for_commandlines = []
self.not_for_commandline() for family in self.get_families():
if family.commandline:
def manage_alternative_name(self) -> None: continue
self.not_for_commandline(family)
not_for_commandlines.append(family.path + '.')
for variable in self.get_variables(): for variable in self.get_variables():
if variable.type == 'symlink': if variable.type == 'symlink':
continue continue
if not variable.alternative_name:
continue
alternative_name = variable.alternative_name
variable_path = variable.path variable_path = variable.path
if '.' not in variable_path: for family_path in not_for_commandlines:
path = alternative_name if variable_path.startswith(family_path):
break
else: else:
path = variable_path.rsplit('.', 1)[0] + '.' + alternative_name if not variable.commandline:
self.objectspace.add_variable(alternative_name, {'type': 'symlink', 'path': path, 'opt': variable}, variable.xmlfiles, False, False, variable.version) self.not_for_commandline(variable)
else:
self.manage_alternative_name(variable)
self.manage_negative_description(variable)
def not_for_commandline(self) -> None: def not_for_commandline(self, variable) -> None:
for variable in self.get_variables(): self.objectspace.properties.add(variable.path, 'not_for_commandline', True)
if not hasattr(variable, 'commandline') or variable.commandline:
continue def manage_alternative_name(self, variable) -> None:
self.objectspace.properties.add(variable.path, 'not_for_commandline', True) if not variable.alternative_name:
return
alternative_name = variable.alternative_name
variable_path = variable.path
if '.' not in variable_path:
path = alternative_name
else:
path = variable_path.rsplit('.', 1)[0] + '.' + alternative_name
self.objectspace.add_variable(alternative_name, {'type': 'symlink', 'path': path, 'opt': variable}, variable.xmlfiles, False, False, variable.version)
def manage_negative_description(self, variable) -> None:
if not variable.negative_description:
if variable.type == 'boolean' and not self.objectspace.add_extra_options:
raise DictConsistencyError(_(f'negative_description is mandatory for boolean variable, but "{variable.path}" hasn\'t'), 200, variable.xmlfiles)
return
if variable.type != 'boolean':
raise DictConsistencyError(_(f'negative_description is only available for boolean variable, but "{variable.path}" is "{variable.type}"'), 200, variable.xmlfiles)
self.objectspace.informations.add(
variable.path, "negative_description", variable.negative_description
)

View file

@ -0,0 +1,42 @@
"""
Config file for Rougail-structural_commandline
Silique (https://www.silique.fr)
Copyright (C) 2024
distribued with GPL-2 or later license
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program 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 General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
"""
def get_rougail_config(*,
backward_compatibility=True,
) -> dict:
options = """
structural_commandline:
description: Configuration rougail-structural_commandline
commandline: false
add_extra_options:
description: Add extra options to tiramisu-cmdline-parser
default: true
"""
return {'name': 'exporter',
'process': 'structural',
'options': options,
'level': 20,
}
__all__ = ('get_rougail_config')

View file

@ -26,6 +26,11 @@ from pydantic import BaseModel
class Variable(BaseModel): class Variable(BaseModel):
alternative_name: Optional[str]=None alternative_name: Optional[str]=None
commandline: bool=True commandline: bool=True
negative_description: Optional[str]=None
__all__ = ('Variable',) class Family(BaseModel):
commandline: bool=True
__all__ = ('Variable', 'Family')