Merge pull request #1319 from benjaoming/dockerize

Supplemental development process for Docker

Author: benjaoming

.gitignore

@@ -27,3 +27,5 @@ sphinx_rtd_theme/static/js/html5shiv.min.js
 sphinx_rtd_theme/static/js/html5shiv-printshiv.min.js
 .direnv/
 .envrc
+# Used for dockerized builds
+.container_id

Dockerfile

@@ -0,0 +1,58 @@
+# This implicitely includes Python 3.10
+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 &&\
+    python3 --version && python3 --version | grep -q "3.10"
+
+RUN pip install pip --upgrade
+
+RUN mkdir -p /project/src/ &&\
+    mkdir -p /project/docs/build/ &&\
+    mkdir -p /project-minimal-copy/sphinx_rtd_theme &&\
+    touch /project-minimal-copy/sphinx_rtd_theme/__init__.py
+
+# This is the main working directory where node_modules
+# gets built. During runtime, it's mixed with directories
+# from an external environment through a bind mount
+WORKDIR /project
+
+# Copy files necessary to run "npm install" and save
+# installed packages in the docker image (makes the runtime
+# so much faster)
+COPY package.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 setup.py README.rst /project-minimal-copy/
+RUN cd /project-minimal-copy &&\
+    pip install ".[dev]" &&\
+    /usr/bin/yes | pip uninstall sphinx_rtd_theme
+
+
+# Copy in files that we need to run the project. These files
+# will not be mounted into the runtime from external environment
+# so we copy them during build.
+COPY webpack.common.js webpack.dev.js webpack.prod.js /project/
+
+# Copy in the entrypoint and we're done
+COPY docker-entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]

Makefile

@@ -0,0 +1,18 @@
+SHELL := /bin/bash
+CWD := $(shell cd -P -- '$(shell dirname -- "$0")' && pwd -P)
+
+docker-images:
+	docker-compose build
+
+docker-npm-build:
+	rm -f .container_id
+	docker-compose run -d sphinx_rtd_theme build > .container_id
+	docker container wait "$(shell cat .container_id)"
+	docker cp "$(shell cat .container_id):/project/sphinx_rtd_theme" .
+	docker cp "$(shell cat .container_id):/project/package-lock.json" .
+	@echo "Done building"
+
+docker-npm-dev:
+	docker-compose run sphinx_rtd_theme dev
+	
+docker-build-all: docker-images docker-npm-build

docker-compose.yaml

@@ -0,0 +1,26 @@
+version: "3.2"
+services:
+
+  sphinx_rtd_theme:
+    build: .
+    volumes:
+      - type: "bind"
+        source: "./"
+        target: "/project-readonly"
+        read_only: true
+      - type: "volume"
+        target: "/project-readonly/sphinx_rtd_theme.egg-info"
+      - type: "bind"
+        source: "./src"
+        target: "/project/src"
+        read_only: true
+      - type: "bind"
+        source: "./docs"
+        target: "/project/docs"
+        read_only: false #todo: fix this
+      - type: "volume"
+        target: "/project/docs/_build"
+
+    network_mode: host
+    ports:
+      - "1919:1919"

docker-entrypoint.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+
+# Update latest Python dependencies in case they have changed
+cd /project-readonly
+pip install --upgrade -e ".[dev]"
+
+# This helps a potential permission issue, but might be removed
+# pending some more investigation of docker host file system
+# permissions in the bind mount
+# npm cache clean --force
+# npm install
+
+cd /project
+cp -r /project-readonly/sphinx_rtd_theme .
+
+echo "Going to invoke: npm run $@"
+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,36 @@ 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. 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 observe that the artifacts have been built and left in your current git checkout.
+
+Use the following steps:
+
+.. code-block:: console
+
+    # Builds an updated version of the docker image
+    $ docker-compose build
+
+    # Runs the development webserver
+    $ docker-compose run sphinx_rtd_theme dev
+    
+    # If you want to copy stuff out of the Docker environment, run this make
+    # target or read the actual Makefile to see what is going on.
+    # We suggest running this command every time that you want to quickly build
+    # new CSS/JS assets
+    $ make docker-build-all
+
+Every time you change the Node or Python requirements, you will need to rebuild images with ``docker-compose run sphinx_rtd_theme build``. If you change SASS or JS, you will need to rebuild assets.
+
 Testing
 =======