clean up runthedocs and README

README.md

@@ -22,11 +22,13 @@ Fork and clone this repository. Issue pull requests per document.
 
 If you would like to develop documentation locally and see your work, we offer a Docker containerized solution.
 
-**Prerequisites**
+### Prerequisites
 
  - MacOS or Linux system (untested on Bash on Windows)
  - Docker
 
+### Install
+
 1. Clone the repository to your project directory:
 
     ```bash
@@ -38,13 +40,15 @@ If you would like to develop documentation locally and see your work, we offer a
     git clone git@github.com:pantheon-systems/documentation.git
     ```
 
-2. Pull the Docker image:
+1. Pull the Docker image:
 
     ```bash
     docker image pull pantheonsystems/documentation
     ```
 
-3. From the project root, run the `runthedocs.sh` script:
+### Run
+
+1. From the project root, execute the `runthedocs.sh` script:
 
     ```bash
     cd documentation
@@ -53,17 +57,89 @@ If you would like to develop documentation locally and see your work, we offer a
 
     **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.
 
-    The Docker image will mount the `source` directory from the project root, and rebuild when you save changes.
+    You should see:
 
-4. When you're done, run:
+    ```bash
+    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...
+    ```
+
+    The Docker image will mount the `source` directory from the project root on your computer, and rebuild when you save changes:
+
+    ```bash
+    /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
+    ```
+
+1. When you're done, run:
 
     ```bash
     docker container stop pantheon-docs
     ```
 
+### Update
+
+Because the Docker container uses the `source` directory you cloned into your project directory, you only need to update it when there's a change to the toolset. Otherwise, `git pull` will bring you the latest docs content.
 
-5. To update the documentation build locally run:
+1. To update the documentation build locally run:
 
     ```bash
     ./updater.sh
     ```
+
+### Testing
+
+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.
+
+#### Merge Conflicts
+
+To check for merge conflict messages accidentally commited into the docs, run the `merge_conflicts.sh` script:
+
+```bash
+docker exec pantheon-docs scripts/merge_conflicts.sh
+Merge conflict:pass
+```
+#### URL Validation
+
+To make sure all relative links (like `/docs/support/`) are correct, run
+
+```bash
+docker exec pantheon-docs htmlproofer --assume-extension  ./output_dev/ --disable-external true
+```
+
+#### [A11y](https://github.com/addyosmani/a11y)
+
+We use grunt to manage accessibility tests:
+
+```bash
+docker exec pantheon-docs node_modules/.bin/grunt test
+Running "a11y:dev" (a11y) task
+
+Done, without errors.
+```
+
+#### [Wraith](https://github.com/BBC-News/wraith)
+
+Checks for visual regression:
+
+```bash
+docker exec pantheon-docs wraith capture wraith.yaml
+```
+
+#### [Behat](https://github.com/Behat/Behat)
+
+```bash
+docker exec pantheon-docs bin/behat
+```

runthedocs.sh

@@ -1,16 +1,19 @@
 #/bin/bash
 
+printf "Creating the Docker container... \n"
 
 # Invoke the docker image with a shared volume for source.
-if docker run -p 8000:8000 --name=pantheon-docs -v $(pwd)/source:/documentation/source -dit pantheonsystems/documentation; then
-    printf "Container built and running \n"
+if docker run -p 8000:8000 --name=pantheon-docs -v $(pwd)/source:/documentation/source -dit pantheonsystems/documentation > /dev/null 2>&1; then
+    printf "Container built and running. 👍👍 \n"
 else
-    printf "Container exists... \n"
+    printf "Container exists, restarting... \n"
     docker container start pantheon-docs
+    printf "\n"
+    printf "Container restarted. 👍👍 \n"
 fi
 
 printf "Building the latest docs... \n"
-docker exec pantheon-docs /documentation/node_modules/.bin/grunt --force
+docker exec pantheon-docs /documentation/node_modules/.bin/grunt --force > /dev/null
 docker exec pantheon-docs /documentation/bin/sculpin generate --env=dev
 
 # Start app script, which invokes grunt, the watch script, and a simple PHP web server