Build assets in Docker container + use same container setup in CI

.circleci/config.yml

@@ -17,8 +17,9 @@ commands:
     description: "Ensure built assets are up to date"
     steps:
       - checkout
-      - run: npm ci
-      - run: npm run build
+      - run: make docker-images
+      - run: make docker-run
+      - run: make docker-copy-assets
       - run:
           name: Ensure built assets are up to date
           command: |
@@ -31,8 +32,10 @@ commands:
 
 jobs:
   build:
-    docker:
-      - image: 'cimg/python:3.9-node'
+    machine: # executor type
+      image: ubuntu-2004:202010-01 # # recommended linux image - includes Ubuntu 20.04, docker 19.03.13, docker-compose 1.27.4
+    # docker:
+    #   - image: docker:17.05.0-ce-git
     steps:
       - run-build: {}
   py27:

.gitignore

@@ -24,3 +24,5 @@ sphinx_rtd_theme/static/fonts/RobotoSlab/
 sphinx_rtd_theme/static/js/html5shiv.min.js
 sphinx_rtd_theme/static/js/html5shiv-printshiv.min.js
 .nvmrc
+
+.container_id

Dockerfile

@@ -0,0 +1,27 @@
+FROM node:14-alpine
+FROM python:2-alpine
+
+RUN apk add --update npm
+
+RUN mkdir -p /project/src/
+
+WORKDIR /project
+
+COPY package.json /project/
+
+# COPY package-lock.json /project/
+
+COPY bin/preinstall.js /project/bin/preinstall.js
+
+RUN cd /project
+
+RUN npm install --package-lock-only &&\
+    npm audit fix &&\
+    npm install
+
+COPY webpack.common.js webpack.dev.js webpack.prod.js /project/
+
+COPY docker-entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]

Makefile

@@ -0,0 +1,13 @@
+SHELL := /bin/bash
+CWD := $(shell cd -P -- '$(shell dirname -- "$0")' && pwd -P)
+
+docker-images:
+	docker build -t sphinx_rtd_theme:latest .
+
+docker-run:
+	rm -f .container_id
+	docker run --cidfile=.container_id --mount type=bind,source="$(CWD)/src",target=/project/src,readonly sphinx_rtd_theme:latest
+
+docker-copy-assets:
+	docker cp "$(shell cat .container_id):/project/sphinx_rtd_theme" .
+	docker cp "$(shell cat .container_id):/project/package-lock.json" .

docker-entrypoint.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+
+cd /project
+
+npm run build
+

docs/contributing.rst

@@ -6,6 +6,9 @@ This project follows the Read the Docs :doc:`code of conduct
 <rtd:code-of-conduct>`. If you are not familiar with our code of conduct policy,
 take a minute to read the policy before starting with your first contribution.
 
+.. tip::
+    There is a new dockerized build environment, see :ref:`dockerized-build`.
+
 Modifying the theme
 ===================
 
@@ -62,6 +65,27 @@ can be used to test built assets:
 .. _Wyrm: http://www.github.com/snide/wyrm/
 .. _Sphinx: http://www.sphinx-doc.org/en/stable/
 
+
+_dockerized-build::
+
+Dockerized build
+================
+
+If you have Docker available on your platform, you can get started building CSS and JS artifacts a bit faster and won't have to worry about any of the setup spilling over into your general environment.
+
+When building with Docker, we create an image containing the build dependencies, such as `SASS`_ , `Wyrm` and `Webpack`_ in the anticipated versions. Some of these are quite outdated and therefore ideal to isolate a container. The image is tagged as ``sphinx_rtd_theme:latest``.
+
+Inside the running docker image, we mount the working copy of the repository, build the artifacts and finally copy out those artifacts into your external environment.
+
+Use the following steps:
+
+.. code-block:: console
+
+    $ make docker-images      # Builds an updated version of the docker image
+    $ make docker-run         # Runs the docker environment and builds the assets. The container exits after completing the build.
+    $ make docker-copy-assets # Copies out the assets from the most recent docker-run
+
+
 Testing
 =======