From 28f40f7edd1eb723adbb9bd94652a00f7211bb08 Mon Sep 17 00:00:00 2001 From: rob Date: Mon, 5 Jan 2026 18:25:36 -0400 Subject: [PATCH] Initial project setup Development Hub - Central project orchestration for the development ecosystem. Features: - new-project script for automated project scaffolding - Templates for Python projects - Integration with centralized documentation system - Gitea API integration for repo creation --- .gitignore | 21 + CLAUDE.md | 104 +++++ README.md | 76 ++++ bin/new-project | 455 +++++++++++++++++++ templates/CLAUDE.md.template | 49 ++ templates/README.md.template | 39 ++ templates/gitignore.template | 53 +++ templates/overview.md.template | 41 ++ templates/pyproject.toml.template | 23 + templates/updating-documentation.md.template | 134 ++++++ 10 files changed, 995 insertions(+) create mode 100644 .gitignore create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100755 bin/new-project create mode 100644 templates/CLAUDE.md.template create mode 100644 templates/README.md.template create mode 100644 templates/gitignore.template create mode 100644 templates/overview.md.template create mode 100644 templates/pyproject.toml.template create mode 100644 templates/updating-documentation.md.template diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8502a3b --- /dev/null +++ b/.gitignore @@ -0,0 +1,21 @@ +# Python +__pycache__/ +*.py[cod] +*.so + +# Virtual environments +.venv/ +venv/ + +# IDE +.idea/ +.vscode/ +*.swp +*.swo + +# OS +.DS_Store +Thumbs.db + +# Documentation symlink (points to project-docs) +docs diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..cc0f94f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,104 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +**Development Hub** is the central orchestration project for Rob's multi-project development ecosystem. It provides tooling to create and manage projects that follow consistent patterns for documentation, repository structure, and AI-assisted development. + +## Key Scripts + +### `bin/new-project` + +Creates a new project in the ecosystem with all the standard setup: + +```bash +# Full usage +new-project myproject --title "My Project" --tagline "Short description" + +# Interactive mode (prompts for title/tagline) +new-project myproject + +# Options +--title "..." Display title for the project +--tagline "..." Short description +--dry-run Show what would happen without making changes +--skip-gitea Skip Gitea repository creation (for offline use) +``` + +**What it does:** +1. Creates Gitea repository via API +2. Creates local project directory with git +3. Generates project files from templates (CLAUDE.md, README.md, .gitignore, pyproject.toml) +4. Sets up documentation symlink to project-docs +5. Updates build-public-docs.sh to include the new project +6. Creates initial commit and pushes + +## Project Structure + +``` +development-hub/ +├── bin/ +│ └── new-project # Main scaffolding script +├── templates/ +│ ├── gitignore.template # Python .gitignore with docs exclusion +│ ├── CLAUDE.md.template # AI context file +│ ├── README.md.template # Basic README +│ ├── pyproject.toml.template +│ ├── overview.md.template # Docs overview +│ └── updating-documentation.md.template +├── docs/ # Symlink to project-docs +├── CLAUDE.md # This file +├── README.md +└── .gitignore +``` + +## Template Placeholders + +Templates use these placeholders (replaced by sed): + +- `{{PROJECT_NAME}}` - lowercase project name (e.g., "my-tool") +- `{{PROJECT_TITLE}}` - display title (e.g., "My Tool") +- `{{PROJECT_TAGLINE}}` - short description +- `{{YEAR}}` - current year +- `{{DATE}}` - creation date +- `{{GITEA_URL}}` - https://gitea.brrd.tech +- `{{GITEA_OWNER}}` - rob + +## Configuration + +### Gitea API Token + +The script needs a Gitea API token to create repositories: + +1. **Environment variable**: `GITEA_TOKEN` +2. **Config file**: `~/.config/development-hub/gitea-token` + +To create a token: +1. Go to https://gitea.brrd.tech/user/settings/applications +2. Generate a new token with 'repo' scope +3. The script will prompt and save it automatically + +## Documentation + +Documentation lives in the centralized docs system: + +- **Source**: `~/PycharmProjects/project-docs/docs/projects/development-hub/` +- **Public URL**: `https://pages.brrd.tech/rob/development-hub/` + +When updating documentation: +1. Edit files in `docs/` (the symlink) +2. Use `public: true` frontmatter for public-facing docs +3. Run `~/PycharmProjects/project-docs/scripts/build-public-docs.sh development-hub --deploy` to publish + +## Related Projects + +This project manages and creates projects in the ecosystem: + +- **CmdForge** - AI-powered CLI tool builder +- **CascadingDev** - Cascading Development Framework +- **Orchestrated Discussions** - AI Discussion Framework +- **Artifact Editor** - Code Artifact Editor +- **Ramble** - Voice Note Transcription + +All projects follow the same documentation pattern and can be created using `new-project`. diff --git a/README.md b/README.md new file mode 100644 index 0000000..ff51415 --- /dev/null +++ b/README.md @@ -0,0 +1,76 @@ +# Development Hub + +Central orchestration project for managing Rob's multi-project development ecosystem. + +## Overview + +Development Hub provides tooling to create and manage projects that follow consistent patterns: + +- Centralized documentation via Docusaurus +- Gitea repository hosting with Pages support +- AI-assistant context files (CLAUDE.md) +- Python project structure + +## Quick Start + +### Create a New Project + +```bash +# Add to PATH (one-time) +export PATH="$PATH:$HOME/PycharmProjects/development-hub/bin" + +# Create a new project +new-project my-awesome-tool --title "My Awesome Tool" --tagline "Does awesome things" +``` + +This will: +1. Create a Gitea repository at `gitea.brrd.tech/rob/my-awesome-tool` +2. Set up local project at `~/PycharmProjects/my-awesome-tool/` +3. Generate starter files (CLAUDE.md, README.md, pyproject.toml, .gitignore) +4. Configure documentation symlink and build scripts +5. Create initial commit and push + +### View Full Options + +```bash +new-project --help +``` + +## What Gets Created + +For each new project: + +``` +~/PycharmProjects/my-project/ +├── src/my_project/ # (you create this) +├── tests/ # (you create this) +├── docs/ # Symlink to centralized docs +├── CLAUDE.md # AI assistant context +├── README.md # Project readme +├── pyproject.toml # Python packaging +└── .gitignore # Standard Python ignores +``` + +## Documentation System + +All projects use centralized documentation: + +- **Private hub**: `~/PycharmProjects/project-docs/` (view with `npm start`) +- **Public sites**: `https://pages.brrd.tech/rob/{project}/` + +The `docs/` symlink in each project points to its section in project-docs. + +## Configuration + +### Gitea Token + +The script needs a Gitea API token. It will prompt you the first time and save it to `~/.config/development-hub/gitea-token`. + +To create manually: +1. Go to https://gitea.brrd.tech/user/settings/applications +2. Generate token with 'repo' scope +3. Set `GITEA_TOKEN` env var or let the script save it + +## Full Documentation + +https://pages.brrd.tech/rob/development-hub/ diff --git a/bin/new-project b/bin/new-project new file mode 100755 index 0000000..03bfd03 --- /dev/null +++ b/bin/new-project @@ -0,0 +1,455 @@ +#!/bin/bash +# +# new-project - Create a new project in Rob's development ecosystem +# +# This script automates: +# - Creating local project directory +# - Creating Gitea repository via API +# - Setting up documentation symlinks +# - Generating project files from templates +# - Updating build-public-docs.sh +# +# Usage: +# new-project myproject --title "My Project" --tagline "Short description" +# new-project myproject # Interactive mode + +set -e + +# Configuration +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +HUB_ROOT="$(dirname "$SCRIPT_DIR")" +PROJECTS_ROOT="$HOME/PycharmProjects" +PROJECT_DOCS_ROOT="$PROJECTS_ROOT/project-docs" +TEMPLATES_DIR="$HUB_ROOT/templates" +CONFIG_DIR="$HOME/.config/development-hub" +TOKEN_FILE="$CONFIG_DIR/gitea-token" + +GITEA_URL="https://gitea.brrd.tech" +GITEA_SSH="ssh://git@gitea.brrd.tech:222" +GITEA_OWNER="rob" + +# Colors +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +CYAN='\033[0;36m' +NC='\033[0m' + +log_info() { echo -e "${BLUE}[INFO]${NC} $1"; } +log_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; } +log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; } +log_error() { echo -e "${RED}[ERROR]${NC} $1"; } +log_step() { echo -e "${CYAN}[STEP]${NC} $1"; } + +# Parse arguments +PROJECT_NAME="" +PROJECT_TITLE="" +PROJECT_TAGLINE="" +DRY_RUN=false +SKIP_GITEA=false + +show_help() { + cat << EOF +Usage: $(basename "$0") [options] + +Create a new project in the development ecosystem. + +Arguments: + project-name Name for the project (lowercase, alphanumeric, hyphens) + +Options: + --title "Title" Display title (default: derived from name) + --tagline "..." Short description (prompted if not provided) + --dry-run Show what would happen without doing it + --skip-gitea Skip Gitea repo creation (for offline use) + --help, -h Show this help message + +Examples: + $(basename "$0") my-tool --title "My Tool" --tagline "A useful tool" + $(basename "$0") my-tool # Interactive mode + +After creation, your project will be at: + ~/PycharmProjects// + +With documentation at: + ~/PycharmProjects/project-docs/docs/projects// +EOF +} + +parse_args() { + while [[ $# -gt 0 ]]; do + case $1 in + --title) + PROJECT_TITLE="$2" + shift 2 + ;; + --tagline) + PROJECT_TAGLINE="$2" + shift 2 + ;; + --dry-run) + DRY_RUN=true + shift + ;; + --skip-gitea) + SKIP_GITEA=true + shift + ;; + --help|-h) + show_help + exit 0 + ;; + -*) + log_error "Unknown option: $1" + show_help + exit 1 + ;; + *) + if [[ -z "$PROJECT_NAME" ]]; then + PROJECT_NAME="$1" + else + log_error "Unexpected argument: $1" + exit 1 + fi + shift + ;; + esac + done +} + +validate_name() { + local name="$1" + + if [[ -z "$name" ]]; then + log_error "Project name is required" + show_help + exit 1 + fi + + # Check format: lowercase, alphanumeric, hyphens + if [[ ! "$name" =~ ^[a-z][a-z0-9-]*$ ]]; then + log_error "Project name must be lowercase, start with a letter, and contain only letters, numbers, and hyphens" + exit 1 + fi + + # Check if project already exists + if [[ -d "$PROJECTS_ROOT/$name" ]]; then + log_error "Project directory already exists: $PROJECTS_ROOT/$name" + exit 1 + fi + + # Check if docs already exist + if [[ -d "$PROJECT_DOCS_ROOT/docs/projects/$name" ]]; then + log_error "Documentation directory already exists: $PROJECT_DOCS_ROOT/docs/projects/$name" + exit 1 + fi +} + +# Derive title from name if not provided +derive_title() { + local name="$1" + # Convert hyphens to spaces and capitalize each word + echo "$name" | sed 's/-/ /g' | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2))}1' +} + +prompt_for_missing() { + if [[ -z "$PROJECT_TITLE" ]]; then + local default_title + default_title=$(derive_title "$PROJECT_NAME") + read -rp "Project title [$default_title]: " PROJECT_TITLE + PROJECT_TITLE="${PROJECT_TITLE:-$default_title}" + fi + + if [[ -z "$PROJECT_TAGLINE" ]]; then + read -rp "Project tagline (short description): " PROJECT_TAGLINE + if [[ -z "$PROJECT_TAGLINE" ]]; then + log_error "Tagline is required" + exit 1 + fi + fi +} + +load_gitea_token() { + # Check environment variable first + if [[ -n "$GITEA_TOKEN" ]]; then + log_info "Using GITEA_TOKEN from environment" + return 0 + fi + + # Check token file + if [[ -f "$TOKEN_FILE" ]]; then + GITEA_TOKEN=$(cat "$TOKEN_FILE") + log_info "Loaded Gitea token from $TOKEN_FILE" + return 0 + fi + + # Prompt user to create token + log_warn "No Gitea API token found" + echo "" + echo "To create a token:" + echo " 1. Go to $GITEA_URL/user/settings/applications" + echo " 2. Generate a new token with 'repo' scope" + echo " 3. Copy the token" + echo "" + read -rsp "Paste your Gitea API token: " GITEA_TOKEN + echo "" + + if [[ -z "$GITEA_TOKEN" ]]; then + log_error "Token is required for Gitea API access" + log_info "Use --skip-gitea to skip repository creation" + exit 1 + fi + + # Save token for future use + mkdir -p "$CONFIG_DIR" + echo "$GITEA_TOKEN" > "$TOKEN_FILE" + chmod 600 "$TOKEN_FILE" + log_success "Token saved to $TOKEN_FILE" +} + +create_gitea_repo() { + local name="$1" + local description="$2" + + log_step "Creating Gitea repository: $name" + + if [[ "$DRY_RUN" == true ]]; then + log_info "[DRY RUN] Would create repo: $GITEA_URL/$GITEA_OWNER/$name" + return 0 + fi + + local response + response=$(curl -s -w "\n%{http_code}" -X POST "$GITEA_URL/api/v1/user/repos" \ + -H "Authorization: token $GITEA_TOKEN" \ + -H "Content-Type: application/json" \ + -d "{ + \"name\": \"$name\", + \"description\": \"$description\", + \"private\": false, + \"auto_init\": false + }") + + local http_code + http_code=$(echo "$response" | tail -n1) + local body + body=$(echo "$response" | sed '$d') + + if [[ "$http_code" == "201" ]]; then + log_success "Created repository: $GITEA_URL/$GITEA_OWNER/$name" + elif [[ "$http_code" == "409" ]]; then + log_warn "Repository already exists on Gitea" + else + log_error "Failed to create repository (HTTP $http_code)" + echo "$body" | head -5 + exit 1 + fi +} + +create_local_project() { + local name="$1" + local project_dir="$PROJECTS_ROOT/$name" + + log_step "Creating local project: $project_dir" + + if [[ "$DRY_RUN" == true ]]; then + log_info "[DRY RUN] Would create: $project_dir" + return 0 + fi + + mkdir -p "$project_dir" + cd "$project_dir" + + git init --quiet + git remote add origin "$GITEA_SSH/$GITEA_OWNER/$name.git" + + log_success "Created local project with git" +} + +apply_template() { + local template="$1" + local output="$2" + local name="$3" + local title="$4" + local tagline="$5" + + local year + year=$(date +%Y) + local date + date=$(date +%Y-%m-%d) + + sed -e "s|{{PROJECT_NAME}}|$name|g" \ + -e "s|{{PROJECT_TITLE}}|$title|g" \ + -e "s|{{PROJECT_TAGLINE}}|$tagline|g" \ + -e "s|{{YEAR}}|$year|g" \ + -e "s|{{DATE}}|$date|g" \ + -e "s|{{GITEA_URL}}|$GITEA_URL|g" \ + -e "s|{{GITEA_OWNER}}|$GITEA_OWNER|g" \ + "$template" > "$output" +} + +generate_project_files() { + local name="$1" + local title="$2" + local tagline="$3" + local project_dir="$PROJECTS_ROOT/$name" + + log_step "Generating project files from templates" + + if [[ "$DRY_RUN" == true ]]; then + log_info "[DRY RUN] Would generate files in $project_dir" + return 0 + fi + + # Generate each file from template + apply_template "$TEMPLATES_DIR/gitignore.template" "$project_dir/.gitignore" "$name" "$title" "$tagline" + apply_template "$TEMPLATES_DIR/CLAUDE.md.template" "$project_dir/CLAUDE.md" "$name" "$title" "$tagline" + apply_template "$TEMPLATES_DIR/README.md.template" "$project_dir/README.md" "$name" "$title" "$tagline" + apply_template "$TEMPLATES_DIR/pyproject.toml.template" "$project_dir/pyproject.toml" "$name" "$title" "$tagline" + + log_success "Generated project files" +} + +setup_documentation() { + local name="$1" + local title="$2" + local tagline="$3" + local docs_dir="$PROJECT_DOCS_ROOT/docs/projects/$name" + local project_dir="$PROJECTS_ROOT/$name" + + log_step "Setting up documentation" + + if [[ "$DRY_RUN" == true ]]; then + log_info "[DRY RUN] Would create: $docs_dir" + log_info "[DRY RUN] Would create symlink: $project_dir/docs" + return 0 + fi + + # Create docs directory + mkdir -p "$docs_dir" + + # Generate documentation files + apply_template "$TEMPLATES_DIR/overview.md.template" "$docs_dir/overview.md" "$name" "$title" "$tagline" + apply_template "$TEMPLATES_DIR/updating-documentation.md.template" "$docs_dir/updating-documentation.md" "$name" "$title" "$tagline" + + # Create symlink + ln -s "../project-docs/docs/projects/$name" "$project_dir/docs" + + log_success "Created documentation with symlink" +} + +update_build_script() { + local name="$1" + local title="$2" + local tagline="$3" + local build_script="$PROJECT_DOCS_ROOT/scripts/build-public-docs.sh" + + log_step "Updating build-public-docs.sh" + + if [[ "$DRY_RUN" == true ]]; then + log_info "[DRY RUN] Would add to PROJECT_CONFIG:" + log_info " PROJECT_CONFIG[\"$name\"]=\"$title|$tagline|$GITEA_OWNER|$name|$name\"" + return 0 + fi + + # Find the last PROJECT_CONFIG line and add after it + local config_line="PROJECT_CONFIG[\"$name\"]=\"$title|$tagline|$GITEA_OWNER|$name|$name\"" + + # Check if already exists + if grep -q "PROJECT_CONFIG\[\"$name\"\]" "$build_script"; then + log_warn "Project already in build script" + return 0 + fi + + # Add after the last PROJECT_CONFIG line + sed -i "/^PROJECT_CONFIG\[\"ramble\"\]/a $config_line" "$build_script" + + log_success "Added project to build script" +} + +initial_commit() { + local name="$1" + local project_dir="$PROJECTS_ROOT/$name" + + log_step "Creating initial commit" + + if [[ "$DRY_RUN" == true ]]; then + log_info "[DRY RUN] Would commit and push" + return 0 + fi + + cd "$project_dir" + git add . + git commit -m "Initial project setup + +Created by development-hub/new-project script" + + if [[ "$SKIP_GITEA" != true ]]; then + git push -u origin main 2>/dev/null || git push -u origin master 2>/dev/null || { + log_warn "Could not push to remote. You may need to push manually." + } + fi + + log_success "Created initial commit" +} + +print_summary() { + local name="$1" + local title="$2" + + echo "" + echo -e "${GREEN}========================================${NC}" + echo -e "${GREEN} Project '$title' created successfully!${NC}" + echo -e "${GREEN}========================================${NC}" + echo "" + echo "Locations:" + echo " Local: $PROJECTS_ROOT/$name/" + echo " Gitea: $GITEA_URL/$GITEA_OWNER/$name" + echo " Docs: $PROJECT_DOCS_ROOT/docs/projects/$name/" + echo "" + echo "Next steps:" + echo " 1. cd $PROJECTS_ROOT/$name" + echo " 2. Start developing!" + echo "" + echo "To publish documentation:" + echo " $PROJECT_DOCS_ROOT/scripts/build-public-docs.sh $name --deploy" + echo "" + echo "Public docs will be available at:" + echo " https://pages.brrd.tech/$GITEA_OWNER/$name/" + echo "" +} + +main() { + parse_args "$@" + validate_name "$PROJECT_NAME" + prompt_for_missing + + echo "" + log_info "Creating project: $PROJECT_NAME" + log_info "Title: $PROJECT_TITLE" + log_info "Tagline: $PROJECT_TAGLINE" + echo "" + + if [[ "$DRY_RUN" == true ]]; then + log_warn "DRY RUN - No changes will be made" + echo "" + fi + + # Load Gitea token (unless skipping) + if [[ "$SKIP_GITEA" != true ]]; then + load_gitea_token + create_gitea_repo "$PROJECT_NAME" "$PROJECT_TAGLINE" + fi + + create_local_project "$PROJECT_NAME" + generate_project_files "$PROJECT_NAME" "$PROJECT_TITLE" "$PROJECT_TAGLINE" + setup_documentation "$PROJECT_NAME" "$PROJECT_TITLE" "$PROJECT_TAGLINE" + update_build_script "$PROJECT_NAME" "$PROJECT_TITLE" "$PROJECT_TAGLINE" + initial_commit "$PROJECT_NAME" + + if [[ "$DRY_RUN" != true ]]; then + print_summary "$PROJECT_NAME" "$PROJECT_TITLE" + fi +} + +main "$@" diff --git a/templates/CLAUDE.md.template b/templates/CLAUDE.md.template new file mode 100644 index 0000000..c5404a8 --- /dev/null +++ b/templates/CLAUDE.md.template @@ -0,0 +1,49 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +**{{PROJECT_TITLE}}** - {{PROJECT_TAGLINE}} + +## Development Commands + +```bash +# Install for development +pip install -e ".[dev]" + +# Run tests +pytest + +# Run a single test +pytest tests/test_file.py::test_name +``` + +## Architecture + +*TODO: Describe the project architecture* + +### Key Modules + +*TODO: List key modules and their purposes* + +### Key Paths + +- **Source code**: `src/{{PROJECT_NAME}}/` +- **Tests**: `tests/` +- **Documentation**: `docs/` (symlink to project-docs) + +## Documentation + +Documentation for this project lives in the centralized docs system: + +- **Source**: `~/PycharmProjects/project-docs/docs/projects/{{PROJECT_NAME}}/` +- **Public URL**: `https://pages.brrd.tech/{{GITEA_OWNER}}/{{PROJECT_NAME}}/` + +When updating documentation: +1. Edit files in `docs/` (the symlink) or the full path above +2. Use `public: true` frontmatter for public-facing docs +3. Use `` / `` to hide sections +4. Run `~/PycharmProjects/project-docs/scripts/build-public-docs.sh {{PROJECT_NAME}} --deploy` to publish + +Do NOT create documentation files directly in this repository. diff --git a/templates/README.md.template b/templates/README.md.template new file mode 100644 index 0000000..ed9ca07 --- /dev/null +++ b/templates/README.md.template @@ -0,0 +1,39 @@ +# {{PROJECT_TITLE}} + +{{PROJECT_TAGLINE}} + +## Installation + +```bash +pip install -e . +``` + +## Usage + +*TODO: Add usage instructions* + +## Documentation + +Full documentation is available at: https://pages.brrd.tech/{{GITEA_OWNER}}/{{PROJECT_NAME}}/ + +## Development + +```bash +# Clone the repository +git clone {{GITEA_URL}}/{{GITEA_OWNER}}/{{PROJECT_NAME}}.git +cd {{PROJECT_NAME}} + +# Create virtual environment +python -m venv .venv +source .venv/bin/activate + +# Install for development +pip install -e ".[dev]" + +# Run tests +pytest +``` + +## License + +*TODO: Add license* diff --git a/templates/gitignore.template b/templates/gitignore.template new file mode 100644 index 0000000..30c26d7 --- /dev/null +++ b/templates/gitignore.template @@ -0,0 +1,53 @@ +# Python +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg + +# Virtual environments +.venv/ +venv/ +ENV/ + +# IDE +.idea/ +.vscode/ +*.swp +*.swo + +# OS +.DS_Store +Thumbs.db + +# Testing +.pytest_cache/ +.coverage +htmlcov/ +.tox/ +.nox/ + +# mypy +.mypy_cache/ + +# Local config +.env +*.local.yaml + +# Documentation symlink (points to project-docs) +docs diff --git a/templates/overview.md.template b/templates/overview.md.template new file mode 100644 index 0000000..6dbefef --- /dev/null +++ b/templates/overview.md.template @@ -0,0 +1,41 @@ +--- +sidebar_position: 1 +--- + +# {{PROJECT_TITLE}} + +{{PROJECT_TAGLINE}} + +## Overview + +*TODO: Add project overview* + +## Features + +*TODO: List key features* + +## Getting Started + +### Installation + +```bash +pip install -e . +``` + +### Quick Start + +*TODO: Add quick start guide* + +## Architecture + +*TODO: Describe architecture at a high level* + +## Related Projects + +This project is part of the development ecosystem: + +- [CmdForge](https://pages.brrd.tech/rob/CmdForge/) - AI-powered CLI tool builder +- [CascadingDev](https://pages.brrd.tech/rob/CascadingDev/) - Cascading Development Framework +- [Orchestrated Discussions](https://pages.brrd.tech/rob/orchestrated-discussions/) - AI Discussion Framework +- [Artifact Editor](https://pages.brrd.tech/rob/artifact-editor/) - Code Artifact Editor +- [Ramble](https://pages.brrd.tech/rob/ramble/) - Voice Note Transcription diff --git a/templates/pyproject.toml.template b/templates/pyproject.toml.template new file mode 100644 index 0000000..44127ae --- /dev/null +++ b/templates/pyproject.toml.template @@ -0,0 +1,23 @@ +[build-system] +requires = ["setuptools>=61.0", "wheel"] +build-backend = "setuptools.build_meta" + +[project] +name = "{{PROJECT_NAME}}" +version = "0.1.0" +description = "{{PROJECT_TAGLINE}}" +readme = "README.md" +requires-python = ">=3.10" +dependencies = [] + +[project.optional-dependencies] +dev = [ + "pytest>=7.0", + "pytest-cov>=4.0", +] + +[tool.setuptools.packages.find] +where = ["src"] + +[tool.pytest.ini_options] +testpaths = ["tests"] diff --git a/templates/updating-documentation.md.template b/templates/updating-documentation.md.template new file mode 100644 index 0000000..62ebcfd --- /dev/null +++ b/templates/updating-documentation.md.template @@ -0,0 +1,134 @@ +--- +sidebar_label: Updating Documentation +sidebar_position: 99 +--- + +# How to Update Documentation + +This document explains the documentation system and procedures for updating {{PROJECT_TITLE}} documentation. + +## Documentation Architecture + +{{PROJECT_TITLE}} documentation is managed through a **centralized documentation system**: + +``` +~/PycharmProjects/project-docs/ # Central documentation hub +├── docs/projects/{{PROJECT_NAME}}/ # Docs source (THIS FOLDER) +├── scripts/build-public-docs.sh # Builds public docs +└── public-builds/{{PROJECT_NAME}}/ # Built static site + +~/PycharmProjects/{{PROJECT_NAME}}/ +└── docs -> ../project-docs/docs/projects/{{PROJECT_NAME}}/ # Symlink to here +``` + +## Two Documentation Modes + +### Private Documentation (Internal) + +- **Location**: `~/PycharmProjects/project-docs/` +- **View locally**: `cd ~/PycharmProjects/project-docs && npm start` +- **Contains**: All docs including credentials, internal notes, todos, deployment details +- **Audience**: Internal team only + +### Public Documentation (Contributors) + +- **Location**: `https://pages.brrd.tech/{{GITEA_OWNER}}/{{PROJECT_NAME}}/` +- **Build command**: `~/PycharmProjects/project-docs/scripts/build-public-docs.sh {{PROJECT_NAME}} --deploy` +- **Contains**: Only whitelisted public files +- **Audience**: Open-source contributors + +## File Visibility Rules + +### Automatically Public Files + +These filenames are included in public builds: +- `overview.md` +- `architecture.md` +- `formats.md` +- `configuration.md` +- `index.md` + +### Making Other Files Public + +Add frontmatter to include a file in public builds: + +```markdown +--- +public: true +--- + +# Your Document Title +``` + +### Hiding Sections Within Public Files + +Use HTML comments to hide sensitive sections: + +```markdown +## Public Section + +This content is visible to everyone. + + +## Internal Notes + +This section is stripped from public builds. +Credentials, internal discussions, etc. + + +## Another Public Section +``` + +## Procedures + +### Adding New Documentation + +1. Create the file in `~/PycharmProjects/project-docs/docs/projects/{{PROJECT_NAME}}/` +2. Add appropriate frontmatter (title, sidebar position) +3. If it should be public, either: + - Use a whitelisted filename, OR + - Add `public: true` to frontmatter +4. Preview locally: `cd ~/PycharmProjects/project-docs && npm start` + +### Updating Existing Documentation + +1. Navigate via symlink: `cd ~/PycharmProjects/{{PROJECT_NAME}}/docs` + - Or directly: `cd ~/PycharmProjects/project-docs/docs/projects/{{PROJECT_NAME}}` +2. Edit the relevant `.md` file +3. Preview locally if needed + +### Publishing to Public Site + +```bash +# Build and deploy {{PROJECT_NAME}} docs only +~/PycharmProjects/project-docs/scripts/build-public-docs.sh {{PROJECT_NAME}} --deploy + +# Or build all projects +~/PycharmProjects/project-docs/scripts/build-public-docs.sh --deploy + +# Dry run (see what would happen) +~/PycharmProjects/project-docs/scripts/build-public-docs.sh {{PROJECT_NAME}} --dry-run +``` + +### Viewing Documentation + +```bash +# Private docs (all content) +cd ~/PycharmProjects/project-docs && npm start +# Opens http://localhost:3000 + +# Public docs +# Visit https://pages.brrd.tech/{{GITEA_OWNER}}/{{PROJECT_NAME}}/ +``` + +## For AI Assistants + +When asked to update documentation for this project: + +1. **DO** edit files in `docs/` (the symlink) or the full path above +2. **DO NOT** create documentation files in the project root +3. **DO** use appropriate visibility (public/private) based on content +4. **DO** run the build script if publishing changes to the public site +5. **DO** preview changes locally before publishing + +The `docs/` folder you see in this project is a symlink to the central documentation system. All changes are reflected in both the private hub and (after building) the public site.