From 3b52431b486528982559349367f759d5180aecd2 Mon Sep 17 00:00:00 2001 From: Ryan Stewart Date: Wed, 17 Mar 2021 17:11:14 -0500 Subject: [PATCH] fill in build logic for dev This adds commands to actually build and test docs with the dev image. That involves putting a Makefile and a vale configuration where the container can use it, plus adding the proper command support to the scripts. --- internal/main | 31 +++++++++++++++++++++- it/docker-image.bats | 35 ++++++++++++++++++++++++ resources/Makefile | 53 +++++++++++++++++++++++++++++++++++++ resources/vale.ini.template | 32 ++++++++++++++++++++++ 4 files changed, 150 insertions(+), 1 deletion(-) create mode 100644 resources/Makefile create mode 100644 resources/vale.ini.template diff --git a/internal/main b/internal/main index d9efb46..b58969f 100755 --- a/internal/main +++ b/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 < [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 "$@" ;; diff --git a/it/docker-image.bats b/it/docker-image.bats index 0878aee..76535ab 100644 --- a/it/docker-image.bats +++ b/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 +} diff --git a/resources/Makefile b/resources/Makefile new file mode 100644 index 0000000..d8db8cc --- /dev/null +++ b/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 diff --git a/resources/vale.ini.template b/resources/vale.ini.template new file mode 100644 index 0000000..55a9ee4 --- /dev/null +++ b/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