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
This commit is contained in:
commit
28f40f7edd
|
|
@ -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
|
||||||
|
|
@ -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`.
|
||||||
|
|
@ -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/
|
||||||
|
|
@ -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") <project-name> [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/<project-name>/
|
||||||
|
|
||||||
|
With documentation at:
|
||||||
|
~/PycharmProjects/project-docs/docs/projects/<project-name>/
|
||||||
|
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 "$@"
|
||||||
|
|
@ -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 `<!-- PRIVATE_START -->` / `<!-- PRIVATE_END -->` 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.
|
||||||
|
|
@ -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*
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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"]
|
||||||
|
|
@ -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.
|
||||||
|
|
||||||
|
<!-- PRIVATE_START -->
|
||||||
|
## Internal Notes
|
||||||
|
|
||||||
|
This section is stripped from public builds.
|
||||||
|
Credentials, internal discussions, etc.
|
||||||
|
<!-- PRIVATE_END -->
|
||||||
|
|
||||||
|
## 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.
|
||||||
Loading…
Reference in New Issue