This repository contains the Pantheon documentation, as well as the tools to build local test environmnets.
Read style-guide.md for our guidelines on how to write documentation.
Get the Code
Fork and clone this repository. Issue pull requests per document.
Local Setup (Optional)
If you would like to develop documentation locally and see your work, we offer a Docker containerized solution.
- MacOS or Linux system (untested on Bash on Windows)
Clone the repository to your project directory:
cd ~/projects git clone https://github.com/pantheon-systems/documentation.git OR git clone firstname.lastname@example.org:pantheon-systems/documentation.git
Pull the Docker image:
docker image pull pantheonsystems/documentation
From the project root, execute the
cd documentation ./runthedocs.sh
Note:: This will occupy the terminal in which you invoke the script, providing output when files are changed or loaded. Use CTRL + C to exit.
You should see:
Creating the Docker container... Container built and running. 👍👍 Building the latest docs... Detected new or updated files Generating: 100% (1035 sources / 0.06 seconds) Converting: 100% (1122 sources / 8.04 seconds) Formatting: 100% (1122 sources / 2.73 seconds) Processing completed in 12.20 seconds Running "watch" task Waiting...
Once running, you can view the local dev environment by visiting
http://localhost:8000/docsin your browser.
The Docker image will mount the
sourcedirectory from the project root on your computer, and rebuild when you save changes:
/documentation/source/_docs/getting-support.md was changed. Building... Detected new or updated files Generating: 100% (1035 sources / 0.04 seconds) Converting: 100% (1122 sources / 5.73 seconds) Formatting: 100% (1122 sources / 2.01 seconds) Processing completed in 9.05 seconds
When you're done, run:
docker container stop pantheon-docs
Update The Docs
pantheon-docs container mounts the
documentation/source directory from your computer, so the image remains evergreen as long as the toolset is unchanged. To update your local project with the latest version of the docs, you need only pull them from git:
git pull origin
Update The App
To update the documentation build locally run:
We include several tools to test that new content doesn't break the documentation. Most of these tests are performed automatically by our continuous integration service, but pull requests created from external contributors aren't included in CI tests. If you want to manually test your branch, you can execute the following tests within the Docker container.
To check for merge conflict messages accidentally commited into the docs, run the
docker exec pantheon-docs scripts/merge_conflicts.sh Merge conflict:pass
To make sure all relative links (like
/docs/support/) are correct, run
docker exec pantheon-docs htmlproofer --assume-extension ./output_dev/ --disable-external true
We use grunt to manage accessibility tests:
docker exec pantheon-docs node_modules/.bin/grunt test Running "a11y:dev" (a11y) task Done, without errors.
Checks for visual regression:
docker exec pantheon-docs wraith capture wraith.yaml
docker exec pantheon-docs bin/behat