fill in build logic for dev

internal/main

@@ -355,6 +355,35 @@ function setup {
     docker build .rax-docs/repo/resources -t rax-docs
 }
 
+function docker_run {
+    docker image inspect rax-docs > /dev/null || {
+	echo "You need to set up your local environment first. Try running 'rax-docs setup'."
+	exit 1
+    }
+    docker run --rm \
+                -v "$PWD":/src \
+                -v "$HOME"/.ssh:/ssh_config \
+                -w /src \
+                --dns=10.13.90.38 --dns=10.13.90.39 --dns=8.8.8.8 \
+                --dns-search=rackspace.com \
+                -e OUTER_PWD="$PWD" \
+                -e PLEASE=true \
+                --user "$(id -u)":"$(id -g)" \
+                rax-docs "$@"
+}
+
+function docker_make {
+    docker_run make -C /src/docs -f /src/.rax-docs/repo/resources/Makefile "$@"
+}
+
+function html {
+    docker_make html
+}
+
+function testy {
+    docker_make test
+}
+
 function usage {
     cat <<EOF
 Usage: rax-docs <command> [command-options]
@@ -451,7 +480,7 @@ TOPCMD="$1"
 shift
 
 case $TOPCMD in
-    internal_install|status|usage|setup)
+    internal_install|status|usage|setup|html|testy)
 	$TOPCMD "$@"
 	;;
 

it/docker-image.bats

@@ -59,3 +59,38 @@ function teardown {
     run docker run --rm rax-docs vale --version
     [ "$output" = "vale version 2.4.0" ]
 }
+
+@test "the toolkit can use the image to build a simple docs project" {
+    mkdir docs
+    echo "Hello world" > docs/contents.rst
+    touch docs/conf.py
+    run ./rax-docs html
+    [ "$status" -eq 0 ]
+    [ -f docs/_build/html/contents.html ]
+    [[ "$(cat docs/_build/html/contents.html)" =~ Hello\ world ]]
+}
+
+@test "the toolkit can use the image to test a simple docs project" {
+    mkdir docs
+    echo "Hello world. The pencil will be returned upon completion." > docs/contents.rst
+    echo "from sphinxcontrib import spelling" > docs/conf.py
+    echo "extensions = ['sphinxcontrib.spelling']" >> docs/conf.py
+    run ./rax-docs test
+    [ "$status" -eq 0 ]
+    PHRASES=(
+	# The html pages get built
+	'HTML finished. The pages are in'
+	# Vale checks style
+	'Vale Finished. Output is in'
+	# It should've found an error
+	"'be returned' looks like"
+	# doc8 check style
+	'Detailed error counts:'
+	# spelling runs
+	'Spell check finished. The spellcheck output is in'
+    )
+    for PHRASE in "${PHRASES[@]}"; do
+	echo "Check phrase: $PHRASE"
+	[[ "$output" =~ $PHRASE ]]
+    done
+}

resources/Makefile

@@ -0,0 +1,53 @@
+# This Makefile is for internal use only. Please see top-level
+# tools/documentation. This file focuses on running the tools. It
+# doesn't deal with setting up the environment at all.
+
+ifndef PLEASE
+$(error "You should use the 'rax-docs' command for all documentation	\
+	tasks. If you think you know what you're doing, say PLEASE")
+endif
+
+ifdef JENKINS_URL
+# Running in Jenkins, so everything has to happen within the workspace
+styles_dir = styles
+temp_dir = ./
+template_path = .rax-docs/repo/resources/vale.ini.template
+else
+# Running in Docker, so resources will be where they were installed in
+# the image
+styles_dir = /styles
+temp_dir = /tmp
+template_path = /src/.rax-docs/repo/resources/vale.ini.template
+endif
+
+.PHONY: clean html htmlvers spelling vale test
+
+clean:
+	rm -rf _build/*
+
+test: spelling vale
+	doc8
+	@echo "All tests completed"
+	@echo
+
+html:
+	sphinx-build -E -q -b html -d _build/doctrees . _build/html
+	@echo "HTML finished. The pages are in $(OUTER_PWD)/docs/_build/html"
+	@echo
+
+vale: html
+	TEMP=$$(mktemp --tmpdir=$(temp_dir)) && \
+	sed 's#{{styles_path}}#$(styles_dir)#' < $(template_path) > "$$TEMP" && \
+	vale --config "$$TEMP" _build/html/* | tee _build/vale_output.txt || true
+	@echo "Vale Finished. Output is in $(OUTER_PWD)/docs/_build/vale_output.txt"
+	@echo
+
+htmlvers:
+	sphinx-versioning -l conf.py build docs _build/html/
+	@echo "Versioned HTML. The HTML pages are in $(OUTER_PWD)/docs/_build/html"
+	@echo
+
+spelling: html
+	sphinx-build -W -b spelling -d _build/doctrees . _build/spelling
+	@echo "Spell check finished. The spellcheck output is in $(OUTER_PWD)/docs/_build/spelling"
+	@echo

resources/vale.ini.template

@@ -0,0 +1,32 @@
+# Rackspace Vale
+
+
+# CI builds will only fail on error-level alerts.
+# MinAlertLevel specifies the minimum alert severity that Vale will report.
+# The options are "suggestion," "warning," or "error" (defaults to "suggestion").
+MinAlertLevel = suggestion
+
+# The path to your _build folder (relative to the configuration file).
+SphinxBuildPath = _build
+
+# The command that builds your site (make html is the default for Sphinx).
+# If this is defined, Vale will re-build your site prior to linting any content—making it possible to use Sphinx
+# and Vale in lint-on-the-fly environments (e.g., text editors) at the cost of performance.
+#SphinxAutoBuild = make html
+
+# Specifies inline-level HTML tags to ignore. In other words, these tags may occur in an active scope
+# (unlike SkippedScopes, which are skipped entirely) but their content still won't raise any alerts.
+IgnoredScopes = code
+
+# Specifies where Vale should look for its external resources (e.g., styles and ignore files).
+# The path value may be absolute or relative to the location of the parent .vale.ini file.
+# The styles path for Jenkins and Docker are different since both have different installation methods.  Docker
+# places the styles path in '/styles' while Jenkins installs it in 'docs/styles'.  The mustache variable is
+# replaced with the actual value used when you run 'make vale' or 'make tests'.  For more information, see the
+# inner Makefile.
+StylesPath = {{styles_path}}
+Vocab = Vocab
+
+[*.html]
+# Specifies styles that should have all of their rules enabled.
+BasedOnStyles = Microsoft, Google, docs-vale