PlanExe Documentation

This repository contains the built documentation for PlanExe, hosted on GitHub Pages at docs.planexe.org.

Overview

The documentation source files are maintained in the main PlanExe repository in the docs directory. This repository contains the compiled output from MkDocs Material, which is automatically deployed to GitHub Pages.

Architecture

• Source: PlanExeOrg/PlanExe/docs
• Build Tool: MkDocs Material
• Output: This repository (deployed to GitHub Pages)
• Domain: docs.planexe.org

Local Development

Prerequisites

• Python 3.8+
• pip

Setup

1. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

   pip install -r requirements.txt

3. Clone both repositories:

   # Clone this repo
   git clone https://github.com/PlanExeOrg/PlanExe-docs.git
   cd PlanExe-docs
   
   # Clone the PlanExe repo (adjust path as needed)
   git clone https://github.com/PlanExeOrg/PlanExe.git ../PlanExe

4. Build the documentation:

   python build.py

   Or manually:

   # Copy docs from PlanExe repo
   cp -r ../PlanExe/docs/* docs/
   
   # Build
   mkdocs build

5. Preview locally:

   python serve.py

   Then open http://127.0.0.1:18525 in your browser.

Custom Build Paths

If your PlanExe repo is in a different location:

PLANEXE_REPO=/path/to/PlanExe DOCS_SOURCE_DIR=docs python build.py

Deployment

Manual Deployment

1. Build the documentation:

   python build.py

2. Copy the site/ directory contents to the repository root:

   cp -r site/* .

3. Commit and push:

   git add .
   git commit -m "Update documentation"
   git push

Automated Deployment

See .github/workflows/deploy.yml for GitHub Actions automation.

Why doesn’t the site rebuild when I push docs changes in PlanExe?

The docs site is built and deployed from this repo (PlanExe-docs). Pushing to the PlanExe repo does not run workflows here. Rebuilds happen when:

1. Someone pushes to main on PlanExe-docs (this repo), or
2. Someone manually runs the “Deploy Documentation” workflow in PlanExe-docs (Actions → Deploy Documentation → Run workflow), or
3. The PlanExe repo triggers a rebuild when docs/ changes on main.

For (3), the PlanExe repo has a workflow (.github/workflows/docs-update.yml) that sends a repository_dispatch to this repo when files under docs/ change. For that to work you must configure a secret in the PlanExe repo named PLANEXE_DOCS_DISPATCH_TOKEN (PlanExe → Settings → Secrets and variables → Actions).

Token value: use a GitHub Personal Access Token that can trigger workflows in this repo. A fine-grained token is recommended (narrower permissions). Fine-grained tokens have a maximum expiration of 1 year, so the secret must be renewed annually.

Create or renew the fine-grained token:

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens.
2. Generate new token (or open an existing one to regenerate/check expiry).
3. Token name: e.g. PlanExe docs dispatch.
4. Expiration: set the maximum (1 year); add a calendar reminder to renew before it expires.
5. Resource owner: your user or the org that owns PlanExe.
6. Repository access: Only select repositories → choose PlanExeOrg/PlanExe-docs.
7. Permissions → Repository permissions: set Contents to Read and write (required for the repository_dispatch API; Actions alone is not enough).
8. Generate the token, copy it (it is shown only once), then in the PlanExe repo update the PLANEXE_DOCS_DISPATCH_TOKEN secret with this value.

Alternative: a classic PAT with repo scope also works and can have a longer or no expiration.

If the secret is missing or expired, the “Notify docs deploy” job in PlanExe will fail and the site will not rebuild. Until the token is set, use option (2) and manually run “Deploy Documentation” in PlanExe-docs after merging docs changes.

Troubleshooting deployment

The main place to check is the PlanExe-docs Actions page: github.com/PlanExeOrg/PlanExe-docs/actions. There you can see all workflow runs: “Deploy Documentation” (builds the site and deploys to GitHub Pages) and “pages build and deployment” (GitHub’s Pages publish). Runs triggered by a docs change in PlanExe show the event docs-updated and “Repository dispatch triggered by …”. Use this page to confirm a deploy ran, re-run a failed workflow, or manually start “Deploy Documentation” (Actions → Deploy Documentation → Run workflow).

• Site didn’t update after pushing to PlanExe/docs? Open the PlanExe-docs Actions page. If there is no “Deploy Documentation” run for your push, the trigger from PlanExe likely failed — check the PlanExe Actions tab: a failed “Notify docs deploy” job will show the API error (e.g. token missing Contents: Read and write). If “Deploy Documentation” ran but failed, open that run and fix the error shown in the logs. If it succeeded, wait a minute or two for GitHub Pages to update and try a hard refresh (Ctrl+Shift+R / Cmd+Shift+R) or a private window to avoid cache.
• “Notify docs deploy” succeeded in PlanExe, but no “Deploy Documentation” run appears in PlanExe-docs? The dispatch API may have rejected the request (e.g. 403). Fine-grained tokens need Contents: Read and write on PlanExe-docs; Actions alone is not enough. Update the token with that permission and update PLANEXE_DOCS_DISPATCH_TOKEN in the PlanExe repo. After the change, the PlanExe workflow fails the job and prints the API response when the dispatch is rejected, so the exact error will appear in PlanExe Actions.

Configuration

The MkDocs configuration is in mkdocs.yml. Key settings:

• Site URL: https://docs.planexe.org
• Theme: Material for MkDocs
• Source: Points to PlanExe repo's docs directory

Contributing

To contribute to the documentation:

1. Edit files in the PlanExe repository's docs directory
2. Build and test locally using the instructions above
3. Submit a pull request to the PlanExe repository
4. After merging, rebuild and deploy to this repository

License

MIT License - see LICENSE file.