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