Merge pull request #6 from arthur-debert:better-docs

Better devx

Author: arthur-debert

.markdownlint.json

@@ -0,0 +1 @@
+{ "MD013": false, "MD029": false, "MD014": false }

README.md

@@ -35,10 +35,33 @@ Access deeply **nested values** using intuitive dot-separated paths (e.g., **`pe
 
 Dotcat is a good **unix citizen** with well structured **exit codes** so it can take part of your command pipeline like cat or grep would.
 
+Includes **ZSH autocompletion** for both file paths and dotted paths, making it even easier to navigate complex data structures.
+
 ## Installation
 
 If you have a global pip install, this will install dotcat globally:
 
 ```bash
 pip install dotcat
 ```
+
+## ZSH Completion
+
+Dotcat comes with ZSH completion support that is automatically installed when you install the package with pip. The installation script will:
+
+1. Look for appropriate ZSH completion directories
+2. Install the completion files if possible
+3. Notify you of the installation location
+
+If the automatic installation fails, you can manually install the completions:
+
+```bash
+# Copy the completion script to your ZSH completions directory
+mkdir -p ~/.zsh/completions
+cp /path/to/installed/package/zsh/_dotcat ~/.zsh/completions/
+
+# Or run the installation script directly
+dotcat-install-completions
+```
+
+See the [ZSH completion README](zsh/README.md) for detailed instructions.

bin/usage-samples

@@ -0,0 +1,42 @@
+#! /usr/bin/env bash
+
+# Don't exit on error
+set +e
+
+## this files just collects all possible outputs for regular and errors so
+## that we can test the output of the program
+
+# Function to indent each line of input by 4 spaces
+function indent() {
+	sed 's/^/  /'
+}
+
+function run_command() {
+	local description="$2"
+	echo ""
+	echo -e "\033[1m$description: \033[0m"
+	echo ""
+	eval "$1" | indent
+	echo ""
+}
+
+run_command "dotcat" "no arguments, quick usage"
+
+run_command "dotcat --help" "--help"
+
+run_command "dotcat help" "help"
+
+run_command "dotcat pyproject.toml project.authors" "correct usage, both file exists and keys is found"
+
+run_command "dotcat pyproject.toml" "missing dotted-path"
+
+run_command "dotcat project.authors" "missing file"
+
+run_command "dotcat nothere.toml project.authors" "no such file"
+
+run_command "dotcat pyproject.toml project.nothere" "missing dotted-path"
+
+run_command "dotcat tests/fixtures/malformed.json python.editor.tabSize" "malformed file"
+
+# Reset exit behavior
+set -e

pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 packages = [{ include = "dotcat", from = "src" }]
-include = ["templates", "template/**", "LICENSE", "README.md"]
+include = ["templates", "template/**", "LICENSE", "README.md", "zsh/**"]
 exclude = ["tests"]
 
 [project]
-version = "0.9.0"
+version = "0.9.1"
 
 name = "dotcat"
 readme = { file = "README.md", content-type = "text/markdown" }
@@ -79,7 +79,8 @@ docs = [
 
 [project.scripts]
 dotcat = "dotcat:main"
-
+install-dotcat-completions = "dotcat.install_completions:main"
+dotcat-install-completions = "dotcat.install_completions:main"
 
 [tool.pytest.ini_options]
 addopts = "-ra -q"

src/dotcat/__init__.py

@@ -1 +1,4 @@
-from .dotcat import run, main
+from .dotcat import run, main, USAGE, HELP
+from . import install_completions
+
+__all__ = ["run", "main", "USAGE", "HELP", "install_completions"]

src/dotcat/__version__.py

@@ -1,2 +1,38 @@
-import importlib;
-__version__ = importlib.metadata.version('dotcat')
+from importlib import metadata
+import pathlib
+import toml
+
+
+def get_version_from_toml():
+    """
+    Extract version from pyproject.toml file.
+
+    Returns:
+        str: The version string or "unknown" if not found
+    """
+    try:
+        # Find the project root (where pyproject.toml is located)
+        current_file = pathlib.Path(__file__)
+        project_root = (
+            current_file.parent.parent.parent
+        )  # src/dotcat -> src -> project root
+        pyproject_path = project_root / "pyproject.toml"
+
+        if pyproject_path.exists():
+            # Parse pyproject.toml using the toml library
+            pyproject_data = toml.load(pyproject_path)
+            return pyproject_data.get("project", {}).get("version", "unknown")
+    except Exception:
+        pass
+    return "unknown"
+
+
+# Try to get version from package metadata (works when installed)
+try:
+    __version__ = metadata.version("dotcat")
+except metadata.PackageNotFoundError:
+    # Fallback: read version from pyproject.toml (works during development/CI)
+    __version__ = get_version_from_toml()
+
+# Make the function available for testing
+__all__ = ["get_version_from_toml"]