This repository contains the source code and configuration for the official phēnix documentation.
The documentation is built using Material for MkDocs and versioned with mike.
Documentation is built and deployed automatically using GitHub Actions.
mainbranch: Pushing tomainwill automatically build and deploy thelatestversion of the docs.devbranch: Pushing todevwill automatically build and deploy thedevversion of the docs.
The workflow will commit the built static site to the gh-pages branch and push it to the repository, publishing the changes. No manual deployment is necessary.
Note
You will see a second workflow named "pages-build-deployment" running automatically after the deployment workflow completes.
This is the standard GitHub system workflow that takes the static files pushed to the gh-pages branch and actually serves them to the web.
Do not disable this workflow. It is required for the site to be visible.
To preview documentation changes from a feature branch before merging:
- Go to the Actions tab in the repository.
- Select the Deploy Documentation workflow.
- Click Run workflow, select your feature branch, and click Run workflow.
This will deploy a version named after your branch (e.g., feat-new-docs). When the corresponding Pull Request is closed, this preview version is automatically deleted.
Important
Note for Forks: To preview deployments on your own fork, you must enable GitHub Pages:
- Go to Settings > Pages.
- Under Build and deployment > Source, select Deploy from a branch.
- Under Branch, select
gh-pagesand/ (root). - Click Save.
Your site will be available at https://<username>.github.io/sceptre-phenix-docs/.
To build and serve the documentation locally, which includes the versioning selector, run:
make serveThe docs will be served on localhost:8000 by a Docker container.
Any changes to the Markdown files or mkdocs.yml will trigger an
automatic rebuild while the container is running. This alleviates
the need to run the command every time a change is made.