# Copyright 2026 jCloud

# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at

#     http://www.apache.org/licenses/LICENSE-2.0

# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import pathlib

from ...core.python import (
    PythonDefinitionDocumentationIncludeSections,
    PythonDocumentationGenerator,
)

__all__ = [
    'VALID_SECTIONS',
    'parse_sections_list',
    'generate',
]

VALID_SECTIONS = list(
    PythonDefinitionDocumentationIncludeSections()._args.keys()
)


def parse_sections_list(
    include_sections: list[str] | None = None,
    exclude_sections: list[str] = [],
) -> PythonDefinitionDocumentationIncludeSections:
    """
    Returns a Python definition documentation sections list from the
    sections list to be included and the sections list to be excluded.
    These lists both consist of the sections as strings which contain
    the section name.

    :param include_sections: The list of sections to be included.
    :type include_sections: list[str] | None
    :param exclude_sections: The list of sections to be excluded.
    :type exclude_sections: list[str]

    :return: The Python definition documentation sections object.
    :rtype: PythonDefinitionDocumentationIncludeSections
    """

    if include_sections is None:
        include_sections = VALID_SECTIONS[:]

    for section in exclude_sections:
        while section in include_sections:
            del include_sections[include_sections.index(section)]

    return PythonDefinitionDocumentationIncludeSections(
        signature='signature' in include_sections,
        returns='returns' in include_sections,
        params='params' in include_sections,
        exceptions='exceptions' in include_sections,
        examples='examples' in include_sections,
        docstring='docstring' in include_sections,
        bases='bases' in include_sections,
        decorators='decorators' in include_sections,
        class_body='class_body' in include_sections,
    )


def _generate(
    project_directory: pathlib.Path,
    output_directory: pathlib.Path,
    *,
    include_sections: PythonDefinitionDocumentationIncludeSections = (
        PythonDefinitionDocumentationIncludeSections()
    ),
    allow_html: bool = False,
    allow_tables: bool = False,
    force: bool = False,
) -> None:
    """
    Generates the documentation for a Python project.

    :param project_directory: The project directory.
    :type project_directory: pathlib.Path
    :param output_directory: The output directory.
    :type output_directory: pathlib.Path
    :param include_sections: The sections to be included in the
                             documentation.
    :type include_sections: PythonDefinitionDocumentationIncludeSections
    :param allow_html: Indicates whether HTML is allowed to appear in
                       the generated documentation.
    :type allow_html: bool
    :param allow_tables: Indicates whether Markdown tables are allowed.
                         Warning: Markdown tables are not CommonMark.
    :param force: Indicates whether the output directory shall be
                  overwritten if it is not empty.
    :type force: bool
    """

    docs_generator = PythonDocumentationGenerator(
        project_directory,
        output_directory,
        include_sections=include_sections,
        allow_html=allow_html,
        allow_tables=allow_tables,
    )
    docs_generator.generate_documentation(force)


def generate(
    project_directory: pathlib.Path,
    output_directory: pathlib.Path,
    *,
    include_sections: list[str] | None = None,
    exclude_sections: list[str] = [],
    allow_html: bool = False,
    allow_tables: bool = False,
    force: bool = False,
) -> None:
    """
    Generates the documentation for a Python project.

    :param project_directory: The project directory.
    :type project_directory: pathlib.Path
    :param output_directory: The output directory.
    :type output_directory: pathlib.Path
    :param include_sections: The sections to be included in the
                             documentation.
    :type include_sections: list[str] | None
    :param exclude_sections: The sections to be excluded in the
                             documentation.
    :type exclude_sections: list[str]
    :param allow_html: Indicates whether HTML is allowed to appear in
                       the generated documentation.
    :type allow_html: bool
    :param allow_tables: Indicates whether Markdown tables are allowed.
                         Warning: Markdown tables are not CommonMark.
    :param force: Indicates whether the output directory shall be
                  overwritten if it is not empty.
    :type force: bool
    """

    sections = parse_sections_list(include_sections, exclude_sections)

    _generate(
        project_directory,
        output_directory,
        include_sections=sections,
        allow_html=allow_html,
        allow_tables=allow_tables,
        force=force,
    )