🛠 Documentation Site Setup¶

This guide outlines how to generate, sanitize, build, and publish the documentation site for pg-schemata.

📄 JSDoc Annotations¶

Documentation is generated from JSDoc comments in the codebase using documentation.js.

📁 Folder Structure¶

pg-schemata/
├── src/                         # Source code with JSDoc comments
├── pg-schemata-docs/
│   └── documentation/          # Generated .md files
├── docs-site/
│   ├── docs/                   # Sanitized Markdown files for MkDocs
│   ├── mkdocs.yml              # MkDocs site configuration
│   └── ...

📦 Install JS Dependencies¶

Run the following to install documentation.js and related tooling:

npm install

📜 Build Documentation Files¶

Use the following script from package.json to generate both documentation files and sanitize the output:

"scripts": {
    "docs": "documentation build src/index.js -f md -o pg-schemata-docs/documentation/pg-schemata.md && documentation build src/schemaTypes.d.ts -f md -o pg-schemata-docs/documentation/schemaTypes.md && node ./pg-schemata-docs/sanitizeToc.js",
}

Run with:

npm run docs

This generates both documentation files and sanitizes the output using the sanitizeToc.js script.

🐍 Python & MkDocs Setup¶

Install Python (via Homebrew)

brew install python

Create Virtual Environment

python3 -m venv venv

Activate Environment

source venv/bin/activate

Install MkDocs and Plugins

pip install mkdocs mkdocs-material mkdocs-material-extensions==1.3.1

🛠 Build & Preview MkDocs Site¶

From inside the pg-schemata-docs/ folder (run source venv/bin/activate first if python is already setup):

mkdocs serve

To build static site output:

mkdocs build

🚀 Publish to GitHub Pages¶

To publish built site:

mkdocs gh-deploy

This pushes the site to the gh-pages branch of your repository and makes it live.

✅ Requirements Summary¶

Node.js v18+
Python 3.10+
documentation.js
MkDocs Material theme v9.6.14+
mkdocs-material-extensions v1.3.1+