Docker configuration for dev environment

Author: benjaoming

.gitignore

@@ -27,3 +27,4 @@ sphinx_rtd_theme/static/js/html5shiv.min.js
 sphinx_rtd_theme/static/js/html5shiv-printshiv.min.js
 .direnv/
 .envrc
+.container_id

Dockerfile

@@ -0,0 +1,52 @@
+# python:3-alpine contains node 18 so has to go first
+# in order to get overwritten
+FROM python:3-alpine
+FROM node:14-alpine
+
+# Do not use --update since that will also fetch the
+# latest node-current package
+# 'make' is needed for building documentation
+RUN apk add npm make py3-pip py3-wheel
+
+# Add an extra verification that we have the right node
+# because the above caused issues
+RUN node -v && node -v | grep -q v14
+
+RUN pip install pip --upgrade
+
+RUN mkdir -p /project/src/ &&\
+    mkdir -p /project/docs/ &&\
+    mkdir -p /project-static-copy
+
+WORKDIR /project
+
+COPY package.json /project/
+
+# COPY package-lock.json /project/
+
+COPY bin/preinstall.js /project/bin/preinstall.js
+
+RUN cd /project
+
+# It matters that the node environment is installed into the same
+# folder, i.e. /project where we will run the environment from
+RUN npm install --package-lock-only &&\
+    npm audit fix &&\
+    npm install
+
+# This is strictly speaking not necessary, just makes
+# running the container faster...
+# Install dependencies, then uninstall project itself
+COPY . /project-static-copy
+RUN cd /project-static-copy &&\
+    pip install ".[dev]" &&\
+    /usr/bin/yes | pip uninstall sphinx_rtd_theme
+
+
+# Copy in stuff we need to run the project
+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,19 @@
+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 -t -i -p 1919:1919 \
+                --network host \
+		--mount type=bind,source="$(CWD)",target=/project-readonly,readonly \
+		--mount type=volume,dst=/project-readonly/sphinx_rtd_theme.egg-info,volume-driver=local \
+		--mount type=bind,source="$(CWD)/src",target=/project/src,readonly  \
+		--mount type=bind,source="$(CWD)/docs",target=/project/docs \
+		sphinx_rtd_theme:latest $(command)
+
+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,11 @@
+#!/bin/sh
+
+# Install the readonly project in editable mode and make sure
+# all dependencies are upgrade. This is mounted in from the
+# outside, but it is on purpose that it is readonly!
+cd /project-readonly
+pip install --upgrade -e ".[dev]"
+
+cd /project
+
+npm run $@

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,39 @@ 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 development
+======================
+
+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
+
+    # Builds an updated version of the docker image
+    $ make docker-images
+
+    # Runs the docker environment and builds the assets. The container exits after completing the build.
+    $ make docker-run command=build
+
+    # Runs the development webserver
+    $ make docker-run command=dev
+
+    # Copies out the assets from the most recent docker-run
+    $ make docker-copy-assets
+
+
+Every time you change the Node or Python requirements, you will need to rebuild images with ``make docker-images``. If you change SASS or JS, you will need to rebuild assets.
+
+If you need a different setup, refer to ``Makefile`` to see the exact method used to invoke the Docker environment.
+
 Testing
 =======