diff --git a/docs/cli-reference.md b/docs/cli-reference.md new file mode 100644 index 0000000..ff9cbff --- /dev/null +++ b/docs/cli-reference.md @@ -0,0 +1,205 @@ +# CLI Reference + +This document provides a reference for the `struct` command-line interface (CLI). + +## Overview + +The `struct` CLI allows you to generate project structures from YAML configuration files. It supports both built-in structure definitions and custom structures. + +**Basic Usage:** + +```sh +struct {info,validate,generate,list,generate-schema} ... +``` + +## Global Options + +These options are available for all commands: + +- `-h, --help`: Show the help message and exit. +- `-l LOG, --log LOG`: Set the logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). +- `-c CONFIG_FILE, --config-file CONFIG_FILE`: Path to a configuration file. +- `-i LOG_FILE, --log-file LOG_FILE`: Path to a log file. + +## Commands + +### `info` + +Show information about a structure definition. + +**Usage:** + +```sh +struct info [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH] structure_definition +``` + +**Arguments:** + +- `structure_definition`: Name of the structure definition. +- `-s STRUCTURES_PATH, --structures-path STRUCTURES_PATH`: Path to structure definitions. + +### `validate` + +Validate the YAML configuration file. + +**Usage:** + +```sh +struct validate [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] yaml_file +``` + +**Arguments:** + +- `yaml_file`: Path to the YAML configuration file. + +### `generate` + +Generate the project structure. + +**Usage:** + +```sh +struct generate [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH] [-n INPUT_STORE] [-d] [-v VARS] [-b BACKUP] [-f {overwrite,skip,append,rename,backup}] [-p GLOBAL_SYSTEM_PROMPT] [--non-interactive] [--mappings-file MAPPINGS_FILE] [-o {console,file}] structure_definition base_path +``` + +**Arguments:** + +- `structure_definition`: Path to the YAML configuration file. +- `base_path`: Base path where the structure will be created. +- `-s STRUCTURES_PATH, --structures-path STRUCTURES_PATH`: Path to structure definitions. +- `-n INPUT_STORE, --input-store INPUT_STORE`: Path to the input store. +- `-d, --dry-run`: Perform a dry run without creating any files or directories. +- `-v VARS, --vars VARS`: Template variables in the format KEY1=value1,KEY2=value2. +- `-b BACKUP, --backup BACKUP`: Path to the backup folder. +- `-f {overwrite,skip,append,rename,backup}, --file-strategy {overwrite,skip,append,rename,backup}`: Strategy for handling existing files. +- `-p GLOBAL_SYSTEM_PROMPT, --global-system-prompt GLOBAL_SYSTEM_PROMPT`: Global system prompt for OpenAI. +- `--non-interactive`: Run the command in non-interactive mode. +- `--mappings-file MAPPINGS_FILE`: Path to a YAML file containing mappings to be used in templates (can be specified multiple times). +- `-o {console,file}, --output {console,file}`: Output mode. + +### `list` + +List available structures. + +**Usage:** + +```sh +struct list [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH] +``` + +**Arguments:** + +- `-s STRUCTURES_PATH, --structures-path STRUCTURES_PATH`: Path to structure definitions. + +### `generate-schema` + +Generate JSON schema for available structures. + +**Usage:** + +```sh +struct generate-schema [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH] [-o OUTPUT] +``` + +**Arguments:** + +- `-s STRUCTURES_PATH, --structures-path STRUCTURES_PATH`: Path to structure definitions. +- `-o OUTPUT, --output OUTPUT`: Output file path for the schema (default: stdout). + +## Examples + +### Basic Structure Generation + +Generate a structure using a built-in definition: + +```sh +struct generate python-basic ./my-project +``` + +Generate from a custom YAML file: + +```sh +struct generate file://my-structure.yaml ./output-dir +``` + +### Using Custom Structures + +Generate with custom structure path: + +```sh +struct generate -s ~/custom-structures python-api ./my-api +``` + +### Template Variables + +Pass template variables to the structure: + +```sh +struct generate -v "project_name=MyApp,author=John Doe" file://structure.yaml ./output +``` + +### Dry Run + +Test structure generation without creating files: + +```sh +struct generate -d file://structure.yaml ./output +``` + +### File Strategies + +Handle existing files with different strategies: + +```sh +# Skip existing files +struct generate -f skip file://structure.yaml ./output + +# Backup existing files +struct generate -f backup -b ./backup file://structure.yaml ./output +``` + +### Console Output + +Output to console instead of creating files: + +```sh +struct generate -o console file://structure.yaml ./output +``` + +### Validation + +Validate a YAML configuration before generation: + +```sh +struct validate my-structure.yaml +``` + +### List Available Structures + +List all built-in structures: + +```sh +struct list +``` + +List structures from custom path: + +```sh +struct list -s ~/custom-structures +``` + +### Get Structure Information + +Get detailed information about a structure: + +```sh +struct info python-basic +``` + +### Generate Schema + +Generate JSON schema and save to file: + +```sh +struct generate-schema -o schema.json +``` diff --git a/docs/custom-structures.md b/docs/custom-structures.md new file mode 100644 index 0000000..2d3422b --- /dev/null +++ b/docs/custom-structures.md @@ -0,0 +1,37 @@ +# Creating Custom Structures + +Let's say you are happy with the default structures that STRUCT provides, but you want to customize them for your specific needs. This is totally possible! + +The best way to approach this is to have a repository where you can store your custom structures. You can then reference these structures in your `.struct.yaml` files. + +## Suggested Repository Structure + +Here is a suggested structure for your custom structures repository: + +```sh +structures/ +├── category1/ +│ ├── structure1.yaml +│ └── structure2.yaml +├── category2/ +│ ├── structure1.yaml +│ └── structure2.yaml +``` + +This way you could reference your custom structures in your `.struct.yaml` files like this: + +```yaml +folders: + - ./: + struct: + - category1/structure1 + - category2/structure2 + with: + var_in_structure1: 'value' +``` + +For this to work, you will need to set the path to the custom structures repository using the `-s` option when running STRUCT: + +```sh +struct generate -s ~/path/to/custom-structures/structures file://.struct.yaml ./output +``` diff --git a/docs/examples/index.md b/docs/examples/index.md index d85a266..0825d64 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -1,49 +1,377 @@ # Examples -This directory contains practical examples of STRUCT configurations for various use cases. +This page contains practical examples of STRUCT configurations for various use cases. ## Basic Examples -- [Simple Project](simple-project.yaml) - Basic project structure with files and folders -- [Template Variables](template-variables.yaml) - Using dynamic content with variables -- [Remote Files](remote-files.yaml) - Fetching content from external sources +### Simple Project + +Basic project structure with files and folders: + +```yaml +# Example: Simple Project Structure +# Use case: Basic project setup with common files + +files: + - README.md: + content: | + # {{@ project_name | default('My Project') @}} + + Welcome to the project! + + ## Getting Started + + 1. Install dependencies + 2. Run the application + 3. Enjoy! + + - .gitignore: + content: | + node_modules/ + *.log + .env + dist/ + + - LICENSE: + content: | + MIT License + + Copyright (c) {{@ year | default('2024') @}} {{@ author | default('Project Author') @}} + +folders: + - src/: + struct: + - basic/folder + - docs/: + struct: + - basic/folder + +variables: + - project_name: + description: 'Name of the project' + type: string + default: 'My Project' + - author: + description: 'Project author' + type: string + default: 'Project Author' + - year: + description: 'Copyright year' + type: string + default: '2024' +``` + +### Template Variables + +Using dynamic content with variables: + +```yaml +# Example: Template Variables +# Use case: Dynamic content generation with user input + +files: + - package.json: + content: | + { + "name": "{{@ package_name @}}", + "version": "{{@ version | default('1.0.0') @}}", + "description": "{{@ description @}}", + "author": "{{@ author @}}", + "license": "{{@ license | default('MIT') @}}" + } + + - src/config.js: + content: | + module.exports = { + appName: '{{@ app_name @}}', + version: '{{@ version | default('1.0.0') @}}', + environment: '{{@ environment | default('development') @}}' + }; + +variables: + - package_name: + description: 'NPM package name' + type: string + required: true + - app_name: + description: 'Application display name' + type: string + required: true + - description: + description: 'Project description' + type: string + required: true + - author: + description: 'Package author' + type: string + required: true + - version: + description: 'Initial version' + type: string + default: '1.0.0' + - license: + description: 'License type' + type: string + default: 'MIT' + - environment: + description: 'Target environment' + type: string + default: 'development' +``` + +### Remote Files + +Fetching content from external sources: + +```yaml +# Example: Remote Files +# Use case: Including content from external URLs or repositories + +files: + - .gitignore: + remote: 'https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore' + + - CODE_OF_CONDUCT.md: + remote: 'https://raw.githubusercontent.com/contributor-covenant/contributor-covenant/main/CODE_OF_CONDUCT.md' + + - CONTRIBUTING.md: + content: | + # Contributing to {{@ project_name @}} + + Thank you for your interest in contributing! + + ## Development Setup + + 1. Fork the repository + 2. Clone your fork + 3. Install dependencies + 4. Make your changes + 5. Submit a pull request + +variables: + - project_name: + description: 'Project name' + type: string + required: true +``` ## Application Development -- [Python Project](python-project.yaml) - Complete Python application structure -- [Node.js API](nodejs-api.yaml) - REST API with Express.js -- [React Frontend](react-frontend.yaml) - Modern React application setup -- [Microservice](microservice.yaml) - Containerized microservice template +### Python Project + +Complete Python application structure: + +````yaml +# Example: Python Project +# Use case: Full Python application with proper structure + +files: + - README.md: + content: | + # {{@ project_name @}} + + {{@ description @}} + + ## Installation + + ```bash + pip install -r requirements.txt + ``` + + ## Usage + + ```bash + python -m {{@ package_name @}} + ``` + + - requirements.txt: + content: | + click>=8.0.0 + requests>=2.25.0 + pytest>=6.0.0 + + - setup.py: + content: | + from setuptools import setup, find_packages + + setup( + name="{{@ package_name @}}", + version="{{@ version | default('0.1.0') @}}", + description="{{@ description @}}", + author="{{@ author @}}", + packages=find_packages(), + install_requires=[ + "click>=8.0.0", + "requests>=2.25.0", + ], + entry_points={ + "console_scripts": [ + "{{@ package_name @}}={{@ package_name @}}.cli:main", + ], + }, + ) + + - '{{@ package_name @}}/__init__.py': + content: | + """{{@ description @}}""" + __version__ = "{{@ version | default('0.1.0') @}}" + + - '{{@ package_name @}}/main.py': + content: | + """Main application module.""" + + def main(): + """Main entry point.""" + print("Hello from {{@ project_name @}}!") + + if __name__ == "__main__": + main() + + - tests/test_main.py: + content: | + """Tests for main module.""" + import pytest + from {{@ package_name @}} import main + + def test_main(): + """Test main function.""" + # Add your tests here + assert True + +variables: + - project_name: + description: 'Project name' + type: string + required: true + - package_name: + description: 'Python package name' + type: string + required: true + - description: + description: 'Project description' + type: string + required: true + - author: + description: 'Project author' + type: string + required: true + - version: + description: 'Initial version' + type: string + default: '0.1.0' +```` + +### Node.js API + +REST API with Express.js: + +```yaml +# Example: Node.js API +# Use case: Express.js REST API with proper structure + +files: + - package.json: + content: | + { + "name": "{{@ package_name @}}", + "version": "{{@ version | default('1.0.0') @}}", + "description": "{{@ description @}}", + "main": "src/app.js", + "scripts": { + "start": "node src/app.js", + "dev": "nodemon src/app.js", + "test": "jest" + }, + "dependencies": { + "express": "^4.18.0", + "cors": "^2.8.5", + "helmet": "^6.0.0", + "dotenv": "^16.0.0" + }, + "devDependencies": { + "nodemon": "^2.0.20", + "jest": "^29.0.0", + "supertest": "^6.3.0" + } + } + + - src/app.js: + content: | + const express = require('express'); + const cors = require('cors'); + const helmet = require('helmet'); + require('dotenv').config(); + + const app = express(); + const PORT = process.env.PORT || 3000; + + // Middleware + app.use(helmet()); + app.use(cors()); + app.use(express.json()); -## Infrastructure + // Routes + app.get('/', (req, res) => { + res.json({ message: 'Welcome to {{@ project_name @}} API' }); + }); -- [Terraform Module](terraform-module.yaml) - AWS infrastructure module -- [Kubernetes Application](k8s-application.yaml) - Complete K8s deployment -- [Docker Multi-Stage](docker-multistage.yaml) - Multi-stage Docker setup -- [CI/CD Pipeline](cicd-pipeline.yaml) - GitHub Actions workflow + app.get('/api/health', (req, res) => { + res.json({ status: 'OK', timestamp: new Date().toISOString() }); + }); -## DevOps + app.listen(PORT, () => { + console.log(`{{@ project_name @}} API running on port ${PORT}`); + }); -- [Monitoring Setup](monitoring.yaml) - Prometheus and Grafana configuration -- [GitOps Repository](gitops-repo.yaml) - ArgoCD application structure -- [Helm Chart](helm-chart.yaml) - Kubernetes Helm chart template + module.exports = app; -## Advanced + - .env.example: + content: | + PORT=3000 + NODE_ENV=development -- [Multi-Environment](multi-environment.yaml) - Environment-specific configurations with mappings -- [Custom Hooks](custom-hooks.yaml) - Complex automation with pre/post hooks -- [Modular Structure](modular-structure.yaml) - Composable, reusable components +variables: + - project_name: + description: 'Project name' + type: string + required: true + - package_name: + description: 'NPM package name' + type: string + required: true + - description: + description: 'API description' + type: string + required: true + - version: + description: 'Initial version' + type: string + default: '1.0.0' +``` ## Usage -Each example can be used directly: +To use these examples: + +1. **Copy the YAML content** from any example above +2. **Save it to a file** (e.g., `my-structure.yaml`) +3. **Run struct generate** with your file: ```bash -# Use an example from this directory -struct generate ./docs/examples/python-project.yaml ./my-project +# Create your structure file +cat > my-structure.yaml << 'EOF' +# Paste the YAML content here +EOF -# Or reference the raw URL -struct generate https://raw.githubusercontent.com/httpdss/struct/main/docs/examples/python-project.yaml ./my-project +# Generate your project +struct generate file://my-structure.yaml ./my-project +``` + +### Quick Start with Template Variables + +```bash +# Generate with custom variables +struct generate -v "project_name=MyApp,author=John Doe" file://my-structure.yaml ./my-project ``` ## Contributing Examples @@ -71,7 +399,7 @@ files: variables: - example_var: - description: "Example variable" + description: 'Example variable' type: string - default: "example_value" + default: 'example_value' ``` diff --git a/docs/quickstart.md b/docs/quickstart.md index da45f58..5577fce 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -2,7 +2,7 @@ ## Quick Start Using Docker -1. Create a YAML configuration file for your project structure. [See sample configuration here](../example/structure.yaml). +1. Create a YAML configuration file for your project structure. [See sample configuration here](https://github.com/httpdss/struct/blob/main/example/structure.yaml). 2. Run the following command to generate the project structure: ```sh diff --git a/site/index.html b/site/index.html index 5d9aeef..54dc84e 100644 --- a/site/index.html +++ b/site/index.html @@ -419,7 +419,7 @@

- + Read Guide →
@@ -437,7 +437,7 @@

- + View Reference →
@@ -556,9 +556,9 @@

Built with STRUCT

Resources

@@ -568,7 +568,7 @@

Community

  • GitHub Repository
  • Discussions
  • Issues
    • -
  • Contributing
    • +
  • Contributing
    • @@ -576,7 +576,7 @@

    Support

    diff --git a/site/js/phase3.js b/site/js/phase3.js index 60e41d5..b7f8c1e 100644 --- a/site/js/phase3.js +++ b/site/js/phase3.js @@ -676,7 +676,7 @@ variables: title: 'Documentation', description: 'Comprehensive guides, tutorials, and API documentation', action: 'Read Docs', - link: 'https://github.com/httpdss/struct/blob/main/docs/index.md', + link: 'https://httpdss.github.io/struct/docs/', }, { icon: 'fas fa-heart', diff --git a/site/manifest.json b/site/manifest.json index ae78459..ff39b5a 100644 --- a/site/manifest.json +++ b/site/manifest.json @@ -59,7 +59,7 @@ "name": "Documentation", "short_name": "Docs", "description": "Read STRUCT documentation", - "url": "https://github.com/httpdss/struct/blob/main/docs/index.md", + "url": "https://httpdss.github.io/struct/docs/", "icons": [ { "src": "/images/docs-icon.png", @@ -71,7 +71,7 @@ "name": "Quick Start", "short_name": "Start", "description": "Quick start guide", - "url": "https://github.com/httpdss/struct/blob/main/docs/quickstart.md", + "url": "https://httpdss.github.io/struct/docs/quickstart/", "icons": [ { "src": "/images/quickstart-icon.png", diff --git a/site/sitemap.xml b/site/sitemap.xml index 627857a..8e9d03e 100644 --- a/site/sitemap.xml +++ b/site/sitemap.xml @@ -49,36 +49,168 @@ 0.9 - + + - https://github.com/httpdss/struct/blob/main/docs/index.md - 2025-07-28 + https://httpdss.github.io/struct/docs/configuration/ + 2025-08-02 weekly 0.8 - - https://github.com/httpdss/struct/blob/main/docs/installation.md - 2025-07-28 - monthly + https://httpdss.github.io/struct/docs/hooks/ + 2025-08-02 + weekly 0.8 - - https://github.com/httpdss/struct/blob/main/docs/quickstart.md - 2025-07-28 - monthly + https://httpdss.github.io/struct/docs/development/ + 2025-08-02 + weekly 0.8 - - https://github.com/httpdss/struct/tree/main/example - 2025-07-28 + https://httpdss.github.io/struct/docs/vhs/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/template-variables/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/known-issues/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/articles/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/404/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/installation/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/schema/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/usage/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/completion/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/structures/ + 2025-08-02 weekly - 0.7 + 0.8 + + + + https://httpdss.github.io/struct/docs/contributing/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/github-integration/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/examples/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/file-handling/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/index.html + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/mappings/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/quickstart/ + 2025-08-02 + weekly + 0.8 + + + + https://httpdss.github.io/struct/docs/funding/ + 2025-08-02 + weekly + 0.8 + + + + + https://httpdss.github.io/struct/docs/cli-reference/ + 2025-08-02 + weekly + 0.9 + + + + https://httpdss.github.io/struct/docs/custom-structures/ + 2025-08-02 + weekly + 0.9 diff --git a/site/structured-data.json b/site/structured-data.json index 285bd4e..f446be6 100644 --- a/site/structured-data.json +++ b/site/structured-data.json @@ -53,11 +53,11 @@ "Cross-platform Support" ], "requirements": "Python 3.8+", - "installUrl": "https://github.com/httpdss/struct#installation", + "installUrl": "https://httpdss.github.io/struct/docs/installation/", "supportingData": { "@type": "Dataset", "name": "STRUCT Documentation", "description": "Complete documentation and examples for STRUCT", - "url": "https://github.com/httpdss/struct/blob/main/docs/" + "url": "https://httpdss.github.io/struct/docs/" } } diff --git a/site/update-sitemap.sh b/site/update-sitemap.sh new file mode 100755 index 0000000..57ef12d --- /dev/null +++ b/site/update-sitemap.sh @@ -0,0 +1,65 @@ +#!/bin/bash + +# Script to automatically update sitemap.xml with all generated documentation pages +# Usage: ./update-sitemap.sh + +SITEMAP_FILE="sitemap.xml" +DOCS_DIR="docs" +BASE_URL="https://httpdss.github.io/struct" +TODAY=$(date +%Y-%m-%d) + +echo "📄 Updating sitemap.xml with generated documentation pages..." + +# Backup original sitemap +cp "$SITEMAP_FILE" "${SITEMAP_FILE}.backup" + +# Find all HTML files in docs directory +echo "🔍 Finding HTML files in $DOCS_DIR..." +html_files=$(find "$DOCS_DIR" -name "*.html" | sort) + +# Count files +file_count=$(echo "$html_files" | wc -l) +echo "📊 Found $file_count HTML files to add to sitemap" + +# Create temporary file with new entries +temp_file=$(mktemp) + +# Copy everything before +sed '/<\/urlset>/d' "$SITEMAP_FILE" > "$temp_file" + +# Add comment for generated docs +echo "" >> "$temp_file" +echo " " >> "$temp_file" +echo "" >> "$temp_file" + +# Add each HTML file as a URL entry +while IFS= read -r file; do + # Convert file path to URL path + url_path=${file#docs/} + + # Remove index.html from path for cleaner URLs + if [[ "$url_path" == */index.html ]]; then + url_path=${url_path%/index.html}/ + fi + + # Add URL entry + echo " " >> "$temp_file" + echo " $BASE_URL/$file" >> "$temp_file" + echo " $TODAY" >> "$temp_file" + echo " weekly" >> "$temp_file" + echo " 0.8" >> "$temp_file" + echo " " >> "$temp_file" + echo "" >> "$temp_file" +done <<< "$html_files" + +# Close urlset +echo "" >> "$temp_file" + +# Replace original sitemap +mv "$temp_file" "$SITEMAP_FILE" + +echo "✅ Sitemap updated successfully!" +echo "📈 Total URLs in sitemap: $(grep -c '' "$SITEMAP_FILE")" +echo "📂 Documentation pages: $(grep -c "docs/" "$SITEMAP_FILE")" +echo "" +echo "💡 Backup created: ${SITEMAP_FILE}.backup"