Merge pull request #5520 from freedomofpress/5435-docs-migration

Remove docs, update CI config & tooling

.circleci/config.yml

@@ -74,7 +74,7 @@ jobs:
           name: Run all linters but shellcheck
           command: |
             fromtag=$(docker images |grep securedrop-test-xenial-py3 |head -n1 |awk '{print $2}')
-            DOCKER_BUILD_ARGUMENTS="--cache-from securedrop-test-xenial-py3:${fromtag:-latest}" securedrop/bin/dev-shell bash -c "/opt/venvs/securedrop-app-code/bin/pip3 install --require-hashes -r requirements/python3/develop-requirements.txt && make -C .. ansible-config-lint app-lint flake8 html-lint typelint yamllint docs-lint"
+            DOCKER_BUILD_ARGUMENTS="--cache-from securedrop-test-xenial-py3:${fromtag:-latest}" securedrop/bin/dev-shell bash -c "/opt/venvs/securedrop-app-code/bin/pip3 install --require-hashes -r requirements/python3/develop-requirements.txt && make -C .. ansible-config-lint app-lint flake8 html-lint typelint yamllint"
 
       - run:
           name: Run shellcheck
@@ -100,7 +100,7 @@ jobs:
       - run:
           name: Run tests
           command: |
-            BRANCH_MATCH=$(devops/scripts/match-ci-branch.sh "^(i18n|docs|update-builder)")
+            BRANCH_MATCH=$(devops/scripts/match-ci-branch.sh "^(i18n|update-builder)")
             if [[ $BRANCH_MATCH =~ ^found ]]; then echo "Skipping: ${BRANCH_MATCH}"; exit 0; fi
             export TESTFILES=$(cd securedrop; circleci tests glob 'tests/test*py' 'tests/**/test*py' |circleci tests split --split-by=timings |xargs echo)
             fromtag=$(docker images |grep securedrop-test-xenial-py3 |head -n1 |awk '{print $2}')
@@ -157,7 +157,7 @@ jobs:
       - run:
           name: Run tests
           command: |
-            BRANCH_MATCH=$(devops/scripts/match-ci-branch.sh "^(i18n|docs|update-builder)")
+            BRANCH_MATCH=$(devops/scripts/match-ci-branch.sh "^(i18n|update-builder)")
             if [[ $BRANCH_MATCH =~ ^found ]]; then echo "Skipping: ${BRANCH_MATCH}"; exit 0; fi
             cd admin; make test
 
@@ -171,7 +171,7 @@ jobs:
       - run:
           name: Fetch Tor packages
           command: |
-            BRANCH_MATCH=$(devops/scripts/match-ci-branch.sh "^(i18n|docs|update-builder)")
+            BRANCH_MATCH=$(devops/scripts/match-ci-branch.sh "^(i18n|update-builder)")
             if [[ $BRANCH_MATCH =~ ^found ]]; then echo "Skipping: ${BRANCH_MATCH}"; exit 0; fi
             export LC_ALL="C.UTF-8"
             make fetch-tor-packages
@@ -195,7 +195,7 @@ jobs:
       - run:
           name: Run tests
           command: |
-            BRANCH_MATCH=$(devops/scripts/match-ci-branch.sh "^(i18n|docs|update-builder)")
+            BRANCH_MATCH=$(devops/scripts/match-ci-branch.sh "^(i18n|update-builder)")
             if [[ $BRANCH_MATCH =~ ^found ]]; then echo "Skipping: ${BRANCH_MATCH}"; exit 0; fi
             cd journalist_gui
             xvfb-run -a pipenv run python3 test_gui.py
@@ -242,7 +242,7 @@ jobs:
       - run:
           name: Run Staging tests on GCE
           command: |
-            BRANCH_MATCH=$(devops/scripts/match-ci-branch.sh "^(i18n|docs)")
+            BRANCH_MATCH=$(devops/scripts/match-ci-branch.sh "^(i18n)")
             if [[ $BRANCH_MATCH =~ ^found ]]; then echo "Skipping: ${BRANCH_MATCH}"; exit 0; fi
             make ci-go
           no_output_timeout: 35m
@@ -292,22 +292,6 @@ jobs:
           command: |
             make ci-deb-tests-focal
 
-  docs-linkcheck:
-    docker:
-      - image: circleci/python:3.5
-    steps:
-      - checkout
-      - *rebaseontarget
-      - *installenchant
-
-      - run:
-          name: Install development dependencies
-          command: sudo pip3 install -U -r securedrop/requirements/python3/develop-requirements.txt
-
-      - run:
-          name: Run documentation linkcheck
-          command: make docs-linkcheck
-
 workflows:
   version: 2
   securedrop_ci:
@@ -317,8 +301,6 @@ workflows:
           filters:
             branches:
               ignore:
-                - stable
-                - /docs-.*/
                 - /i18n-.*/
                 - /update-builder-.*/
           requires:
@@ -327,8 +309,6 @@ workflows:
           filters:
             branches:
               ignore:
-                - stable
-                - /docs-.*/
                 - /i18n-.*/
                 - /update-builder-.*/
           requires:
@@ -337,33 +317,21 @@ workflows:
           filters:
             branches:
               ignore:
-                - stable
-                - /docs-.*/
                 - /i18n-.*/
                 - /update-builder-.*/
           requires:
             - lint
       - static-analysis-and-no-known-cves:
-          filters:
-            branches:
-              ignore:
-                - stable
           requires:
             - lint
       - staging-test-with-rebase:
           filters:
             branches:
               ignore:
-                - stable
-                - /docs-.*/
                 - /i18n-.*/
           requires:
             - lint
       - translation-tests:
-          filters:
-            branches:
-              ignore:
-                - stable
           requires:
             - lint
       - deb-tests:
@@ -377,8 +345,6 @@ workflows:
           filters:
             branches:
               ignore:
-                - stable
-                - /docs-.*/
                 - /i18n-.*/
           requires:
             - lint
@@ -406,5 +372,4 @@ workflows:
       - deb-tests
       - deb-tests-focal
       - translation-tests
-      - docs-linkcheck
       - fetch-tor-debs

Makefile

@@ -81,18 +81,6 @@ app-lint-full: ## Test pylint compliance, with no checks disabled.
 	@cd securedrop && find . -name '*.py' | xargs pylint
 	@echo
 
-.PHONY: docs-lint
-docs-lint:  ## Check documentation for common syntax errors.
-	@echo "███ Linting documentation..."
-# The `-W` option converts warnings to errors.
-# The `-n` option enables "nit-picky" mode.
-	@make -C docs/ clean && sphinx-build -Wn docs/ docs/_build/html
-	@echo
-
-.PHONY: docs-linkcheck
-docs-linkcheck:  ## Check documentation for broken links.
-	@make -C docs/ clean && sphinx-build -b linkcheck -Wn docs/ docs/_build/html
-
 .PHONY: flake8
 flake8:  ## Validate PEP8 compliance for Python source files.
 	@echo "███ Running flake8..."
@@ -132,7 +120,7 @@ yamllint:  ## Lint YAML files (does not validate syntax!).
 	@echo
 
 .PHONY: lint
-lint: ansible-config-lint app-lint docs-lint flake8 html-lint shellcheck typelint yamllint ## Runs all lint checks
+lint: ansible-config-lint app-lint flake8 html-lint shellcheck typelint yamllint ## Runs all lint checks
 
 .PHONY: safety
 safety:  ## Run `safety check` to check python dependencies for vulnerabilities.
@@ -188,12 +176,6 @@ dev:  ## Run the development server in a Docker container.
 	@OFFSET_PORTS='false' DOCKER_BUILD_VERBOSE='true' $(DEVSHELL) $(SDBIN)/run
 	@echo
 
-.PHONY: docs
-docs:  ## Build project documentation with live reload for editing.
-	@echo "███ Building docs and watching for changes..."
-	make -C docs/ clean && sphinx-autobuild docs/ docs/_build/html
-	@echo
-
 .PHONY: staging
 staging:  ## Create a local staging environment in virtual machines (Xenial)
 	@echo "███ Creating staging environment on Ubuntu Xenial..."
@@ -308,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
 
 

README.md

@@ -13,9 +13,9 @@ SecureDrop is an open-source whistleblower submission system that media organiza
 
 ## Documentation
 
-SecureDrop's documentation is built and hosted by [Read the Docs](https://readthedocs.org) at https://docs.securedrop.org.
+SecureDrop's documentation is built and hosted by [Read the Docs](https://readthedocs.org) at https://docs.securedrop.org. It is maintained in a standalone repository: https://github.com/freedomofpress/securedrop-docs
 
-There are multiple versions of the [SecureDrop documentation](https://docs.securedrop.org). By default, the documentation describes the most recent SecureDrop release. It is the best version of the documentation for end users (Sources, Journalists, or Administrators). The **latest** documentation is automatically built from the most recent commit to the SecureDrop development branch. It is most useful for developers and contributors to the project. You can switch between versions of the documentation by using the toolbar in the bottom left corner of the Read the Docs screen.
+By default, the documentation describes the most recent SecureDrop release. This is known as the **stable** version and is recommended for end users (Sources, Journalists, or Administrators). The **latest** documentation is automatically built from the most recent commit to the SecureDrop documentation repository. It is most useful for developers and contributors to the project. You can switch between versions of the documentation by using the toolbar in the bottom left corner of the Read the Docs screen.
 
 ## Found an issue?