diff --git a/.gitignore b/.gitignore index 9ddd50e5f..c1a8353bc 100644 --- a/.gitignore +++ b/.gitignore @@ -21,9 +21,8 @@ sphinx_rtd_theme/static/fonts/Lato/ sphinx_rtd_theme/static/fonts/RobotoSlab/ .python-version .node-version -.tool-versions -.nvmrc sphinx_rtd_theme/static/js/html5shiv.min.js sphinx_rtd_theme/static/js/html5shiv-printshiv.min.js -.direnv/ -.envrc +.nvmrc + +.container_id diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 000000000..71534a873 --- /dev/null +++ b/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"] diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..35ac01e59 --- /dev/null +++ b/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" . diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh new file mode 100644 index 000000000..24312c395 --- /dev/null +++ b/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 $@ diff --git a/docs/contributing.rst b/docs/contributing.rst index 9eedb03f6..b1ffdbb22 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -6,6 +6,9 @@ This project follows the Read the Docs :doc:`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 =======