Switch to poetry for dependency management

.circleci/config.yml

@@ -5,9 +5,9 @@ common-steps:
     run:
       name: Install system-level and Python dependencies
       command: |
-        apt-get update && apt-get install -y --no-install-recommends make python3 python3-venv python3-setuptools
-        python3 -m venv .venv
-        ./.venv/bin/pip install --require-hashes -r requirements/requirements.txt
+        apt-get update && apt-get install -y --no-install-recommends make python3 python3-pip
+        pip install poetry==1.3.2
+        poetry install --no-ansi
 
 jobs:
   lint:
@@ -21,7 +21,6 @@ jobs:
       - run:
           name: Run lint
           command: |
-            source .venv/bin/activate
             make docs-lint
 
   linkcheck:
@@ -33,7 +32,6 @@ jobs:
       - run:
           name: Run link check
           command: |
-            source .venv/bin/activate
             make docs-linkcheck
 
   build:

.gitignore

@@ -1,3 +1,4 @@
+.vscode
 docs/_build/*
 docs/_templates/*
 docs/_static/*

Makefile

@@ -1,23 +1,25 @@
+# All targets are run under poetry, so the activation of the virtual environment
+# is not necessary.
 .PHONY: docs
 docs:  ## Build project documentation with live reload for editing.
 	@echo "███ Building docs and watching for changes..."
-	make clean && sphinx-autobuild docs docs/_build/html
+	@poetry run make clean && poetry run sphinx-autobuild docs docs/_build/html
 	@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 clean && sphinx-build -Wn docs docs/_build/html
+	@make clean && poetry run sphinx-build -Wn docs docs/_build/html
 	@echo
 
 .PHONY: docs-linkcheck
 docs-linkcheck:  ## Check documentation for broken links.
-	@make clean && sphinx-build -b linkcheck -Wn docs docs/_build/html
+	@make clean && poetry run sphinx-build -b linkcheck -Wn docs docs/_build/html
 	@echo
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %:
-	@sphinx-build -M $@ docs docs/_build
+	@poetry run sphinx-build -M $@ docs docs/_build

README.md

@@ -5,3 +5,9 @@
 # SecureDrop Redmine Support Documentation
 
 This repository holds the [documentation](https://support-docs.securedrop.org/) for SecureDrop's [Redmine-based support system](https://support.freedom.press). The support system is also available as a Tor Onion Service (http://sup6h5iyiyenvjkfxbgrjynm5wsgijjoatvnvdgyyi7je3xqm4kh6uqd.onion/).
+
+# Local installation (Python 3.9)
+
+1. [Install poetry](https://python-poetry.org/docs/#installation)
+2. Install the dependencies using `poetry install`
+3. Run `make docs` to preview the documentation.

deploy/Dockerfile

@@ -1,15 +1,16 @@
-# sha256 as of 2021-11-09
-FROM python:3.9-slim-bullseye@sha256:408de0cf1a057f5501ee6642ad24a4762738f63bacf09fb4c8d861669260b01e AS sphinx
+# sha256 as of 2023-01-17
+FROM python:3.9-slim-bullseye@sha256:8b0502fe3a8ae9d26567f66e217223595ff6abe901cba64fd8b1b58176311b27 AS sphinx
 
 ARG GIT_BRANCH=main
 RUN apt-get -q update && apt-get -qy upgrade && apt-get -qy install git make latexmk texlive-latex-extra
 COPY ./ .
-RUN pip install -r requirements/requirements.txt
+RUN pip install poetry==1.3.2
+RUN poetry install
 RUN deploy/build $GIT_BRANCH
 
-# sha256 as of 2021-11-09
-FROM nginx:mainline-alpine@sha256:af466e4f12e3abe41fcfb59ca0573a3a5c640573b389d5287207a49d1324abd8
+# sha256 as of 2023-01-09
 
+FROM nginx:mainline-alpine@sha256:c1b9fe3c0c015486cf1e4a0ecabe78d05864475e279638e9713eb55f013f907f
 COPY deploy/nginx.conf /etc/nginx
 RUN mkdir -p /opt/nginx/run /opt/nginx/webroot/en/latest && chown -R nginx:nginx /opt/nginx
 

docs/conf.py

@@ -70,7 +70,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

pyproject.toml

@@ -0,0 +1,14 @@
+[tool.poetry]
+name = "redmine-docs"
+version = "0.1.0"
+description = ""
+authors = ["SecureDrop team <[email protected]>"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.9"
+# The RTD theme does not yet support Sphinx >=6.0.0.
+# See https://github.com/readthedocs/sphinx_rtd_theme/issues/1323
+sphinx = "<6.0.0"
+sphinx-autobuild = "^2021.3.14"
+sphinx-rtd-theme = "^1.1.1"