rob
/
development-hub
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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:
rob 2026-01-05 18:25:36 -04:00
commit 28f40f7edd
10 changed files with 995 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
.gitignore vendored Normal file
View File

@ -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

104
CLAUDE.md Normal file
View File

@ -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`.

76
README.md Normal file
View File

@ -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/

455
bin/new-project Executable file
View File

@ -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 "$@"

49
templates/CLAUDE.md.template Normal file
View File

@ -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.

39
templates/README.md.template Normal file
View File

@ -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*

53
templates/gitignore.template Normal file
View File

@ -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

41
templates/overview.md.template Normal file
View File

@ -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

23
templates/pyproject.toml.template Normal file
View File

@ -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"]

134
templates/updating-documentation.md.template Normal file
View File

@ -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.