Improve documentation layout

docs/articles.md

@@ -0,0 +1,6 @@
+# Articles
+
+- [Defining User Prompts on STRUCT: Harnessing GPT-4.1 for Scalable Project Scaffolding](https://medium.com/@httpdss/defining-user-prompts-on-struct-harnessing-gpt-4-1-for-scalable-project-scaffolding-e6d3b4ec4701)
+- [Unlocking Developer Productivity with STRUCT: The Ultimate Open-Source Tool for Automated Project Structures](https://blog.devops.dev/unlocking-developer-productivity-with-struct-the-ultimate-open-source-tool-for-automated-project-8bca9b5f40f9)
+- [Automating Project Structures with STRUCT and GitHub Actions](https://medium.com/@httpdss/automating-project-structures-with-struct-and-github-actions-64e09c40c11e)
+- [Advanced STRUCT Tips: Working with Template Variables and Jinja2 Filters](https://medium.com/@httpdss/advanced-struct-tips-working-with-template-variables-and-jinja2-filters-b239bf3145e4)

docs/completion.md

@@ -0,0 +1,27 @@
+# Command-Line Auto-Completion
+
+STRUCT uses [argcomplete](https://kislyuk.github.io/argcomplete/) to provide auto-completion.
+
+1. Install `argcomplete`:
+
+```sh
+pip install argcomplete
+```
+
+2. Enable global completion (usually done once):
+
+```sh
+activate-global-python-argcomplete
+```
+
+3. Register the script in your shell configuration (e.g. `.bashrc` or `.zshrc`):
+
+```sh
+eval "$(register-python-argcomplete struct)"
+```
+
+4. Reload your shell configuration:
+
+```sh
+source ~/.bashrc  # or ~/.zshrc for Zsh
+```

docs/configuration.md

@@ -0,0 +1,103 @@
+# YAML Configuration
+
+STRUCT reads a YAML file that describes the files and directories to create. Below are the available keys and options.
+
+## Configuration properties
+
+- **skip** – skip creation of a file or folder.
+- **skip_if_exists** – only create if the path does not already exist.
+- **permissions** – set custom file permissions (e.g. `'0777'`).
+- **content** – inline file content.
+- **file** – path or URL of a file to include. Supported protocols include `file://`, `http://`, `https://`, `github://`, `githubhttps://`, `githubssh://`, `s3://` and `gs://`.
+
+Example configuration:
+
+```yaml
+files:
+  - README.md:
+      skip: true
+      content: |
+        # {{@ project_name @}}
+        This is a template repository.
+  - script.sh:
+      skip_if_exists: true
+      permissions: '0777'
+      content: |
+        #!/bin/bash
+        echo "Hello, {{@ author_name @}}!"
+  - LICENSE:
+      file: https://raw.githubusercontent.com/nishanths/license/master/LICENSE
+  - remote_file.txt:
+      file: file:///path/to/local/file.txt
+  - github_file.py:
+      file: github://owner/repo/branch/path/to/file.py
+  - github_https_file.py:
+      file: githubhttps://owner/repo/branch/path/to/file.py
+  - github_ssh_file.py:
+      file: githubssh://owner/repo/branch/path/to/file.py
+  - s3_file.txt:
+      file: s3://bucket_name/key
+  - gcs_file.txt:
+      file: gs://bucket_name/key
+  - src/main.py:
+      content: |
+        print("Hello, World!")
+folders:
+  - .devops/modules/mod1:
+      struct: terraform/module
+  - .devops/modules/mod2:
+      struct: terraform/module
+      with:
+        module_name: mymod2
+  - ./:
+      struct:
+        - docker-files
+        - project/go
+variables:
+  - project_name:
+      description: "The name of the project"
+      default: "MyProject"
+      type: string
+  - author_name:
+      description: "The name of the author"
+      type: string
+      default: "John Doe"
+```
+
+## Template variables
+
+Template variables are enclosed in `{{@` and `@}}` and are replaced at runtime. If a variable does not have a default value you will be prompted interactively.
+
+### Default variables
+
+- `file_name` – name of the file being processed.
+- `file_directory` – directory of the file being processed.
+
+### Custom Jinja2 filters
+
+`struct` ships a few helper filters.
+
+- **latest_release** – fetch the latest GitHub release.
+- **slugify** – convert a string into a slug.
+- **default_branch** – return the default branch of a GitHub repository.
+
+```yaml
+files:
+  - README.md:
+      content: |
+        Latest release: {{@ "httpdss/struct" | latest_release @}}
+```
+
+If a filter fails, a placeholder value is inserted.
+
+### `with` clause
+
+Nested structures can receive extra variables using the `with` clause. These values are merged with the global variables.
+
+```yaml
+folders:
+  - .devops/modules/mod2:
+      struct: terraform/module
+      with:
+        module_name: mymod2
+```

docs/development.md

@@ -0,0 +1,16 @@
+# Development
+
+1. Clone the repository.
+2. Create a virtual environment and activate it:
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+3. Install dependencies:
+
+```sh
+pip install -r requirements.txt
+pip install -r requirements.dev.txt
+```

docs/github_trigger_script.md

@@ -0,0 +1,30 @@
+# GitHub Trigger Script
+
+The `github-trigger.py` utility triggers the `run-struct` workflow for every private repository in a GitHub organisation that matches certain criteria.
+
+## Features
+
+- Filter repositories by topic (for example `struct-enabled`).
+- Check for the presence of a `.struct.yaml` file in the default branch.
+- Ensure the `run-struct` workflow file exists.
+- Dispatch the workflow for eligible repositories.
+
+## Usage
+
+Set a personal access token as `GITHUB_TOKEN` and run:
+
+```sh
+python3 scripts/github-trigger.py <organization> <topic>
+```
+
+### Arguments
+
+- `<organization>` – GitHub organization name.
+- `<topic>` – repository topic to search for.
+
+### Example
+
+```sh
+export GITHUB_TOKEN=your_personal_access_token
+python3 scripts/github-trigger.py my-org struct-enabled
+```

docs/hooks.md

@@ -0,0 +1,24 @@
+# Pre-Generation and Post-Generation Hooks
+
+You can run shell commands before and after structure generation using `pre_hooks` and `post_hooks` in your configuration.
+
+- **pre_hooks** – commands executed before generation. If any command returns a non-zero exit code the process stops.
+- **post_hooks** – commands executed after generation completes. If any command fails an error is shown.
+
+Example:
+
+```yaml
+pre_hooks:
+  - echo "Preparing environment..."
+  - ./scripts/prep.sh
+
+post_hooks:
+  - echo "Generation complete!"
+  - ./scripts/cleanup.sh
+files:
+  - README.md:
+      content: |
+        # My Project
+```
+
+Output from hooks is shown in the terminal.

docs/installation.md

@@ -0,0 +1,55 @@
+# Installation
+
+## Using pip
+
+You can install STRUCT using pip:
+
+```sh
+pip install git+https://github.com/httpdss/struct.git
+```
+
+## From Source
+
+Alternatively, clone the repository and install it locally:
+
+```sh
+git clone https://github.com/httpdss/struct.git
+cd struct
+pip install -r requirements.txt
+```
+
+## Using Docker
+
+The Docker image lets you run the script without installing anything locally. See the [Quick Start](#quick-start) below for an example.
+
+## Quick Start
+
+### Generate a project from a local YAML file
+
+```sh
+docker run \
+  -v $(pwd):/workdir \
+  -u $(id -u):$(id -g) \
+  ghcr.io/httpdss/struct:main generate \
+  /workdir/example/structure.yaml \
+  /workdir/example_output
+```
+
+### Quick Start Using Docker Alpine
+
+For testing you can start a minimal Alpine container and install STRUCT inside it:
+
+```sh
+docker run -it --entrypoint="" python:3.10-alpine sh -l
+```
+
+Inside the container install the tool and run it:
+
+```sh
+apk add python-pip git vim
+pip install git+https://github.com/httpdss/struct.git
+mkdir example
+cd example
+cp /workdir/example/structure.yaml .
+struct generate structure.yaml .
+```

docs/usage.md

@@ -0,0 +1,35 @@
+# Usage
+
+STRUCT exposes a command called `struct` with a set of subcommands:
+
+- `generate` – generate a project structure from a YAML file.
+- `validate` – validate a configuration file.
+- `info` – display information about the tool and its dependencies.
+- `list` – list available structures shipped with the project.
+
+For help on any command run:
+
+```sh
+struct -h
+```
+
+## Simple example
+
+```sh
+struct generate terraform-module ./my-terraform-module
+```
+
+## More complete example
+
+```sh
+struct generate \
+  --log=DEBUG \
+  --dry-run \
+  --backup=/path/to/backup \
+  --file-strategy=rename \
+  --log-file=/path/to/logfile.log \
+  terraform-module \
+  ./my-terraform-module
+```
+
+The [configuration](configuration.md) file controls what files and folders are created.

docs/yaml_schema.md

@@ -0,0 +1,18 @@
+# YAML Schema
+
+A JSON schema is provided to help validate your configuration and provide autocompletion in supported editors.
+
+## Configuring VSCode
+
+1. Install the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml).
+2. Add the following to your `.vscode/settings.json`:
+
+```json
+{
+  "yaml.schemas": {
+    "https://raw.githubusercontent.com/httpdss/struct/main/extras/schema.json": ".struct.yaml"
+  }
+}
+```
+
+This associates the schema with all `.struct.yaml` files in the workspace.