wexample-wex-addon-dev-python 0.0.48__py3-none-any.whl → 0.0.53__py3-none-any.whl

wexample_wex_addon_dev_python/commands/code/check.py

@@ -44,6 +44,7 @@ def python__code__check(
 ) -> bool:
     """Check a Python file using various code quality tools."""
     from wexample_app.response.failure_response import FailureResponse
+
     from wexample_wex_addon_dev_python.commands.code.check.mypy import _code_check_mypy
     from wexample_wex_addon_dev_python.commands.code.check.pylint import (
         _code_check_pylint,

wexample_wex_addon_dev_python/config_value/python_package_readme_config_value.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import os
 from typing import TYPE_CHECKING
 
 from wexample_filestate.config_value.readme_content_config_value import (
@@ -8,9 +7,6 @@ from wexample_filestate.config_value.readme_content_config_value import (
 )
 from wexample_helpers.classes.field import public_field
 from wexample_helpers.decorator.base_class import base_class
-from wexample_wex_addon_dev_python.workdir.python_package_workdir import (
-    PythonPackageWorkdir,
-)
 
 if TYPE_CHECKING:
     from wexample_wex_addon_dev_python.workdir.python_package_workdir import (
@@ -25,6 +21,71 @@ class PythonPackageReadmeContentConfigValue(ReadmeContentConfigValue):
     )
 
     def get_templates(self) -> list[str] | None:
+        # Prepare context for Jinja2 rendering
+        context = self._get_template_context()
+
+        # Define fixed order of README sections
+        section_names = [
+            "title",
+            "table-of-contents",
+            "status-compatibility",
+            "prerequisites",
+            "installation",
+            "quickstart",
+            "basic-usage",
+            "configuration",
+            "logging",
+            "api-reference",
+            "examples",
+            "tests",
+            "code-quality",
+            "versioning",
+            "changelog",
+            "migration-notes",
+            "roadmap",
+            "troubleshooting",
+            "security",
+            "privacy",
+            "support",
+            "contribution-guidelines",
+            "maintainers",
+            "license",
+            "useful-links",
+            "suite-integration",
+            "compatibility-matrix",
+            "requirements",
+            "dependencies",
+            "links",
+            "suite-signature",
+        ]
+
+        # First pass: collect available sections (excluding title and table-of-contents)
+        available_sections = []
+        for section_name in section_names:
+            if section_name not in ["title", "table-of-contents"]:
+                # Check if section exists
+                if self._section_exists(section_name):
+                    available_sections.append(
+                        {
+                            "name": section_name,
+                            "title": self._section_name_to_title(section_name),
+                            "anchor": section_name.replace("_", "-"),
+                        }
+                    )
+
+        # Add available sections to context for table-of-contents
+        context["available_sections"] = available_sections
+
+        # Render ordered sections (supports both .md and .md.j2)
+        rendered_content = ""
+        for section_name in section_names:
+            section_content = self._render_readme_section(section_name, context)
+            if section_content:
+                rendered_content += f"{section_content}\n\n"
+
+        return [rendered_content]
+
+    def _get_template_context(self) -> dict:
         # Use TOMLDocument from the workdir
         doc = self.workdir.get_project_config()
         project = doc.get("project", {}) if isinstance(doc, dict) else {}
@@ -49,44 +110,140 @@ class PythonPackageReadmeContentConfigValue(ReadmeContentConfigValue):
         # Format dependencies list
         deps_list = "\n".join([f"- {dep}" for dep in dependencies])
 
-        package_name = self.workdir.get_package_name()
-        return [
-            f"# {package_name}\n\n"
-            f"{description}\n\n"
-            f"Version: {self.workdir.get_project_version()}\n\n"
-            f'{self._add_section_if_exists("features")}'
-            "## Requirements\n\n"
-            f"- Python {python_version}\n\n"
-            "## Dependencies\n\n"
-            f"{deps_list}\n\n"
-            "## Installation\n\n"
-            "```bash\n"
-            f"pip install {package_name}\n"
-            "```\n\n"
-            f'{self._add_section_if_exists("usage")}'
-            "## Links\n\n"
-            f"- Homepage: {homepage}\n\n"
-            "## License\n\n"
-            f"{license_info}"
-        ]
+        return {
+            "package_name": self.workdir.get_package_name(),
+            "version": self.workdir.get_project_version(),
+            "description": description,
+            "python_version": python_version,
+            "dependencies": dependencies,
+            "deps_list": deps_list,
+            "homepage": homepage,
+            "license_info": license_info,
+            "workdir": self.workdir,
+        }
 
-    def _add_section_if_exists(self, section: str) -> str:
+    def _render_readme_section(self, section_name: str, context: dict) -> str | None:
         """
-        Returns section content if the documentation file exists
+        Render a README section from .md or .md.j2 file with Jinja2 support.
+
+        Searches in three levels (in order):
+        1. Package-level templates
+        2. Suite-level templates
+        3. Default templates (bundled with the module)
+
+        Tries .md.j2 first, then .md. Both formats support Jinja2 variables.
+
+        Args:
+            section_name: Name of the section (without extension)
+            context: Jinja2 context variables for rendering
+
+        Returns:
+            Rendered content or None if section file not found
         """
-        doc_path = self._get_doc_path(section)
+        from pathlib import Path
+
+        from jinja2 import Environment, FileSystemLoader, TemplateNotFound
+        from wexample_app.const.globals import WORKDIR_SETUP_DIR
+
+        workdir_path = self.workdir.get_path()
+
+        search_paths = [
+            workdir_path / WORKDIR_SETUP_DIR / "knowledge" / "readme",  # Package-level
+        ]
+
+        # Package may have a suite.
+        suite_path = self.workdir.find_suite_workdir_path()
+        if suite_path is not None:
+            search_paths.append(
+                suite_path
+                / WORKDIR_SETUP_DIR
+                / "knowledge"
+                / "package-readme",  # Suite-level
+            )
+
+        # Add default templates path (bundled with the module)
+        default_templates_path = (
+            Path(__file__).parent.parent / "resources" / "readme_templates"
+        )
+        search_paths.append(default_templates_path)
+
+        # Try .md.j2 first (Jinja2 template)
+        for search_path in search_paths:
+            if not search_path.exists():
+                continue
+
+            env = Environment(loader=FileSystemLoader(str(search_path)))
+            try:
+                template = env.get_template(f"{section_name}.md.j2")
+                return template.render(context)
+            except TemplateNotFound:
+                pass
 
-        if os.path.exists(doc_path):
-            with open(doc_path, encoding="utf-8") as file:
-                content = file.read()
-                return f"## {section.title()}\n\n{content}\n\n"
+        # Try .md (static markdown, still rendered with Jinja2)
+        for search_path in search_paths:
+            md_path = search_path / f"{section_name}.md"
+            if md_path.exists():
+                content = md_path.read_text(encoding="utf-8")
+                env = Environment(loader=FileSystemLoader(str(search_path)))
+                template = env.from_string(content)
+                return template.render(context)
 
-        return ""
+        return None
 
-    def _get_doc_path(self, section: str) -> str:
+    def _section_exists(self, section_name: str) -> bool:
         """
-        Returns the path to a documentation section file
+        Check if a section file exists (.md or .md.j2).
+
+        Searches in three levels:
+        1. Package-level templates
+        2. Suite-level templates
+        3. Default templates (bundled with the module)
+
+        Args:
+            section_name: Name of the section (without extension)
+
+        Returns:
+            True if section file exists, False otherwise
         """
-        return os.path.join(
-            self.workdir.get_path(), ".wex", "doc", "readme", f"{section}.md"
+        from pathlib import Path
+
+        from wexample_app.const.globals import WORKDIR_SETUP_DIR
+
+        workdir_path = self.workdir.get_path()
+
+        search_paths = [
+            workdir_path / WORKDIR_SETUP_DIR / "knowledge" / "readme",
+        ]
+
+        # Package may have a suite.
+        suite_path = self.workdir.find_suite_workdir_path()
+        if suite_path is not None:
+            search_paths.append(
+                suite_path / WORKDIR_SETUP_DIR / "knowledge" / "package-readme",
+            )
+
+        # Add default templates path (bundled with the module)
+        default_templates_path = (
+            Path(__file__).parent.parent / "resources" / "readme_templates"
         )
+        search_paths.append(default_templates_path)
+
+        for search_path in search_paths:
+            if (search_path / f"{section_name}.md.j2").exists():
+                return True
+            if (search_path / f"{section_name}.md").exists():
+                return True
+
+        return False
+
+    def _section_name_to_title(self, section_name: str) -> str:
+        """
+        Convert section name to human-readable title.
+
+        Args:
+            section_name: Section name (e.g., "basic-usage")
+
+        Returns:
+            Human-readable title (e.g., "Basic Usage")
+        """
+        return section_name.replace("-", " ").replace("_", " ").title()