diff --git a/src/jcloud_docsgen/cli/cli.py b/src/jcloud_docsgen/cli/cli.py index 0189116..70864b6 100644 --- a/src/jcloud_docsgen/cli/cli.py +++ b/src/jcloud_docsgen/cli/cli.py @@ -22,6 +22,9 @@ __all__ = [ import argparse import pathlib +from .parsers.python import VALID_SECTIONS as VALID_PYTHON_SECTIONS + +_LANG_PYTHON = 'python' def existing_directory(path: str) -> pathlib.Path: _path = path @@ -33,12 +36,72 @@ def existing_directory(path: str) -> pathlib.Path: return path def main() -> int: + common_parser = argparse.ArgumentParser(add_help = False) + common_parser.add_argument( + 'project_directory', + type = existing_directory, + nargs = '?', + default = pathlib.Path('.'), + help = 'The directory of the project' + ) + common_parser.add_argument( + '-o', + '--output-dir', + type = pathlib.Path, + help = 'the output directory the documentation will be written to' + ) + argument_parser = argparse.ArgumentParser() - argument_parser.add_argument('project_directory', type = existing_directory, nargs = '?', default = pathlib.Path('.'), help = 'The directory of the project') - argument_parser.add_argument('-o', '--output-dir', type = pathlib.Path, help = 'the output directory the documentation will be written to') + + subparsers = argument_parser.add_subparsers(dest = 'language', required = True) + + python_parser = subparsers.add_parser( + _LANG_PYTHON, + parents = [common_parser], + help = 'generate documentation for Python project' + ) + python_parser.add_argument( + '-s', + '--sections', + nargs = '+', + choices = VALID_PYTHON_SECTIONS, + help = 'the sections to be included in the documentation' + ) + python_parser.add_argument( + '-S', + '--sections-exclude', + nargs = '+', + default = [], + choices = VALID_PYTHON_SECTIONS, + help = 'the sections to be excluded in the documentation. If a section shall be included AND excluded, it is excluded.' + ) + python_parser.add_argument( + '-H', + '--allow-html', + action = 'store_true', + help = 'indicates whether HTML is allowed in the documentation. By default, HTML is disabled.' + ) + python_parser.add_argument( + '-T', + '--allow-tables', + action = 'store_true', + help = 'indicates whether Markdown tables are allowed in the documentation. By default, Markdown tables are disabled. Warning: Markdown tables are not CommonMark.' + ) + args = argument_parser.parse_args() if args.output_dir is None: args.output_dir = args.project_directory / 'docs/reference' + if args.language == _LANG_PYTHON: + from .parsers.python import generate + generate( + args.project_directory, + args.output_dir, + include_sections = args.sections, + exclude_sections = args.sections_exclude, + allow_html = args.allow_html, + allow_tables = args.allow_tables + ) + return 0 diff --git a/src/jcloud_docsgen/cli/parsers/__init__.py b/src/jcloud_docsgen/cli/parsers/__init__.py new file mode 100644 index 0000000..f774970 --- /dev/null +++ b/src/jcloud_docsgen/cli/parsers/__init__.py @@ -0,0 +1,19 @@ +# 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. + +from . import python + +__all__ = [ + 'python' +] diff --git a/src/jcloud_docsgen/cli/parsers/python.py b/src/jcloud_docsgen/cli/parsers/python.py new file mode 100644 index 0000000..d67600a --- /dev/null +++ b/src/jcloud_docsgen/cli/parsers/python.py @@ -0,0 +1,114 @@ +# 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 +from typing import Optional + +__all__ = [ + 'VALID_SECTIONS', + 'generate' +] + +VALID_SECTIONS = list(PythonDefinitionDocumentationIncludeSections()._args.keys()) + +def _generate( + project_directory: pathlib.Path, + output_directory: pathlib.Path, + *, + include_sections: PythonDefinitionDocumentationIncludeSections = PythonDefinitionDocumentationIncludeSections(), + allow_html: bool = False, + allow_tables: 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. + ''' + + docs_generator = PythonDocumentationGenerator( + project_directory, + output_directory, + include_sections = include_sections, + allow_html = allow_html, + allow_tables = allow_tables + ) + docs_generator.generate_documentation() + +def generate( + project_directory: pathlib.Path, + output_directory: pathlib.Path, + *, + include_sections: Optional[list[str]] = None, + exclude_sections: list[str] = [], + allow_html: bool = False, + allow_tables: 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: Optional[list[str]] + :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. + ''' + + 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)] + + sections = 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 + ) if include_sections else PythonDefinitionDocumentationIncludeSections() + + _generate( + project_directory, + output_directory, + include_sections = sections, + allow_html = allow_html, + allow_tables = allow_tables + )