Tooling updates: i18n_tool, update_version, screenshots

- Add docs repo support to i18n_tool.py
- Migrate docs edits out of update_version.sh
- Add support for docs repo to update-user-guides target.
  The script is run inside a container that does not have access
  to the repo checkout, so moved the copy logic into the Makefile.
  Renamed script to accurately reflect its revised purpose.

Makefile

@@ -290,11 +290,15 @@ list-translators:  ## Collect the names of translators since the last merge from
 list-all-translators:  ## Collect the names of all translators in the project's history.
 	@$(DEVSHELL) $(SDROOT)/securedrop/i18n_tool.py list-translators --all
 
-# TODO: test this to make sure the paths in update-user-guides work
 .PHONY: update-user-guides
-update-user-guides:  ## Run the page layout tests to regenerate screenshots.
-	@echo "Running page layout tests to update guide screenshots..."
-	@$(DEVSHELL) $(SDBIN)/update-user-guides
+update-user-guides:  ## Regenerate docs screenshots. Set DOCS_REPO_DIR to repo checkout root.
+ifndef DOCS_REPO_DIR
+	$(error DOCS_REPO_DIR must be set to the documentation repo checkout root.)
+endif
+	@echo "Running page layout tests to update screenshots used in user guide..."
+	@$(DEVSHELL) $(SDBIN)/generate-docs-screenshots
+	@echo "Copying screenshots..."
+	cp securedrop/tests/pageslayout/screenshots/en_US/*.png $${DOCS_REPO_DIR}/docs/images/manual/screenshots
 	@echo
 
 

securedrop/bin/update-user-guides → securedrop/bin/generate-docs-screenshots

@@ -15,4 +15,3 @@ maybe_create_config_py
 
 ./i18n_tool.py translate-messages --compile
 pytest -v --page-layout "${@:-tests/pageslayout}"
-cp tests/pageslayout/screenshots/en_US/*.png ../docs/images/manual/screenshots

securedrop/i18n_tool.py

@@ -14,7 +14,7 @@
 import textwrap
 import version
 
-from os.path import dirname, join, realpath
+from os.path import abspath, dirname, join, realpath
 
 from sh import git, pybabel, sed, msgmerge, xgettext, msgfmt
 
@@ -215,7 +215,7 @@ def update_docs(self, args):
         l10n_content = u'.. GENERATED BY i18n_tool.py DO NOT EDIT:\n\n'
         for (code, info) in sorted(I18NTool.SUPPORTED_LANGUAGES.items()):
             l10n_content += '* ' + info['name'] + ' (``' + code + '``)\n'
-        includes = join(args.documentation_dir, 'includes')
+        includes = abspath(join(args.docs_repo_dir, 'docs/includes'))
         l10n_txt = join(includes, 'l10n.txt')
         io.open(l10n_txt, mode='w').write(l10n_content)
         self.require_git_email_name(includes)
@@ -233,12 +233,10 @@ def update_docs(self, args):
     def set_update_docs_parser(self, subps):
         parser = subps.add_parser('update-docs',
                                   help=('Update the documentation'))
-        documentation_dir = join(dirname(realpath(__file__)), '..', 'docs')
         parser.add_argument(
-            '--documentation-dir',
-            default=documentation_dir,
-            help=('root directory of the SecureDrop documentation'
-                  ' (default {})'.format(documentation_dir)))
+            '--docs-repo-dir',
+            required=True,
+            help=('root directory of the SecureDrop documentation repository'))
         parser.set_defaults(func=self.update_docs)
 
     def update_from_weblate(self, args):

securedrop/tests/test_i18n_tool.py

@@ -229,21 +229,21 @@ def test_update_docs(self, tmpdir, caplog):
         git.init(**k)
         git.config('user.email', "you@example.com", **k)
         git.config('user.name', "Your Name", **k)
-        os.mkdir(join(str(tmpdir), 'includes'))
-        touch('includes/l10n.txt', **k)
-        git.add('includes/l10n.txt', **k)
+        os.makedirs(join(str(tmpdir), 'docs/includes'))
+        touch('docs/includes/l10n.txt', **k)
+        git.add('docs/includes/l10n.txt', **k)
         git.commit('-m', 'init', **k)
 
         i18n_tool.I18NTool().main([
             '--verbose',
             'update-docs',
-            '--documentation-dir', str(tmpdir)])
+            '--docs-repo-dir', str(tmpdir)])
         assert 'l10n.txt updated' in caplog.text
         caplog.clear()
         i18n_tool.I18NTool().main([
             '--verbose',
             'update-docs',
-            '--documentation-dir', str(tmpdir)])
+            '--docs-repo-dir', str(tmpdir)])
         assert 'l10n.txt already up to date' in caplog.text
 
     def test_update_from_weblate(self, tmpdir, caplog):

update_version.sh

@@ -62,17 +62,10 @@ sed -i "s/^\(securedrop_app_code_sdist_version: \"securedrop-app-code-\).*/\1${N
 # Update the version in molecule testinfra vars
 sed -i "s@$(echo "${OLD_VERSION}" | sed 's/\./\\./g')@$NEW_VERSION@g" molecule/builder-xenial/tests/vars.yml
 
-# If version doesnt have an rc designator, its considered stable
-# theres a few things that peg to that stable version like upgrade testing logic
-# and strings inside the documentation
-OLD_RELEASE=$(cat molecule/shared/stable.ver)
+# If version doesn't have an rc designator, it's considered stable.
+# The upgrade testing logic relies on this variable.
 if [[ ! $NEW_VERSION == *~rc* ]]; then
     echo "${NEW_VERSION}" > molecule/shared/stable.ver
-    sed -i "s@$(echo "${OLD_RELEASE}" | sed 's/\./\\./g')@$NEW_VERSION@g" docs/set_up_admin_tails.rst
-    sed -i "s@$(echo "${OLD_RELEASE}" | sed 's/\./\\./g')@$NEW_VERSION@g" docs/conf.py
-    # Upgrade docs to Ubuntu 16.04 reference current stable version explicitly.
-    # Where we're talking about the 0.12 _series_ (the first to support Xenial),
-    # the phrase "0.12 series" is used, so this regex is safe to run.
 fi
 
 # Update the changelog