hem-doc

Documentation site for the Hemlock programming language and hpm package manager.

How It Works

This repo builds a single-file HTML documentation viewer from the markdown files in the hemlock and hpm submodules. The generated docs.html is deployed to GitHub Pages automatically.

It also includes a standalone documentation server built with Sprout, allowing you to serve the docs locally or deploy them anywhere.

Prerequisites

• Hemlock - The Hemlock interpreter
• hpm - Hemlock Package Manager

Quick Start

Using Make

# Install dependencies and generate docs
make deps
make docs

# Build the documentation server
make server

# Run the server locally (http://localhost:3000)
make run

# Create a distribution package (zip with server + docs)
make dist

Manual Setup

1. Clone the repository with submodules:

   git clone --recursive https://github.com/hemlang/hem-doc.git
   cd hem-doc

   Or if you already cloned without --recursive:

   git submodule update --init --recursive

2. Install dependencies:

   hpm install

3. Build the documentation:

   # Build English only (default)
   python3 build_docs.py
   
   # Build a specific language
   python3 build_docs.py --lang zh    # Chinese
   python3 build_docs.py --lang ru    # Russian
   
   # Build all 9 languages
   python3 build_docs.py --lang all

   Supported languages: en, zh, de, es, fr, it, ja, pt, ru

4. Open docs.html in your browser, or run the server:

   hemlock serve.hml

Documentation Server

The documentation server is a self-contained executable built with Hemlock and Sprout:

# Build the server (requires hemlock in PATH or set HEMLOCK env var)
make server

# Run it
./hem-doc-server
# Serving docs at http://localhost:3000

The server provides (every route also answers HEAD):

• /, /docs.html, /docs-<lang>.html - The documentation HTML (falls back to English if a translation is missing)
• /llms.txt, /llms-<lang>.txt - LLM-friendly plain text
• /robots.txt - Allows all crawlers and points at the sitemap
• /sitemap.xml - Lists the languages whose docs loaded at startup
• /favicon.ico - The Hemlock favicon (favicon.svg, served as image/svg+xml)
• /health - Health check (JSON): status (ok, or degraded if any docs/llms file is missing), version, started_at, and per-language loaded flags and byte sizes

Missing translations, llms files and the favicon are optional; only docs.html is required.

Run the route tests with make test (requires make deps).

Updating Submodules

This repository uses Git submodules for the hemlock and hpm documentation sources. Here's how to manage them:

Update All Submodules

To pull the latest changes from both hemlock and hpm repos:

# Update all submodules to their latest commits
git submodule update --remote --merge

# Rebuild the documentation
make docs

# Commit the updated submodule references (if changed)
git add hemlock hpm
git commit -m "Update submodules to latest"

Update a Specific Submodule

To update just one submodule:

# Update only hemlock
git submodule update --remote --merge hemlock

# Update only hpm
git submodule update --remote --merge hpm

Initialize Submodules (First Time Clone)

If you cloned without --recursive, initialize the submodules:

git submodule update --init --recursive

Check Submodule Status

To see which commits the submodules are pointing to:

git submodule status

Project Structure

hem-doc/
├── Makefile               # Build automation
├── build_docs.py          # Documentation generator script (Python)
├── build_docs.hml         # Documentation generator script (Hemlock)
├── serve.hml              # Documentation server entry point (Hemlock/Sprout)
├── server.hml             # Server routes and handlers
├── test_server.hml        # Server route tests (make test)
├── favicon.svg            # Site favicon
├── hemlock/               # Git submodule (hemlock source)
│   ├── CLAUDE.md          # Main language reference
│   ├── docs/              # Additional documentation
│   └── logo.png           # Logo embedded in docs
├── hpm/                   # Git submodule (hpm source)
│   └── docs/              # hpm documentation
├── docs.html              # Generated output (English)
├── docs-*.html            # Generated output (other languages)
├── llms.txt               # LLM-friendly plain text (English)
├── llms-*.txt             # LLM-friendly plain text (other languages)
└── .github/workflows/
    ├── build-docs.yml     # Builds and deploys to GitHub Pages
    └── sync-submodule.yml # Daily sync of submodules

Make Targets

Target	Description
make deps	Install dependencies via hpm
make docs	Generate docs.html (English) from hemlock source
make docs-all	Generate docs for all 9 languages
make server	Package the documentation server executable
make dist	Create distribution zip (server + docs.html)
make run	Run the documentation server locally
make test	Run the server route tests
make clean	Remove build artifacts
make help	Show help message

CI/CD

• build-docs.yml: Builds and deploys documentation to GitHub Pages on push to main
• sync-submodule.yml: Automatically updates the hemlock and hpm submodules daily and on-demand