Merge pull request #13 from kaitj/maint/boutiques-guide

Fix boutiques guide

Author: kaitj

src/boutiques_guide/advanced_features.md

@@ -59,6 +59,7 @@ NiWrap uses separate package configuration files to organize tools by suite:
 ### Endpoint Status Values
 
 The `status` field in each endpoint tracks implementation:
+
 - `"done"`: Descriptor is complete and ready to use
 - `"missing"`: Tool is identified but descriptor not yet created
 - `"ignore"`: Tool should be deliberately excluded from the API
@@ -83,6 +84,7 @@ For tools that output important data to stdout or stderr, the Styx ecosystem ext
 ```
 
 These fields make the command output available as strings in the generated bindings, useful for tools that:
+
 - Output data tables to the terminal
 - Provide processing statistics on stderr
 - Generate simple text outputs without writing files
@@ -219,13 +221,15 @@ Several fields help constrain parameter values:
 When creating or modifying descriptors, use these validation methods:
 
 1. JSON Schema validation:
+
    ```bash
    # In NiWrap repository
    python -m pytest tests/test_descriptors.py::test_descriptor_validity
    ```
 
 2. Visual Studio Code validation:
    Add this to `.vscode/settings.json`:
+
    ```json
    {
      "json.schemas": [
@@ -238,6 +242,7 @@ When creating or modifying descriptors, use these validation methods:
    ```
 
 3. Build testing:
+
    ```bash
    # Test if Styx can process your descriptor
    python build.py
@@ -260,4 +265,4 @@ Now that you've explored advanced features, you might find these pages helpful:
 
 - [Examples](./examples.md) - Complete descriptors demonstrating these concepts in action
 - [Troubleshooting](./troubleshooting.md) - Solutions to common problems with descriptors
-- [Subcommands](./subcommands.md) - More on hierarchical command structures
+- [Subcommands](./subcommands.md) - More on hierarchical command structures

src/boutiques_guide/basic_structure.md

@@ -88,6 +88,7 @@ Optional list-related fields:
 - `list-separator`: Character(s) used to join list values (default is space)
 
 Example with a custom separator:
+
 ```json
 {
   "id": "tags",
@@ -112,6 +113,7 @@ Value keys connect parameters to positions in the command line. In the Styx ecos
 - Match exactly in the `command-line` template
 
 Example:
+
 ```json
 "command-line": "bet [INFILE] [OUTFILE] [OPTIONS]",
 "inputs": [
@@ -191,7 +193,8 @@ Container configurations help ensure reproducibility:
 }
 ```
 
-In the Styx ecosystem, primarily the `type` and `image` fields are used, with Docker as the main container type.
+In the Styx ecosystem, primarily the `type` and `image` fields are used, with Docker as
+the only container type.
 
 ## Cross-References
 
@@ -201,4 +204,4 @@ Now that you understand the basic structure, learn more about:
 - [File Handling](./file_handling.md) - For detailed file input/output, path templates, and extension handling
 - [Advanced Features](./advanced_features.md) - For command output capture, package configuration, and more
 - [Troubleshooting](./troubleshooting.md) - For common issues and their solutions
-- [Examples](./examples.md) - For complete descriptor examples showing these concepts in action
+- [Examples](./examples.md) - For complete descriptor examples showing these concepts in action

src/boutiques_guide/file_handling.md

@@ -111,7 +111,7 @@ If the input is `subject1.nii.gz`, this would produce `subject1_mask.nii.gz` (no
 | `id` | Unique identifier | Yes | `"brain_mask"` |
 | `name` | Human-readable name | Yes | `"Brain Mask Image"` |
 | `description` | Detailed description | No | `"Binary mask of the brain"` |
-| `path-template` | Template for output file path | Yes | `"[OUTPUT_DIR]/[PREFIX]_mask.nii.gz"` |
+| `path-template` | Template for output file path | Yes | `"[PREFIX]_mask.nii.gz"` |
 | `optional` | Whether file might not be produced | No | `true` |
 | `path-template-stripped-extensions` | Extensions to remove from input paths | No | `[".nii.gz", ".nii"]` |
 
@@ -246,4 +246,4 @@ The Styx execution environment handles these mappings transparently, but it's im
     "name": "Processing Log",
     "description": "Detailed log of the processing steps"
   }
-}
+}

src/boutiques_guide/subcommands.md

@@ -111,6 +111,7 @@ The most common use of subcommands is to represent different "modes" or "algorit
 ```
 
 In this example:
+
 - The user must choose either the "fast" or "accurate" algorithm
 - Each algorithm has its own specific parameters
 - The "accurate" algorithm produces an additional output file
@@ -392,10 +393,11 @@ This ensures users can only provide valid parameter combinations.
 4. **Consider output files carefully** - each subcommand can have different outputs
 5. **Nest subcommands when it makes logical sense** for the tool's structure
 6. **Use value-choices for fixed option sets** within subcommands
-7. **Add list: true for repeatable elements** when the same subcommand can appear multiple times
+7. **Add `list: true` for repeatable elements** when the same subcommand can appear multiple times
 
 ## Next Steps
 
 Now that you understand subcommands, learn about:
+
 - [File Handling](./file_handling.md) - For detailed input/output file handling
-- [Advanced Features](./advanced_features.md) - For additional capabilities
+- [Advanced Features](./advanced_features.md) - For additional capabilities

src/boutiques_guide/troubleshooting.md

@@ -13,6 +13,7 @@ This guide covers common issues when creating or modifying Boutiques descriptors
 **Problem**: `ERROR: 'name' is a required property`
 
 **Solution**: Ensure all required top-level fields are present:
+
 ```json
 {
   "name": "tool_name",
@@ -29,6 +30,7 @@ This guide covers common issues when creating or modifying Boutiques descriptors
 **Problem**: `ERROR: 'string' is not of type 'number'`
 
 **Solution**: Check that values match their declared types. For numeric parameters:
+
 ```json
 {
   "id": "threshold",
@@ -42,6 +44,7 @@ This guide covers common issues when creating or modifying Boutiques descriptors
 **Problem**: `ERROR: 'input-file' does not match pattern '^[0-9,_,a-z,A-Z]*$'`
 
 **Solution**: IDs must contain only alphanumeric characters and underscores:
+
 ```json
 {
   "id": "input_file",  // Not "input-file"
@@ -55,8 +58,10 @@ This guide covers common issues when creating or modifying Boutiques descriptors
 
 **Problem**: Value-key placeholders aren't replaced in the command line.
 
-**Solution**: 
+**Solution**:
+
 1. Ensure the value-key in the parameter matches exactly what's in the command-line:
+
    ```json
    "command-line": "tool [INPUT_FILE]",
    "inputs": [
@@ -74,6 +79,7 @@ This guide covers common issues when creating or modifying Boutiques descriptors
 **Problem**: Command-line flags aren't included in the generated command.
 
 **Solution**: Make sure you're using the correct fields:
+
 ```json
 {
   "id": "verbose",
@@ -87,6 +93,7 @@ This guide covers common issues when creating or modifying Boutiques descriptors
 **Problem**: List values aren't formatted as expected in the command.
 
 **Solution**: Use the `list-separator` field to control how values are joined:
+
 ```json
 {
   "id": "coordinates",
@@ -104,6 +111,7 @@ This guide covers common issues when creating or modifying Boutiques descriptors
 **Problem**: Parameters inside subcommands aren't accessible in the generated bindings.
 
 **Solution**: Check your subcommand structure:
+
 ```json
 {
   "id": "algorithm",
@@ -126,6 +134,7 @@ This guide covers common issues when creating or modifying Boutiques descriptors
 **Problem**: The descriptor doesn't enforce mutually exclusive options.
 
 **Solution**: Instead of using `groups` with `mutually-exclusive`, use subcommands:
+
 ```json
 {
   "id": "mode",
@@ -144,7 +153,8 @@ This creates a proper union type in the generated bindings.
 
 **Problem**: Input files are reported as not found even though they exist.
 
-**Solution**: 
+**Solution**:
+
 1. Make sure you're using `"type": "File"` for input files
 2. Check if paths are relative to the current working directory
 3. For containerized runs, verify file paths are accessible in the container
@@ -154,6 +164,7 @@ This creates a proper union type in the generated bindings.
 **Problem**: Output files appear in unexpected locations.
 
 **Solution**: Check your `path-template` in output-files:
+
 ```json
 "output-files": [
   {
@@ -170,6 +181,7 @@ Ensure all value-keys (`[OUTPUT_DIR]`, `[PREFIX]`) are defined in your inputs.
 **Problem**: Output files have double extensions like `file.nii.gz.nii.gz`.
 
 **Solution**: Use `path-template-stripped-extensions`:
+
 ```json
 "output-files": [
   {
@@ -186,9 +198,11 @@ Ensure all value-keys (`[OUTPUT_DIR]`, `[PREFIX]`) are defined in your inputs.
 
 **Problem**: The container image cannot be pulled or found.
 
-**Solution**: 
+**Solution**:
+
 1. Verify the container exists in the specified registry
 2. Ensure the image name and tag are correct:
+
    ```json
    "container-image": {
      "type": "docker",
@@ -201,6 +215,7 @@ Ensure all value-keys (`[OUTPUT_DIR]`, `[PREFIX]`) are defined in your inputs.
 **Problem**: The tool reports missing dependencies inside the container.
 
 **Solution**: Use a container that includes all required dependencies. You may need to build a custom container with a Dockerfile:
+
 ```dockerfile
 FROM base/image:tag
 RUN apt-get update && apt-get install -y additional-dependency
@@ -212,10 +227,12 @@ RUN apt-get update && apt-get install -y additional-dependency
 
 **Problem**: Confusion between value-keys and command-line-flags.
 
-**Solution**: 
+**Solution**:
+
 - `value-key` is a placeholder in the command-line template
 - `command-line-flag` is the actual flag used in the command (e.g., `-v`, `--verbose`)
 - Both are often needed:
+
   ```json
   {
     "id": "threshold",
@@ -229,15 +246,17 @@ RUN apt-get update && apt-get install -y additional-dependency
 **Problem**: Confusion about how to define input and output files.
 
 **Solution**:
+
 - Input files use `"type": "File"` in the inputs section
 - Output files are defined in the `output-files` section with a `path-template`
-- For parameters that specify output paths, use `"type": "String"` (not "File")
+- For parameters that specify output paths, use `"type": "String"` (not `"File"`)
 
 ### Inconsistent Naming
 
 **Problem**: Similar parameters have inconsistent naming across descriptors.
 
 **Solution**: Follow consistent naming conventions:
+
 ```json
 // Good:
 "id": "input_file"
@@ -255,6 +274,7 @@ RUN apt-get update && apt-get install -y additional-dependency
 ### Validating Descriptors
 
 Always validate your descriptors before using them:
+
 ```bash
 # Using NiWrap validation
 python -m pytest tests/test_descriptors.py::test_descriptor_validity
@@ -266,6 +286,7 @@ python -m pytest tests/test_descriptors.py::test_descriptor_validity
 ### Printing Command Line
 
 When testing, print the full command line to see if it's formed correctly:
+
 ```python
 # Python
 from niwrap.tool import function
@@ -276,6 +297,7 @@ print(cmd)
 ### Using Verbose Mode
 
 Many tools have verbose or debug modes that can help identify issues:
+
 ```json
 {
   "id": "verbose",
@@ -292,4 +314,4 @@ If you're still having issues:
 
 1. Check existing descriptors in the NiWrap repository for examples
 2. Examine the [Boutiques documentation](https://boutiques.github.io/doc/)
-3. Open an issue in the [NiWrap issue tracker](https://github.com/styx-api/niwrap/issues)
+3. Open an issue in the [NiWrap issue tracker](https://github.com/styx-api/niwrap/issues)