Switch to a pip-tools workflow

This is motivated by the issues around pipenv always upgrading
every dependency whenever you touch any dependency.
(See pypa/pipenv#2665 and
pypa/pipenv#2412)

.circleci/config.yml

@@ -8,14 +8,32 @@ jobs:
             - checkout
 
             - restore_cache:
-                key: cache-{{ .Branch }}-{{ checksum "Pipfile.lock" }}
-            - run: pipenv install --deploy --dev
+                key: cache-{{ .Branch }}-{{ checksum "requirements.txt" }}
+            - run:
+                name: Install dependencies
+                command: |
+                  python3 -m venv venv
+                  . venv/bin/activate
+                  pip install -r requirements.txt
             - save_cache:
-                key: cache-{{ .Branch }}-{{ checksum "Pipfile.lock" }}
+                key: cache-{{ .Branch }}-{{ checksum "requirements.txt" }}
                 paths:
                     - "/home/circleci/.local/share/virtualenvs"
-            - run: pipenv run build
-            - run: pipenv run lint-yaml
+            - run:
+                name: Build
+                command: |
+                  . venv/bin/activate
+                  ./scripts/build
+            - run:
+                name: Lint Yaml
+                command: |
+                  . venv/bin/activate
+                  ./scripts/lint-yaml
+            - run:
+                name: Ensure requirements.txt and requirements.in are in sync
+                command: |
+                  . venv/bin/activate
+                  diff -u <(pip-compile --dry-run 2>&1 | grep -v '^Dry-run, so nothing updated\.$') requirements.txt
 
     deploy:
         docker:
@@ -26,10 +44,12 @@ jobs:
                     - "9e:a9:7b:98:8d:0a:69:22:29:eb:34:14:90:73:a2:5a"
             - checkout
             - restore_cache:
-                key: cache-{{ .Branch }}-{{ checksum "Pipfile.lock" }}
+                key: cache-{{ .Branch }}-{{ checksum "requirements.txt" }}
             - deploy:
                 name: Deploy to Github Pages
-                command: ./.circleci/deploy.sh
+                command: |
+                  . venv/bin/activate
+                  ./.circleci/deploy.sh
 
 
 workflows:

.circleci/deploy.sh

@@ -8,4 +8,4 @@ git config --global push.default simple
 git config --global user.email $(git --no-pager show -s --format='%ae' HEAD)
 git config --global user.name $CIRCLE_USERNAME
 
-pipenv run mkdocs gh-deploy --verbose -m "Deploy build $CIRCLE_BUILD_NUM - $CIRCLE_SHA1 [ci skip]"
+mkdocs gh-deploy --verbose -m "Deploy build $CIRCLE_BUILD_NUM - $CIRCLE_SHA1 [ci skip]"

README.md

@@ -10,28 +10,27 @@ Student Robotics Competition Program
 
 - Python (`>=3.5`)
 - `pip`
-- `pipenv` (`pip install pipenv`)
 
 ## Usage
 
 ### Installing dependencies
 
 ```
-pipenv install --dev
+pip install -r requirements.txt
 ```
 
 ### Running development server
 
 ```
-pipenv run serve
+mkdocs serve  # or ./scripts/serve
 ```
 
 This will launch a server on http://localhost:8000. Content in the server will live-reload as changes are made. If large refactors of the site structure are made, it's advisable to stop the server, make the changes, then restart it.
 
 ### Production build
 
 ```
-pipenv run build
+mkdocs build  # or ./scripts/build
 ```
 
 This will build the site once, and place it in `site/` in the root of the project. This may be useful to see which files are rendered, and how exactly to access them.
@@ -41,9 +40,20 @@ This will build the site once, and place it in `site/` in the root of the projec
 There are some rudimentary tests in the project. These are all run by the CI, and must pass before deployment.
 
 ```
-pipenv run lint-yaml  # Checks the yaml content is well formatted
+./scripts/lint-yaml  # Checks the yaml content is well formatted
 ```
 
+## Dependency management
+
+Add any new dependencies to `requirements.in`, then run `pip-compile`.
+
+To update existing dependencies, use `pip-compile --upgrade` for all or
+`pip-compile --upgrade-package <name>` for a specific one.
+
+If upgrading a dependency because this project's requirements have actually
+changed (i.e: we now depend on a feature in a particular version), then instead
+update the entry in `requirements.in` and run `pip-compile` as for a new
+dependency.
 
 ## License
 

requirements.in

@@ -0,0 +1,11 @@
+mkdocs
+mkdocs-material
+pymdown-extensions
+mdx-include
+mkdocs-markdownextradata-plugin
+git+https://github.com/pugong/mkdocs-mermaid-plugin@abf14392b0ed0c7022210b32c4e7c9c3e4c5c68a
+
+# Development tooling
+yamllint
+
+pip-tools

requirements.txt

@@ -0,0 +1,31 @@
+#
+# This file is autogenerated by pip-compile
+# To update, run:
+#
+#    pip-compile
+#
+beautifulsoup4==4.8.0
+click==7.0                # via mkdocs, pip-tools
+cyclic==1.0.0             # via mdx-include
+jinja2==2.10.1            # via mkdocs
+livereload==2.6.0         # via mkdocs
+markdown==3.1             # via mdx-include, mkdocs, pymdown-extensions
+markupsafe==1.1.1         # via jinja2
+mdx-include==1.3.3
+mkdocs-markdownextradata-plugin==0.0.5
+mkdocs-material==4.1.1
+git+https://github.com/pugong/mkdocs-mermaid-plugin@abf14392b0ed0c7022210b32c4e7c9c3e4c5c68a
+mkdocs==1.0.4
+pathspec==0.5.9           # via yamllint
+pip-tools==4.1.0
+pygments==2.3.1           # via mkdocs-material
+pymdown-extensions==6.0
+pyyaml==5.1               # via mkdocs, yamllint
+rcslice==1.1.0            # via mdx-include
+six==1.12.0               # via livereload, pip-tools
+soupsieve==1.9.1          # via beautifulsoup4
+tornado==6.0.2            # via livereload, mkdocs
+yamllint==1.15.0
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools==41.2.0        # via markdown

scripts/build

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+exec mkdocs build

scripts/lint-yaml

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+exec yamllint -sc yamllint.yml yamllint.yml docs/ mkdocs.yml

scripts/serve

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+exec mkdocs serve