rougail-output-doc/src/rougail/output_doc/config.py

"""
Config file for Rougail-doc

Silique (https://www.silique.fr)
Copyright (C) 2024-2025

This program 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 3 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 Lesser General Public License for more
details.

You should have received a copy of the GNU Lesser General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
"""

from pathlib import Path
from rougail.utils import load_modules
from .i18n import _


OUTPUTS = None


def get_outputs() -> None:
    """Load all outputs"""
    module_name = "rougail.output_doc.output"
    outputs = {}
    for path in (Path(__file__).parent / "output").iterdir():
        name = path.name
        if not name.endswith(".py") or name.endswith("__.py"):
            continue
        module = load_modules(module_name + "." + name[:-3], str(path))
        if "Formatter" not in dir(module):
            continue
        level = module.Formatter.level
        if level in outputs:
            raise ImportError(
                _('duplicated level rougail-doc for output "{0}": {1} and {2}').format(
                    level, module.Formatter.name, outputs[level].name
                )
            )
        outputs[module.Formatter.level] = module.Formatter
    return {outputs[level].name: outputs[level] for level in sorted(outputs)}


class OutPuts:  # pylint: disable=R0903
    """Transformations applied on a object instance"""

    def __init__(
        self,
    ) -> None:
        global OUTPUTS
        if OUTPUTS is None:
            OUTPUTS = get_outputs()

    def get(self) -> dict:
        """Get all outputs"""
        return OUTPUTS


def get_rougail_config(
    *,
    backward_compatibility=True,  # pylint: disable=unused-argument
) -> dict:
    """Get documentation for output_doc modules"""
    outputs = list(OutPuts().get())
    output_format_default = outputs[0]
    rougail_options = f"""
doc:
  description: {_('Configuration rougail-doc')}
  disabled:
    jinja: |
      {{% if step.output is propertyerror or step.output != 'doc' %}}
      disabled
      {{% endif %}}

  title_level:
    description: {_('Starting title level')}
    alternative_name: dt
    default: 1

  contents:
    description: {_('Generated content')}
    choices:
      - variables
      - example
      - changelog
    default:
      - variables

  previous_json_file:
    description: {_('Previous description file in JSON format')}
    disabled:
      jinja: |-
        {{{{ "changelog" not in _.contents }}}}
      return_type: boolean
      description: changelog is not selected

  without_family: 
    description: {_('Do not add families in documentation')}
    default: false
    disabled:
      jinja: |-
        {{{{ "variables" not in _.contents and "changelog" not in _.contents and _.output_format != "json" }}}}
      return_type: boolean
      description: variables is not selected

  root:
    description: {_('Document the variables from this family')}
    mandatory: false

  other_root_filenames:
    description: {_("Families or variables for this family are in an other file name")}
    type: leadership
    disabled:
      jinja: |-
        {{% if not _.root %}}
          Documents are not splitted
        {{% endif %}}
        {{% if _.output_format != 'gitlab' %}}
          anchor is available only for gitlab output_format
        {{% endif %}}
      description: {_('documentation must be splitted and in gitlab format')}

    root_path:
      description: {_("Root family name")}
      mandatory: false

    filename:
      description: {_("Name of the file")}
      type: unix_filename
      params:
        allow_relative: true

  disabled_modes:
    description: {_('Disable documentation for variables with those modes')}
    multi: true
    mandatory: false
    disabled:
      jinja: |
        {{% if not modes_level %}}
        there is no mode
        {{% endif %}}
      description: {_('disabled when there is no mode available')}
    validators:
      - jinja: |
          {{% if _.disabled_modes not in modes_level %}}
          this mode is not available
          {{% endif %}}
        description: {_('verify if disable modes already exists')}

  change_default_value: true  # {_('Modify values to document leaderships and dynamics families')}

  comment_examples:
    description: {_('Add description of variables and families when generate examples')}
    default: false
    disabled:
      jinja: |-
        {{{{ "example" not in _.contents }}}}
      return_type: boolean
      description: {_('disabled when example in not in contents')}

  comment_examples_column:
    description: {_('Comment in examples starts at column')}
    default: 30
    disabled:
      variable: _.comment_examples
      propertyerror: false
      when: false

  output_format:
    description: {_('Generate document in format')}
    alternative_name: do
    default: output_format_default
    validators:
      - jinja: |-
          {{% if _.output_format == 'json' %}}
            {{% if "changelog" in _.contents or "example" in _.contents %}}
              cannot add to contents "{{{{ _.contents }}}}" with output_format "json"
            {{% endif %}}
          {{% endif %}}
        description: {_('json output_format is not compatible with "changelog" and "example" contents')}
    choices:
""".replace(
        "output_format_default", output_format_default
    )
    for output in outputs:
        rougail_options += f"      - {output}\n"
    rougail_options += f"""
  force_true_color_terminal:
      description: {_('Force true color terminal')}
      default: false
"""
    return {
        "name": "doc",
        "process": "output",
        "options": rougail_options,
        "allow_user_data": False,
        "level": 50,
    }


__all__ = ("OutPuts", "get_rougail_config")