generated from jCloud/repository-template
156 lines
5.2 KiB
Python
156 lines
5.2 KiB
Python
# 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,
|
|
)
|