documentation and ruff fixes

Author: FredHappyface

README.md

@@ -12,6 +12,28 @@
 
 <img src="readme-assets/icons/name.png" alt="Project Icon" width="750">
 
+Generate custom themes for your Nintendo Switch from your images, with optional
+configuration for layout adjustments. Specify the path to the `nxtheme` executable
+and provide the directory for your input images, output files, and an optional
+configuration file.
+
+**Usage**:
+
+```bash
+usage: nxtheme-creator [-h] [--input INPUT] [--output OUTPUT] [--config CONFIG] nxtheme
+```
+
+**Arguments**:
+
+- `nxtheme`: The path to the `nxtheme` executable (e.g., `/path/to/SwitchThemes.exe`). This can be obtained from [SwitchThemeInjector](https://github.com/exelix11/SwitchThemeInjector).
+
+**Options**:
+
+- `-h, --help`: Show help message and exit.
+- `--input INPUT`: Specify the directory containing your input images.
+- `--output OUTPUT`: Define the directory where the generated theme files will be saved.
+- `--config CONFIG`: Provide an optional configuration file (`conf.json`) to customize layout settings.
+
 - [Documentation](#documentation)
 - [Install With PIP](#install-with-pip)
 - [Language information](#language-information)
@@ -41,8 +63,8 @@ where to look for certain things:
 - The [Technical Reference](/documentation/reference) documents APIs and other aspects of the
   machinery. This documentation describes how to use the classes and functions at a lower level
   and assume that you have a good high-level understanding of the software.
-- The [Help](/documentation/help) guide provides a starting point and outlines common issues that you
-  may have.
+<!-- - The [Help](/documentation/help) guide provides a starting point and outlines common issues that you
+  may have. -->
 
 ## Install With PIP
 

documentation/reference/nxtheme_creator/index.md

@@ -10,7 +10,7 @@
 
 ## cli
 
-[Show source in __init__.py:14](../../../nxtheme_creator/__init__.py#L14)
+[Show source in __init__.py:17](../../../nxtheme_creator/__init__.py#L17)
 
 Cli entry point.
 

documentation/reference/nxtheme_creator/process_themes.md

@@ -11,31 +11,112 @@
 
 ## processImages
 
-[Show source in process_themes.py:51](../../../nxtheme_creator/process_themes.py#L51)
+[Show source in process_themes.py:101](../../../nxtheme_creator/process_themes.py#L101)
+
+   Process images from the specified input directory to generate Nintendo Switch themes. This
+function handles the following tasks:
+   1. Walks through the input directory to collect images and associate them with themes.
+   2. Resolves and validates configuration paths for layout files.
+   3. Iterates over each theme and its components, and builds the theme files using the `nxtheme`
+executable.
+
+#### Arguments
+
+- `nxthemebin` *str* - The path to the `nxtheme` executable used for building themes.
+- `inputdir` *str* - The directory containing the input images for the themes.
+- `outputdir` *str* - The directory where the generated theme files will be saved.
+- `config` *dict* - A dictionary containing configuration options such as the author name,
+and paths to layout files.
+
+#### Returns
+
+None
 
 #### Signature
 
 ```python
-def processImages(nxthemebin: str, inputdir: str, outputdir: str, config: dict): ...
+def processImages(
+    nxthemebin: str, inputdir: str, outputdir: str, config: dict
+) -> None: ...
 ```
 
 
 
 ## resolveConf
 
-[Show source in process_themes.py:33](../../../nxtheme_creator/process_themes.py#L33)
+[Show source in process_themes.py:69](../../../nxtheme_creator/process_themes.py#L69)
+
+Resolve the file paths for layout configurations specified in the `conf` dictionary.
+This function checks if the specified layout files exist. If they do not, it attempts
+to find the files in a default `Layouts` directory relative to the `nxthemebin` executable.
+If the files are still not found, it tries to append `.json` to the filenames and checks again.
+
+#### Arguments
+
+   - `nxthemebin` *str* - The path to the `nxtheme` executable, used to locate the default
+`Layouts` directory.
+   - `conf` *dict* - A dictionary containing layout configuration. The keys should be screen types
+(e.g., 'home', 'lock') and the values should be file paths or filenames.
+
+#### Returns
+
+Type: *dict*
+The updated `conf` dictionary with resolved file paths.
 
 #### Signature
 
 ```python
-def resolveConf(nxthemebin: str, conf: dict): ...
+def resolveConf(nxthemebin: str, conf: dict) -> dict: ...
 ```
 
 
 
 ## walkfiletree
 
-[Show source in process_themes.py:9](../../../nxtheme_creator/process_themes.py#L9)
+[Show source in process_themes.py:11](../../../nxtheme_creator/process_themes.py#L11)
+
+Create a theme_image_map from an input directory by walking the dir and getting
+theme names and corresponding images for each component.
+
+#### Arguments
+
+- `inputdir` *str* - the directory to walk
+
+#### Returns
+
+Type: *dict*
+the final theme_image_map
+
+**Example**:
+   Given the following directory structure:
+
+```
+input_directory/
+├── ThemeA/
+│   ├── home.jpg
+│   ├── lock.jpg
+│   └── apps,news.jpg
+└── ThemeB/
+    ├── home.dds
+    └── lock.dds
+```
+
+Calling `walkfiletree("input_directory")` would produce:
+
+```json
+{
+    "ThemeA": {
+        "home": "/path/to/input_directory/ThemeA/home.jpg",
+        "lock": "/path/to/input_directory/ThemeA/lock.jpg",
+        "apps": "/path/to/input_directory/ThemeA/apps,news.jpg",
+        "news": "/path/to/input_directory/ThemeA/apps,news.jpg"
+    },
+    "ThemeB": {
+        "home": "/path/to/input_directory/ThemeB/home.dds",
+        "lock": "/path/to/input_directory/ThemeB/lock.dds"
+    }
+}
+```
 
 #### Signature
 

documentation/tutorials/README.md

@@ -7,15 +7,15 @@ This tutorial will guide you through using the `nxtheme-creator` tool to generat
 
 install with python-pip nxtheme-creator
 
-```
+```sh
 python3 -m pip install
 ```
 
 ## **Step 2: Prepare Your Images**
 
 **Create an Input Directory**: Organize your images in a directory. The directory structure should look like this:
 
-```
+```sh
 themes_directory/
 ├── theme1/
 │   ├── home.jpg
@@ -65,12 +65,12 @@ Note that items ["home", "lock", "apps", "set", "user", "news"] are configured w
 Open your terminal or command prompt and run the following command to generate your theme:
 
 ```bash
-python3 -m nxtheme-creator --nxtheme /path/to/nxtheme.exe --input input_directory --output output_directory --config conf.json
+python3 -m nxtheme-creator --nxtheme /path/to/SwitchThemes.exe --input input_directory --output output_directory --config conf.json
 ```
 
 Replace:
 
-- `/path/to/nxtheme.exe` with the path to the `nxtheme` executable.
+- `/path/to/SwitchThemes.exe` with the path to the `nxtheme` executable.
 - `input_directory` with the path to your images. This defaults to the directory you run `nxtheme-creator` from
 - `output_directory` with the directory where you want to save the generated theme files.This defaults to `./output/`
 - `conf.json` with the path to your configuration file. Note this is optional, though needed if you wish to customise the layouts or set an `author_name`
@@ -79,15 +79,15 @@ Replace:
 
 Assuming you have the following setup:
 
-- `nxtheme.exe` located at `/path/to/nxtheme.exe`
+- `SwitchThemes.exe` located at `/path/to/SwitchThemes.exe`
 - Input directory is `./input_images`
 - Output directory is `./themes`
 - Configuration file is `./conf.json`
 
 Run the command:
 
 ```bash
-python3 -m nxtheme-creator --nxtheme /path/to/nxtheme.exe --input ./input_images --output ./themes --config ./conf.json
+python3 -m nxtheme-creator --nxtheme /path/to/SwitchThemes.exe --input ./input_images --output ./themes --config ./conf.json
 ```
 
 ## **Step 5: Verify and Install Your Theme**
@@ -99,4 +99,4 @@ python3 -m nxtheme-creator --nxtheme /path/to/nxtheme.exe --input ./input_images
 ## **Troubleshooting**
 
 - **Missing Images**: Ensure all required images are present and correctly named in your input directory.
-- **Executable Issues**: Make sure the path to `nxtheme.exe` is correct and that you have the necessary permissions to run it.
+- **Executable Issues**: Make sure the path to `SwitchThemes.exe` is correct and that you have the necessary permissions to run it.

nxtheme_creator/__init__.py

@@ -1,4 +1,7 @@
-""" """
+"""Generate custom themes for your Nintendo Switch from your images, with optional
+configuration for layout adjustments. Specify the path to the `nxtheme` executable
+and provide the directory for your input images, output files, and an optional
+configuration file."""
 
 from __future__ import annotations
 
@@ -17,7 +20,7 @@ def cli() -> None:  # pragma: no cover
 
 	parser.add_argument(
 		"nxtheme",
-		help="Nxtheme command to use. eg /path/to/nxtheme.exe, obtain from https://github.com/exelix11/SwitchThemeInjector",
+		help="Nxtheme command to use. eg /path/to/SwitchThemes.exe, obtain from https://github.com/exelix11/SwitchThemeInjector",
 	)
 	parser.add_argument("--input", help="input directory", default=".")
 	parser.add_argument("--output", help="output directory", default="./output/")

nxtheme_creator/process_themes.py

@@ -1,3 +1,5 @@
+"""Underlying machineary to generate custom themes for your Nintendo Switch from your images. """
+
 import os
 import re
 import subprocess
@@ -7,19 +9,53 @@
 
 
 def walkfiletree(inputdir: str) -> dict:
+	"""Create a theme_image_map from an input directory by walking the dir and getting
+	theme names and corresponding images for each component.
+
+	:param str inputdir: the directory to walk
+	:return dict: the final theme_image_map
+
+	**Example**:
+    Given the following directory structure:
+    ```
+    input_directory/
+    ├── ThemeA/
+    │   ├── home.jpg
+    │   ├── lock.jpg
+    │   └── apps,news.jpg
+    └── ThemeB/
+        ├── home.dds
+        └── lock.dds
+    ```
+    Calling `walkfiletree("input_directory")` would produce:
+    ```json
+    {
+        "ThemeA": {
+            "home": "/path/to/input_directory/ThemeA/home.jpg",
+            "lock": "/path/to/input_directory/ThemeA/lock.jpg",
+            "apps": "/path/to/input_directory/ThemeA/apps,news.jpg",
+            "news": "/path/to/input_directory/ThemeA/apps,news.jpg"
+        },
+        "ThemeB": {
+            "home": "/path/to/input_directory/ThemeB/home.dds",
+            "lock": "/path/to/input_directory/ThemeB/lock.dds"
+        }
+    }
+    ```
+	"""
 	theme_image_map = {}
 
 	# Walk over directories under inputdir
-	for root, dirs, files in os.walk(inputdir):
+	for root, _dirs, files in os.walk(inputdir):
 		for file in files:
 			if file.endswith((".jpg", ".dds")):
 				# Extract theme name from the directory structure
-				theme_name = os.path.basename(root)
+				theme_name = Path(root).name
 
 				if theme_name not in theme_image_map:
 					theme_image_map[theme_name] = {}
 
-				# Extract the screen types from the image name (e.g., 'home,lock.jpg')
+				# Extract the screen types from the image name e.g., 'home,lock.jpg'
 				screen_types = re.match(r"(\w+(,\w+)*)", file).group(1)
 
 				# Split by comma and map each screen type to the image path
@@ -30,7 +66,20 @@ def walkfiletree(inputdir: str) -> dict:
 	return theme_image_map
 
 
-def resolveConf(nxthemebin: str, conf: dict):
+def resolveConf(nxthemebin: str, conf: dict) -> dict:
+	"""
+    Resolve the file paths for layout configurations specified in the `conf` dictionary.
+    This function checks if the specified layout files exist. If they do not, it attempts
+    to find the files in a default `Layouts` directory relative to the `nxthemebin` executable.
+    If the files are still not found, it tries to append `.json` to the filenames and checks again.
+
+    :param str nxthemebin: The path to the `nxtheme` executable, used to locate the default
+	`Layouts` directory.
+    :param dict conf: A dictionary containing layout configuration. The keys should be screen types
+	(e.g., 'home', 'lock') and the values should be file paths or filenames.
+
+    :return dict: The updated `conf` dictionary with resolved file paths.
+	"""
 	for screen_type in SCREEN_TYPES:
 		fname = conf.get(screen_type)
 		if fname is None:
@@ -43,12 +92,29 @@ def resolveConf(nxthemebin: str, conf: dict):
 				if not layout.exists():
 					layout = Path(nxthemebin).parent / "Layouts" / layout.name
 					if not layout.exists():
-						raise RuntimeError(f"{conf[screen_type]} or {layout} does not exist :(")
+						msg = f"{conf[screen_type]} or {layout} does not exist :("
+						raise RuntimeError(msg)
 		conf[screen_type] = layout
 	return conf
 
 
-def processImages(nxthemebin: str, inputdir: str, outputdir: str, config: dict):
+def processImages(nxthemebin: str, inputdir: str, outputdir: str, config: dict) -> None:
+	"""
+    Process images from the specified input directory to generate Nintendo Switch themes. This
+	function handles the following tasks:
+    1. Walks through the input directory to collect images and associate them with themes.
+    2. Resolves and validates configuration paths for layout files.
+    3. Iterates over each theme and its components, and builds the theme files using the `nxtheme`
+	executable.
+
+    :param str nxthemebin: The path to the `nxtheme` executable used for building themes.
+    :param str inputdir: The directory containing the input images for the themes.
+    :param str outputdir: The directory where the generated theme files will be saved.
+    :param dict config: A dictionary containing configuration options such as the author name,
+    and paths to layout files.
+
+    :return: None
+	"""
 	themeimgmap = walkfiletree(inputdir=inputdir)
 	config = resolveConf(nxthemebin, conf=config)