docs: add README

Author: foosel

README.md

@@ -0,0 +1,86 @@
+# gcode-thumbnail-tool
+
+A small tool to analyse and extract thumbnails rendered into GCODE files.
+
+## Installation
+
+```
+pip install gcode-thumbnail-tool
+```
+
+## Usage
+
+### As a Python library
+
+```python
+import gcode_thumbnail_tool as gtt
+
+path = "/path/to/a/file.gcode"
+thumbnails = gtt.extract_thumbnails_from_gcode_file(path)
+
+if result:
+    print(
+        f'Found {len(result.images)} thumbnails in {args.path}, in format "{result.extractor}":'
+    )
+    for image in result.images:
+        print(f"\t{image.format} @ {image.width}x{image.height}")
+else:
+    print(f"Didn't find any thumbnails in {args.path}")
+```
+
+See `gcode_thumbnail_tool.py:main` and `tests/test_api.py` for more usage examples.
+
+### As a command line tool
+
+<!--INSERT:help-->
+
+```
+usage: gcode-thumbnail-tool [-h] [--verbose] {extract,analyse} ...
+
+A small CLI tool to extract thumbnail images from GCODE files.
+
+positional arguments:
+  {extract,analyse}
+    extract          extracts thumbnails from the provided file as PNGs
+    analyse          provides information on the GCODE file's thumbnails
+
+options:
+  -h, --help         show this help message and exit
+  --verbose, -v      increase logging verbosity
+```
+
+<!--/INSERT:help-->
+
+#### `extract`
+
+<!--INSERT:extract-->
+
+```
+usage: gcode-thumbnail-tool extract [-h] [-o OUTPUT] path
+
+positional arguments:
+  path                  path to the GCODE file
+
+options:
+  -h, --help            show this help message and exit
+  -o OUTPUT, --output OUTPUT
+                        output path for the extracted thumbnails
+```
+
+<!--/INSERT:extract-->
+
+#### `analyse`
+
+<!--INSERT:analyse-->
+
+```
+usage: gcode-thumbnail-tool analyse [-h] path
+
+positional arguments:
+  path        path to the GCODE file
+
+options:
+  -h, --help  show this help message and exit
+```
+
+<!--/INSERT:analyse-->

Taskfile.yml

@@ -0,0 +1,28 @@
+version: "3"
+
+tasks:
+  update-readme:
+    cmds:
+      - |
+        help_output=$(gcode-thumbnail-tool)
+        extract_output=$(gcode-thumbnail-tool extract --help)
+        analyse_output=$(gcode-thumbnail-tool analyse --help)
+
+        awk -i inplace -v text="$help_output" '
+          BEGIN{p=1}
+          $1=="<!--INSERT:help-->"{p=0;print;next}
+          $1=="<!--/INSERT:help-->"{print "```\n" text "\n```"; p=1}
+          p
+        ' README.md
+        awk -i inplace -v text="$extract_output" '
+          BEGIN{p=1}
+          $1=="<!--INSERT:extract-->"{p=0;print;next}
+          $1=="<!--/INSERT:extract-->"{print "```\n" text "\n```"; p=1}
+          p
+        ' README.md
+        awk -i inplace -v text="$analyse_output" '
+          BEGIN{p=1}
+          $1=="<!--INSERT:analyse-->"{p=0;print;next}
+          $1=="<!--/INSERT:analyse-->"{print "```\n" text "\n```"; p=1}
+          p
+        ' README.md

gcode_thumbnail_tool.py

@@ -504,23 +504,29 @@ def main():
 
     parser = argparse.ArgumentParser(
         prog="gcode-thumbnail-tool",
-        description="A small CLI tool to extract thumbnail images from GCODE files",
+        description="A small CLI tool to extract thumbnail images from GCODE files.",
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        dest="verbosity",
+        action="count",
+        help="increase logging verbosity",
     )
-    parser.add_argument("--verbose", "-v", dest="verbosity", action="count")
     subparsers = parser.add_subparsers(dest="subcommand")
 
     extract_parser = subparsers.add_parser(
-        "extract", help="Extracts thumbnails from the provided file as PNGs"
+        "extract", help="extracts thumbnails from the provided file as PNGs"
     )
-    extract_parser.add_argument("path", help="Path to the GCODE file")
+    extract_parser.add_argument("path", help="path to the GCODE file")
     extract_parser.add_argument(
-        "-o", "--output", dest="output", help="Output path for the extracted thumbnails"
+        "-o", "--output", dest="output", help="output path for the extracted thumbnails"
     )
 
     analyse_parser = subparsers.add_parser(
-        "analyse", help="Provides information on the GCODE file's thumbnails"
+        "analyse", help="provides information on the GCODE file's thumbnails"
     )
-    analyse_parser.add_argument("path", help="Path to the GCODE file")
+    analyse_parser.add_argument("path", help="path to the GCODE file")
 
     args = parser.parse_args()
     if not args.subcommand:

pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gcode-thumbnail-tool"
-description = "Small tool to analyse and extract thumbnails rendered into GCODE files"
-version = "1.0.0"
+description = "A small tool to analyse and extract thumbnails rendered into GCODE files"
+version = "0.1.0"
 dependencies = [
     "Pillow>=1.11.3",
 ]