config-cli-gui 0.3.8__tar.gz → 0.3.9__tar.gz

{config_cli_gui-0.3.8 → config_cli_gui-0.3.9}/HISTORY.md

@@ -4,6 +4,13 @@ Changelog
 
 (unreleased)
 ------------
+- Improved cli doc generation: link to config.yaml. [Paul Magister]
+- Improved cli doc generation: no more python -m. [Paul Magister]
+
+
+0.3.8 (2026-10-02)
+------------------
+- Docs: Update HISTORY.md for release 0.3.8. [Paul Magister]
 - Bump python version to <3.14. [Paul Magister]
 
 

{config_cli_gui-0.3.8 → config_cli_gui-0.3.9}/Makefile

@@ -50,7 +50,7 @@ lint:             ## Run pep8, black, mypy linters.
 #	uv run mypy --ignore-missing-imports src/
 
 .PHONY: test
-test: lint        ## Run tests and generate coverage report.
+test: lint example-files  ## Run tests and generate coverage report.
 	uv run pytest -v --cov-config .coveragerc --cov=src -l --tb=short --maxfail=1 tests/
 	uv run coverage xml
 	uv run coverage html
@@ -115,7 +115,7 @@ release:          ## Create a new tag for release.
 	echo "Add modified files to commit and push them to main"
 
 .PHONY: docs
-docs:             ## Build and sync the documentation.
+docs: example-files ## Build and sync the documentation.
 	@echo "sync documentation ..."
 	@uv run ./scripts/update_readme.py
 	@uv run ./.github/update_funding.py
@@ -138,3 +138,8 @@ pytree:            ## Show project tree (excluding ignored folders)
 .PHONY: init
 init:             ## Initialize the project based on an application template.
 	@./.github/init.sh
+
+.PHONY: example-files
+example-files:      ## Regenerate config.yaml and docs from tests/example_project.
+	@echo "Generating example config and docs from tests/example_project..."
+	@uv run python tests/example_project/config/config_example.py

{config_cli_gui-0.3.8/src/config_cli_gui.egg-info → config_cli_gui-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: config-cli-gui
-Version: 0.3.8
+Version: 0.3.9
 Summary: Feature-rich Python project template for config-cli-gui.
 Author: pamagister
 Requires-Python: <3.14,>=3.10

{config_cli_gui-0.3.8 → config_cli_gui-0.3.9}/config.yaml

@@ -10,7 +10,7 @@ app:
   # Enable logging to console | type=bool | choices=[True, False]
   enable_console_logging: true
   # GUI theme setting supported by ttkbootstrap | type=str | choices=['cosmo', 'flatly', 'litera', 'minty', 'lumen', 'sandstone', 'yeti', 'pulse', 'united', 'darkly', 'superhero', 'solar', 'cyborg', 'vapor', 'simplex']
-  theme: superhero
+  theme: darkly
 cli:
   # Path to input (file or folder) | type=str | [CLI]
   input: ''
@@ -34,21 +34,21 @@ gui:
   # Maximum number of log lines to keep in GUI | type=int
   max_log_lines: 1000
   # Point in 2D space | type=Vector
-  point2D: (7.0, 11.0)
+  point2D: (7, 11)
   # Point in 3D space | type=Vector
   point3D: (1.2, 3.4, 5.6)
 misc:
   # Example integer | type=int
   some_numeric: 42
   # Example vector 2D | type=Vector
-  some_vector2d: (1.0, 2.0)
+  some_vector2d: (1, 2)
   # Example vector 3D | type=Vector
   some_vector3d: (1.1, 2.2, 3.3)
-  # Path to the file to use | type=str
+  # Path to the file to use | type=PosixPath
   some_file: some_file.txt
   # Color setting for the application | type=Color
   some_color: '#ff0000'
   # Date setting for the application | type=datetime
-  some_date: '2025-12-31T10:30:00'
+  some_date: '2025-12-31T10:30:45'
   # Font setting for the application | type=Font
-  some_font: 'DejaVuSans.ttf, 12.0, #0000ff'
+  some_font: 'DejaVuSans.ttf, 12, #0000ff'

{config_cli_gui-0.3.8 → config_cli_gui-0.3.9}/docs/usage/cli.md

@@ -3,13 +3,22 @@
 Command line options for app
 
 ```bash
-python -m app [OPTIONS] input
+app [OPTIONS] <input>
+```
+
+For development from a source checkout, the equivalent module invocation is:
+
+```bash
+python -m app [OPTIONS] <input>
 ```
 
 ## Options
 
 | Option                | Type | Description                                       | Default    | Choices       |
 |-----------------------|------|---------------------------------------------------|------------|---------------|
+| --config              | str  | Path to configuration file                        | -          | -             |
+| -v, --verbose         | bool | Enable debug logging                              | False      | [True, False] |
+| -q, --quiet           | bool | Show warnings and errors only                     | False      | [True, False] |
 | `input`               | str  | Path to input (file or folder)                    | *required* | -             |
 | `--output`            | str  | Path to output destination                        | *required* | -             |
 | `--min_dist`          | int  | Maximum distance between two waypoints            | 20         | -             |
@@ -23,37 +32,44 @@ python -m app [OPTIONS] input
 ### 1. Basic usage
 
 ```bash
-python -m app input
+app input
 ```
 
 ### 2. With verbose logging
 
 ```bash
-python -m app -v input
-python -m app --verbose input
+app -v input
+app --verbose input
 ```
 
 ### 3. With quiet mode
 
 ```bash
-python -m app -q input
-python -m app --quiet input
+app -q input
+app --quiet input
 ```
 
-### 4. With min_dist parameter
+### 4. With output parameter
 
 ```bash
-python -m app --min_dist 20 input
+app --output  input
 ```
 
-### 5. With extract_waypoints parameter
+### 5. With min_dist parameter
 
 ```bash
-python -m app --extract_waypoints True input
+app --min_dist 20 input
 ```
 
-### 6. With elevation parameter
+### 6. With extract_waypoints parameter
 
 ```bash
-python -m app --elevation True input
+app --extract_waypoints True input
+```
+
+### Developer usage
+
+```bash
+python -m app --help
+python -m app input
 ```

{config_cli_gui-0.3.8 → config_cli_gui-0.3.9}/docs/usage/config.md

@@ -3,7 +3,16 @@
 These parameters are available to configure the behavior of your application.
 The parameters in the cli category can be accessed via the command line interface.
 
-## Category "app"
+## Configuration File Reference
+
+The actual configuration is stored in [`config.yaml`](../../config.yaml). You can:
+
+- Edit the configuration file directly using your text editor
+- Use the `--config` command-line option to specify a custom config file
+- Place a `config.yaml` in your application's config
+  directory (typically `~/.config/config-cli-gui/`)
+
+## Category "app" {#app}
 
 | Name                   | Type | Description                                 | Default    | Choices                                                                                                                                               |
 |------------------------|------|---------------------------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -14,7 +23,7 @@ The parameters in the cli category can be accessed via the command line interfac
 | enable_console_logging | bool | Enable logging to console                   | True       | [True, False]                                                                                                                                         |
 | theme                  | str  | GUI theme setting supported by ttkbootstrap | 'darkly'   | ['cosmo', 'flatly', 'litera', 'minty', 'lumen', 'sandstone', 'yeti', 'pulse', 'united', 'darkly', 'superhero', 'solar', 'cyborg', 'vapor', 'simplex'] |
 
-## Category "cli"
+## Category "cli" {#cli}
 
 | Name              | Type | Description                                       | Default | Choices       |
 |-------------------|------|---------------------------------------------------|---------|---------------|
@@ -24,7 +33,7 @@ The parameters in the cli category can be accessed via the command line interfac
 | extract_waypoints | bool | Extract starting points of each track as waypoint | True    | [True, False] |
 | elevation         | bool | Include elevation data in waypoints               | False   | [True, False] |
 
-## Category "gui"
+## Category "gui" {#gui}
 
 | Name              | Type   | Description                                    | Default               | Choices       |
 |-------------------|--------|------------------------------------------------|-----------------------|---------------|
@@ -36,7 +45,7 @@ The parameters in the cli category can be accessed via the command line interfac
 | point2D           | Vector | Point in 2D space                              | Vector(7, 11)         | -             |
 | point3D           | Vector | Point in 3D space                              | Vector(1.2, 3.4, 5.6) | -             |
 
-## Category "misc"
+## Category "misc" {#misc}
 
 | Name          | Type      | Description                       | Default                                                      | Choices |
 |---------------|-----------|-----------------------------------|--------------------------------------------------------------|---------|

{config_cli_gui-0.3.8 → config_cli_gui-0.3.9}/src/config_cli_gui/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.8'
-__version_tuple__ = version_tuple = (0, 3, 8)
+__version__ = version = '0.3.9'
+__version_tuple__ = version_tuple = (0, 3, 9)
 
-__commit_id__ = commit_id = 'g250985e4a'
+__commit_id__ = commit_id = 'gddc907973'

config_cli_gui-0.3.9/src/config_cli_gui/docs.py

@@ -0,0 +1,279 @@
+from pathlib import Path
+from textwrap import dedent
+
+from config_cli_gui.config import ConfigManager
+
+
+class DocumentationGenerator:
+    """Generates documentation and configuration files from ConfigManager."""
+
+    def __init__(self, config_manager: ConfigManager):
+        self.config_manager = config_manager
+
+    def generate_config_markdown_doc(
+        self,
+        output_file: str,
+        config_file_path: str | None = "../../config.yaml",
+        link_strategy: str = "relative",
+    ):
+        """Generate Markdown documentation for all configuration parameters.
+
+        Args:
+            output_file: Path where the markdown file will be written
+            config_file_path: Path to the config.yaml file (for creating links)
+                             Can be relative (e.g., "../../config.yaml") or absolute
+            link_strategy: How to generate links to config.yaml:
+                          - "relative": relative path (default, for documentation)
+                          - "file": file:// URI (for file explorer/installed app)
+                          - "none": no links (default if config_file_path is None)
+        """
+
+        def pad(s, width):
+            return s + " " * (width - len(s))
+
+        # Create introduction with link to config file if provided
+        markdown_content = dedent("""
+            # Configuration Parameters
+
+            These parameters are available to configure the behavior of your application.
+            The parameters in the cli category can be accessed via the command line interface.
+
+            """).lstrip()
+
+        # Add config file link if provided
+        if config_file_path:
+            if link_strategy == "file":
+                # Convert to absolute path for file:// URI
+                from pathlib import Path as PathlibPath
+
+                abs_path = PathlibPath(config_file_path).resolve()
+                link = f"file://{abs_path.as_posix()}"
+            else:
+                # Use relative path (default)
+                link = config_file_path
+
+            markdown_content += dedent(f"""
+                ## Configuration File Reference
+
+                The actual configuration is stored in [`config.yaml`]({link}). You can:
+
+                - Edit the configuration file directly using your text editor
+                - Use the `--config` command-line option to specify a custom config file
+                - Place a `config.yaml` in your application's config
+                  directory (typically `~/.config/config-cli-gui/`)
+
+                """).lstrip()
+
+        for category_name, category in self.config_manager._categories.items():
+            # Create anchor-friendly category name
+            category_anchor = category_name.lower().replace(" ", "-")
+            markdown_content += f'## Category "{category_name}" {{#{category_anchor}}}\n\n'
+
+            # Collect all parameters for this category
+            rows = []
+            header = ["Name", "Type", "Description", "Default", "Choices"]
+
+            for param in category.get_parameters():
+                name = param.name
+                typ = type(param.value).__name__
+                desc = param.help
+                value = repr(param.value)
+                choices = str(param.choices) if param.choices else "-"
+
+                rows.append((name, typ, desc, value, choices))
+
+            if not rows:
+                continue
+
+            # Calculate column widths
+            all_rows = [header] + rows
+            widths = [max(len(str(col)) for col in column) for column in zip(*all_rows)]
+
+            # Create Markdown table
+            table = (
+                "| "
+                + " | ".join(pad(h, w) for h, w in zip(header, widths))
+                + " |\n"
+                + "|-"
+                + "-|-".join("-" * w for w in widths)
+                + "-|\n"
+            )
+            for row in rows:
+                table += "| " + " | ".join(pad(str(col), w) for col, w in zip(row, widths)) + " |\n"
+
+            markdown_content += table + "\n"
+
+        # Write to file
+        Path(output_file).parent.mkdir(parents=True, exist_ok=True)
+        with open(output_file, "w", encoding="utf-8") as f:
+            f.write(markdown_content)
+
+    def generate_default_config_file(self, output_file: str):
+        """Generate a default configuration file with all parameters and descriptions."""
+        output_path = Path(output_file)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        self.config_manager.save_to_file(output_path.as_posix())
+
+    def generate_cli_markdown_doc(self, output_file: str, app_name: str = "app"):
+        """Generate Markdown CLI documentation.
+
+        The generated doc prefers the installed command for end users (for example
+        ``gpx-kml-converter --help``), while still including the direct module
+        invocation as a development fallback (``python -m gpx_kml_converter``).
+        """
+        cli_params = self.config_manager.get_cli_parameters()
+
+        if not cli_params:
+            return
+
+        base_app_name = (app_name or self.config_manager.get_app_name()).strip() or "app"
+        command_name = base_app_name.replace("_", "-")
+        module_name = base_app_name.replace("-", "_")
+
+        rows = [
+            ("--config", "str", "Path to configuration file", "-", "-"),
+            ("-v, --verbose", "bool", "Enable debug logging", "False", "[True, False]"),
+            (
+                "-q, --quiet",
+                "bool",
+                "Show warnings and errors only",
+                "False",
+                "[True, False]",
+            ),
+        ]
+        required_params = []
+        optional_params = []
+
+        for param in cli_params:
+            cli_arg = (
+                f"`{param.name}`" if param.required else (f"`{param.cli_arg or f'--{param.name}'}`")
+            )
+            typ = type(param.value).__name__
+            desc = param.help
+            value = (
+                "*required*" if param.required or param.value in (None, "") else repr(param.value)
+            )
+            choices = str(param.choices) if param.choices else "-"
+
+            rows.append((cli_arg, typ, desc, value, choices))
+            if param.required:
+                required_params.append(param)
+            else:
+                optional_params.append(param)
+
+        # Generate table
+        def pad(s, width):
+            return s + " " * (width - len(s))
+
+        header = ["Option", "Type", "Description", "Default", "Choices"]
+        widths = [max(len(str(col)) for col in column) for column in zip(*rows, strict=False)]
+
+        table = dedent(
+            "| "
+            + " | ".join(pad(h, w) for h, w in zip(header, widths, strict=False))
+            + " |\n"
+            + "|-"
+            + "-|-".join("-" * w for w in widths)
+            + "-|\n"
+        )
+        for row in rows:
+            table += (
+                "| "
+                + " | ".join(pad(str(col), w) for col, w in zip(row, widths, strict=False))
+                + " |\n"
+            )
+
+        required_arg_names = [param.name for param in required_params]
+        required_target = (
+            " ".join(f"<{name}>" for name in required_arg_names) if required_arg_names else "input"
+        )
+        usage_command = f"{command_name} [OPTIONS] {required_target}".strip()
+        usage_module = f"python -m {module_name} [OPTIONS] {required_target}".strip()
+
+        examples = []
+        primary_target = required_arg_names[0] if required_arg_names else "input"
+
+        examples.append(
+            dedent(f"""
+            ### 1. Basic usage
+
+            ```bash
+            {command_name} {primary_target}
+            ```
+            """)
+        )
+
+        examples.append(
+            dedent(f"""
+            ### 2. With verbose logging
+
+            ```bash
+            {command_name} -v {primary_target}
+            {command_name} --verbose {primary_target}
+            ```
+            """)
+        )
+
+        examples.append(
+            dedent(f"""
+            ### 3. With quiet mode
+
+            ```bash
+            {command_name} -q {primary_target}
+            {command_name} --quiet {primary_target}
+            ```
+            """)
+        )
+
+        for i, param in enumerate(optional_params[:3], 4):
+            if param.name in {"verbose", "quiet", "config"}:
+                continue
+            example_value = param.choices[0] if param.choices else param.value
+            examples.append(
+                dedent(f"""
+                ### {i}. With {param.name} parameter
+
+                ```bash
+                {command_name} --{param.name} {example_value} {primary_target}
+                ```
+                """)
+            )
+
+        examples.append(
+            dedent(f"""
+            ### Developer usage
+
+            ```bash
+            python -m {module_name} --help
+            python -m {module_name} {primary_target}
+            ```
+            """)
+        )
+
+        markdown = dedent(f"""
+# Command Line Interface
+
+Command line options for {base_app_name}
+
+```bash
+{usage_command}
+```
+
+For development from a source checkout, the equivalent module invocation is:
+
+```bash
+{usage_module}
+```
+
+## Options
+
+{table}
+
+## Examples
+
+            {"".join(examples)}
+            """).strip()
+
+        Path(output_file).parent.mkdir(parents=True, exist_ok=True)
+        with open(output_file, "w", encoding="utf-8") as f:
+            f.write(markdown)

{config_cli_gui-0.3.8 → config_cli_gui-0.3.9/src/config_cli_gui.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: config-cli-gui
-Version: 0.3.8
+Version: 0.3.9
 Summary: Feature-rich Python project template for config-cli-gui.
 Author: pamagister
 Requires-Python: <3.14,>=3.10

{config_cli_gui-0.3.8 → config_cli_gui-0.3.9}/src/config_cli_gui.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.3.8",
+  "tag": "0.3.9",
   "distance": 0,
-  "node": "g250985e4a0c10f70ecf64392a37ba8294e8c45ae",
+  "node": "gddc9079730c4ede01e053a2bc94b1a9bf2c7a81e",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-10-02"

{config_cli_gui-0.3.8 → config_cli_gui-0.3.9}/tests/example_project/config/config_example.py

@@ -196,7 +196,12 @@ def main():
     doc_gen.generate_default_config_file(output_file=default_config)
     print(f"Generated: {default_config}")
 
-    doc_gen.generate_config_markdown_doc(output_file=default_config_doc)
+    # Generate config markdown with link to config.yaml
+    doc_gen.generate_config_markdown_doc(
+        output_file=default_config_doc,
+        config_file_path="../../config.yaml",
+        link_strategy="relative",
+    )
     print(f"Generated: {default_config_doc}")
 
     doc_gen.generate_cli_markdown_doc(output_file=default_cli_doc)

config_cli_gui-0.3.8/src/config_cli_gui/docs.py

@@ -1,203 +0,0 @@
-from pathlib import Path
-from textwrap import dedent
-
-from config_cli_gui.config import ConfigManager
-
-
-class DocumentationGenerator:
-    """Generates documentation and configuration files from ConfigManager."""
-
-    def __init__(self, config_manager: ConfigManager):
-        self.config_manager = config_manager
-
-    def generate_config_markdown_doc(self, output_file: str):
-        """Generate Markdown documentation for all configuration parameters."""
-
-        def pad(s, width):
-            return s + " " * (width - len(s))
-
-        markdown_content = dedent(
-            """
-            # Configuration Parameters
-
-            These parameters are available to configure the behavior of your application.
-            The parameters in the cli category can be accessed via the command line interface.
-
-            """
-        ).lstrip()
-
-        for category_name, category in self.config_manager._categories.items():
-            markdown_content += f'## Category "{category_name}"\n\n'
-
-            # Collect all parameters for this category
-            rows = []
-            header = ["Name", "Type", "Description", "Default", "Choices"]
-
-            for param in category.get_parameters():
-                name = param.name
-                typ = type(param.value).__name__
-                desc = param.help
-                value = repr(param.value)
-                choices = str(param.choices) if param.choices else "-"
-
-                rows.append((name, typ, desc, value, choices))
-
-            if not rows:
-                continue
-
-            # Calculate column widths
-            all_rows = [header] + rows
-            widths = [max(len(str(col)) for col in column) for column in zip(*all_rows)]
-
-            # Create Markdown table
-            table = (
-                "| "
-                + " | ".join(pad(h, w) for h, w in zip(header, widths))
-                + " |\n"
-                + "|-"
-                + "-|-".join("-" * w for w in widths)
-                + "-|\n"
-            )
-            for row in rows:
-                table += "| " + " | ".join(pad(str(col), w) for col, w in zip(row, widths)) + " |\n"
-
-            markdown_content += table + "\n"
-
-        # Write to file
-        Path(output_file).parent.mkdir(parents=True, exist_ok=True)
-        with open(output_file, "w", encoding="utf-8") as f:
-            f.write(markdown_content)
-
-    def generate_default_config_file(self, output_file: str):
-        """Generate a default configuration file with all parameters and descriptions."""
-        output_path = Path(output_file)
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-        self.config_manager.save_to_file(output_path.as_posix())
-
-    def generate_cli_markdown_doc(self, output_file: str, app_name: str = "app"):
-        """Generate Markdown CLI documentation."""
-        cli_params = self.config_manager.get_cli_parameters()
-
-        if not cli_params:
-            return
-
-        rows = []
-        required_params = []
-        optional_params = []
-
-        for param in cli_params:
-            cli_arg = f"`--{param.name}`" if not param.required else f"`{param.name}`"
-            typ = type(param.value).__name__
-            desc = param.help
-            value = (
-                "*required*" if param.required or param.value in (None, "") else repr(param.value)
-            )
-            choices = str(param.choices) if param.choices else "-"
-
-            rows.append((cli_arg, typ, desc, value, choices))
-            if value == "*required*":
-                required_params.append(param)
-            else:
-                optional_params.append(param)
-
-        # Generate table
-        def pad(s, width):
-            return s + " " * (width - len(s))
-
-        widths = [max(len(str(col)) for col in column) for column in zip(*rows)]
-        header = ["Option", "Type", "Description", "Default", "Choices"]
-
-        table = (
-            "| "
-            + " | ".join(pad(h, w) for h, w in zip(header, widths))
-            + " |\n"
-            + "|-"
-            + "-|-".join("-" * w for w in widths)
-            + "-|\n"
-        )
-        for row in rows:
-            table += "| " + " | ".join(pad(str(col), w) for col, w in zip(row, widths)) + " |\n"
-
-        # Generate examples
-        examples = []
-        required_arg = required_params[0].name if required_params else "example.input"
-
-        examples.append(
-            dedent(
-                f"""
-            ### 1. Basic usage
-
-            ```bash
-            python -m {app_name} {required_arg}
-            ```
-            """
-            )
-        )
-
-        # Add logging examples
-        examples.append(
-            dedent(
-                f"""
-        ### 2. With verbose logging
-
-        ```bash
-        python -m {app_name} -v {required_arg}
-        python -m {app_name} --verbose {required_arg}
-        ```
-        """
-            )
-        )
-
-        examples.append(
-            dedent(
-                f"""
-        ### 3. With quiet mode
-
-        ```bash
-        python -m {app_name} -q {required_arg}
-        python -m {app_name} --quiet {required_arg}
-        ```
-        """
-            )
-        )
-
-        # Add more examples with optional parameters
-        for i, param in enumerate(optional_params[:3], 4):
-            if param.name in ["verbose", "quiet"]:
-                continue
-            example_value = param.choices[0] if param.choices else param.value
-            examples.append(
-                dedent(
-                    f"""
-                ### {i}. With {param.name} parameter
-
-                ```bash
-                python -m {app_name} --{param.name} {example_value} {required_arg}
-                ```
-                """
-                )
-            )
-
-        markdown = dedent(
-            f"""
-            # Command Line Interface
-
-Command line options for {app_name}
-
-```bash
-python -m {app_name} [OPTIONS] {required_arg if required_params else ""}
-```
-
-## Options
-
-{table}
-
-## Examples
-
-            {"".join(examples)}
-            """
-        ).strip()
-
-        Path(output_file).parent.mkdir(parents=True, exist_ok=True)
-        with open(output_file, "w", encoding="utf-8") as f:
-            f.write(markdown)