From af77f9f285e1ac0d2141795734493714668368d1 Mon Sep 17 00:00:00 2001
From: Andrew Arnott <andrewarnott@live.com>
Date: Tue, 5 Sep 2023 14:14:57 +0000
Subject: [PATCH] Add devcontainer.json

This ensures that VS Code or GitHub Codespaces can automatically create an environment where `make` can build the rst files.
It also enables the rst preview pane in VS Code or GitHub Codespaces.
---
 .devcontainer/Dockerfile        | 32 ++++++++++++++++++++++++++++++++
 .devcontainer/devcontainer.json |  4 ++++
 README.template                 |  3 +++
 devcontainer.rst                | 20 ++++++++++++++++++++
 4 files changed, 59 insertions(+)
 create mode 100644 .devcontainer/Dockerfile
 create mode 100644 .devcontainer/devcontainer.json
 create mode 100644 devcontainer.rst

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 00000000..21a182a6
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,32 @@
+FROM debian:latest
+
+RUN apt-get update \
+ && apt-get install -y \
+        gawk \
+        perl \
+        sed \
+        git \
+        python3 \
+        python3-pip \
+        pandoc \
+        biber \
+        latexmk \
+        texlive \
+        texlive-science \
+        texlive-fonts-extra \
+        texlive-plain-generic \
+        texlive-bibtex-extra \
+ && apt-get clean
+
+# Install Python packages, after removing a file that breaks pip.
+RUN rm /usr/lib/python3.11/EXTERNALLY-MANAGED
+RUN pip install rst2html5 \
+ && pip install docutils==0.19
+
+RUN apt-get install -y locales \
+ && echo "LC_ALL=en_US.UTF-8" >> /etc/environment \
+ && echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen \
+ && echo "LANG=en_US.UTF-8" > /etc/locale.conf \
+ && locale-gen en_US.UTF-8
+
+ENV PATH=${PATH}:/root/.local/bin
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 00000000..4557f61a
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,4 @@
+{
+    "name": "Dev space",
+    "dockerFile": "Dockerfile"
+}
\ No newline at end of file
diff --git a/README.template b/README.template
index f838ffac..720f9dbb 100644
--- a/README.template
+++ b/README.template
@@ -39,6 +39,9 @@ Use ``make`` to check that you are using correct
 and double-check the generated ``draft-*.html`` file before filing a Pull Request.
 See `here <protocol/README.rst>`__ for the project dependencies.
 
+Consider leveraging `our devcontainer.json <devcontainer.rst>`__ for ease of tool aquisition
+when working in this repo.
+
 NU5 ZIPs
 --------
 
diff --git a/devcontainer.rst b/devcontainer.rst
new file mode 100644
index 00000000..1b363757
--- /dev/null
+++ b/devcontainer.rst
@@ -0,0 +1,20 @@
+# Using dev containers for editing this repo
+
+This repo uses devcontainer.json to ease configuring the tools necessary to run ``make``.
+You can use [Codespaces](https://docs.github.com/en/codespaces/developing-in-codespaces/developing-in-a-codespace)
+to make your contributions and validate your work.
+Or when using VS Code, use the "Dev Containers: Reopen in Container" command to create
+the docker container with the tools.
+
+## VS Code experience
+
+When using VS Code to edit .rst files, the following extensions will add a preview pane,
+and otherwise add tooling for the files you may be editing:
+
+- [Makefile Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.makefile-tools)
+- [reStructuredText](https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext)
+- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+- [reStructuredText Syntax highlighting](https://marketplace.visualstudio.com/items?itemName=trond-snekvik.simple-rst)
+- [Docker](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker)
+
+Note that these extensions are not endorsed nor been vetted by the Zcash Foundation.