Add some developer doc and additional tools

Note that run_tests.sh was reporting an error, however the CI tests were passing. I added an explicit exit command to ensure the build fails if there are any failed projects. I also added an explicit declaration of the shell to the top of run_tests.sh since I run zsh by default, and this script relies on bash specific features. Also added the "sphinx-autobuild" tool and a "develop.sh" script that can be used to run it. It opens up a live HTML server that reloads your documentation every time it is saved, allowing you to preview it every time you save a file.
coleshaw · Jan 27, 2015 · 8474b34 · 8474b34
1 parent 2d58767
commit 8474b34
Show file tree

Hide file tree

Showing 7 changed files with 93 additions and 92 deletions.
diff --git a/.gitignore b/.gitignore
@@ -68,3 +68,6 @@ lms/lib/comment_client/python
 autodeploy.properties
 .ws_migrations_complete
 dist
+
+### Testing artifacts
+test_root/
diff --git a/README.rst b/README.rst
@@ -50,4 +50,48 @@ Flow`_.
 .. _GitHub Flow: https://github.com/blog/1557-github-flow-in-the-browser
 
 All pull requests need approval from edX. For more information, contact edX at
-[email protected].
+[email protected].
+
+Before submitting a pull request, it is recommend you run the test suite on
+your contribution to ensure it can be compiled without errors.
+
+To run a test compilation of a contribution, first install the prerequisites:
+
+.. code::
+  
+  pip install -r requirements.txt
+
+Then run the tests:
+
+.. code::
+
+  ./run_tests.sh
+
+Additionally, you can run tests for a single project:
+
+.. code::
+  
+  ./run_tests.sh en_us/install_operations/
+
+A convenience script is provided to help you develop new documentation. To use
+it you must first install the optional tools, and then run the script.
+
+.. code::
+
+  pip install -r shared/tools.txt
+  ./develop.sh en_us/install_operations/
+
+It will output a line of text that looks like this:
+
+::
+
+  Serving on http://127.0.0.1:9090
+
+You can copy this URL into a web browser to see the HTML output for your
+project.
+
+The command starts an HTTP server that renders the HTML for the project. This
+HTTP server also monitors the project and detects any changes. When you save a
+change to a file, the server rebuilds the HTML and refreshes your browser
+automatically. In this way you can rapidly see how changes you make will be
+rendered as HTML.
diff --git a/develop.sh b/develop.sh
@@ -0,0 +1,18 @@
+#!/bin/bash
+
+# Allows you to preview the HTML for a project "live" in a browser view that updates everytime an ReST file is changed.
+
+[ $# -eq 0 ] && { echo "Usage: $0 path/to/project [port]"; exit 1; }
+
+if [ -z "$(which sphinx-autobuild)" ]
+then
+    echo "sphinx-autobuild not found. You can install it with the command 'pip install -r shared/tools.txt'. Exiting."
+    exit 2
+fi
+
+project_dir=$1
+port=${2:-9090}
+
+cd $1
+make html
+sphinx-autobuild -b html -d build/doctrees -c source source build/html --port $port
diff --git a/requirements.txt b/requirements.txt
@@ -0,0 +1 @@
+shared/travis_requirements.txt
diff --git a/run_tests.sh b/run_tests.sh
@@ -1,7 +1,14 @@
+#!/bin/bash
+
 # Each documentation project is in a directory in the en_us folder.
 # To generate docs for a project, Go to a project directory and
 # run `make HTML` and `make latexpdf`.
 
+# To test a subset of projects you can pass them in as command line
+# arguments to this script.  For example:
+# `./run_tests.sh en_us/install_operations` would only run tests on
+# the install operations project.
+
 # The directory that this script is located in.
 BASE_DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
 
@@ -24,16 +31,20 @@ SPHINX_ERRORS=0
 # build to fail.
 SPHINX_WARNINGS=0
 
-projects=(
-    "en_us/course_authors" 
-    "en_us/data"
-    "en_us/install_operations"
-    "en_us/mobile"
-    "en_us/olx"
-    "en_us/ORA2"
-    "en_us/release_notes"
-    "en_us/students"
-)
+projects=($@)
+if [ ${#projects[@]} -eq 0 ]
+then
+    projects=(
+        "en_us/course_authors" 
+        "en_us/data"
+        "en_us/install_operations"
+        "en_us/mobile"
+        "en_us/olx"
+        "en_us/ORA2"
+        "en_us/release_notes"
+        "en_us/students"
+    )
+fi
 
 for project in "${projects[@]}"; do
     cd $BASE_DIR/$project
@@ -88,11 +99,15 @@ echo TOTAL SPHINX ERRORS: $SPHINX_ERRORS
 echo TOTAL SPHINX WARNINGS: $SPHINX_WARNINGS
 echo OTHER BUILD ERRORS: $BUILD_ERRORS
 
+EXIT_STATUS=0
 if [ ${#FAILED_BUILDS[@]} -gt 0 ]; then
     echo "There were errors while building the following projects:"
     for project in "${FAILED_BUILDS[@]}"; do
         echo $project
     done
+    EXIT_STATUS=1
 else
     echo "All builds passed."
 fi
+
+exit $EXIT_STATUS
diff --git a/shared/requirements.txt b/shared/requirements.txt
diff --git a/shared/tools.txt b/shared/tools.txt
@@ -0,0 +1 @@
+sphinx-autobuild==0.4.0