From 31e07b787523cfdc92701cd8d565d4dcc304b874 Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 31 Aug 2019 17:34:00 +0100 Subject: [PATCH 1/4] Ensure we're on Python 3 for the deploy too --- .circleci/config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 16c5caea..93f21aa1 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -19,7 +19,7 @@ jobs: deploy: docker: - - image: circleci/python + - image: circleci/python:3 steps: - add_ssh_keys: fingerprints: From b85f214be6bdffdf16c0207dee775271ac1ec7ee Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 31 Aug 2019 17:40:22 +0100 Subject: [PATCH 2/4] Switch to a pip-tools workflow This is motivated by the issues around pipenv always upgrading every dependency whenever you touch any dependency. (See https://github.com/pypa/pipenv/issues/2665 and https://github.com/pypa/pipenv/issues/2412) --- .circleci/config.yml | 34 ++++++-- .circleci/deploy.sh | 2 +- Pipfile | 23 ----- Pipfile.lock | 195 ------------------------------------------- README.md | 20 +++-- requirements.in | 11 +++ requirements.txt | 31 +++++++ scripts/build | 3 + scripts/lint-yaml | 3 + scripts/serve | 3 + 10 files changed, 94 insertions(+), 231 deletions(-) delete mode 100644 Pipfile delete mode 100644 Pipfile.lock create mode 100644 requirements.in create mode 100644 requirements.txt create mode 100755 scripts/build create mode 100755 scripts/lint-yaml create mode 100755 scripts/serve diff --git a/.circleci/config.yml b/.circleci/config.yml index 93f21aa1..c7b6910b 100644 --- a/.circleci/config.yml +++ b/.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: diff --git a/.circleci/deploy.sh b/.circleci/deploy.sh index 46d6cfce..92feb72a 100755 --- a/.circleci/deploy.sh +++ b/.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]" diff --git a/Pipfile b/Pipfile deleted file mode 100644 index 440626cd..00000000 --- a/Pipfile +++ /dev/null @@ -1,23 +0,0 @@ -[[source]] -name = "pypi" -url = "https://pypi.org/simple" -verify_ssl = true - -[dev-packages] - -[packages] -mkdocs = "*" -mkdocs-material = "*" -pymdown-extensions = "*" -mdx-include = "*" -yamllint = "*" -mkdocs-markdownextradata-plugin = "*" -mkdocs-mermaid-plugin = {git = "https://github.com/pugong/mkdocs-mermaid-plugin"} - -[requires] -python_version = "3" - -[scripts] -serve = "mkdocs serve" -build = "mkdocs build" -lint-yaml = "yamllint -sc yamllint.yml yamllint.yml docs/ mkdocs.yml" diff --git a/Pipfile.lock b/Pipfile.lock deleted file mode 100644 index f0bc6d38..00000000 --- a/Pipfile.lock +++ /dev/null @@ -1,195 +0,0 @@ -{ - "_meta": { - "hash": { - "sha256": "c8df5d37ada15278160cb80c3a69178d0efdcbd22dc02bf64c221fd009cc3566" - }, - "pipfile-spec": 6, - "requires": { - "python_version": "3" - }, - "sources": [ - { - "name": "pypi", - "url": "https://pypi.org/simple", - "verify_ssl": true - } - ] - }, - "default": { - "click": { - "hashes": [ - "sha256:2335065e6395b9e67ca716de5f7526736bfa6ceead690adf616d925bdc622b13", - "sha256:5b94b49521f6456670fdb30cd82a4eca9412788a93fa6dd6df72c94d5a8ff2d7" - ], - "version": "==7.0" - }, - "cyclic": { - "hashes": [ - "sha256:32d8181d7698f426bce6f14f4c3921ef95b6a84af9f96192b59beb05bc00c3ed", - "sha256:ecddd56cb831ee3e6b79f61ecb0ad71caee606c507136867782911aa01c3e5eb" - ], - "version": "==1.0.0" - }, - "jinja2": { - "hashes": [ - "sha256:065c4f02ebe7f7cf559e49ee5a95fb800a9e4528727aec6f24402a5374c65013", - "sha256:14dd6caf1527abb21f08f86c784eac40853ba93edb79552aa1e4b8aef1b61c7b" - ], - "version": "==2.10.1" - }, - "livereload": { - "hashes": [ - "sha256:29cadfabcedd12eed792e0131991235b9d4764d4474bed75cf525f57109ec0a2", - "sha256:e632a6cd1d349155c1d7f13a65be873b38f43ef02961804a1bba8d817fa649a7" - ], - "version": "==2.6.0" - }, - "markdown": { - "hashes": [ - "sha256:fc4a6f69a656b8d858d7503bda633f4dd63c2d70cf80abdc6eafa64c4ae8c250", - "sha256:fe463ff51e679377e3624984c829022e2cfb3be5518726b06f608a07a3aad680" - ], - "version": "==3.1" - }, - "markupsafe": { - "hashes": [ - "sha256:00bc623926325b26bb9605ae9eae8a215691f33cae5df11ca5424f06f2d1f473", - "sha256:09027a7803a62ca78792ad89403b1b7a73a01c8cb65909cd876f7fcebd79b161", - "sha256:09c4b7f37d6c648cb13f9230d847adf22f8171b1ccc4d5682398e77f40309235", - "sha256:1027c282dad077d0bae18be6794e6b6b8c91d58ed8a8d89a89d59693b9131db5", - "sha256:24982cc2533820871eba85ba648cd53d8623687ff11cbb805be4ff7b4c971aff", - "sha256:29872e92839765e546828bb7754a68c418d927cd064fd4708fab9fe9c8bb116b", - "sha256:43a55c2930bbc139570ac2452adf3d70cdbb3cfe5912c71cdce1c2c6bbd9c5d1", - "sha256:46c99d2de99945ec5cb54f23c8cd5689f6d7177305ebff350a58ce5f8de1669e", - "sha256:500d4957e52ddc3351cabf489e79c91c17f6e0899158447047588650b5e69183", - "sha256:535f6fc4d397c1563d08b88e485c3496cf5784e927af890fb3c3aac7f933ec66", - "sha256:62fe6c95e3ec8a7fad637b7f3d372c15ec1caa01ab47926cfdf7a75b40e0eac1", - "sha256:6dd73240d2af64df90aa7c4e7481e23825ea70af4b4922f8ede5b9e35f78a3b1", - "sha256:717ba8fe3ae9cc0006d7c451f0bb265ee07739daf76355d06366154ee68d221e", - "sha256:79855e1c5b8da654cf486b830bd42c06e8780cea587384cf6545b7d9ac013a0b", - "sha256:7c1699dfe0cf8ff607dbdcc1e9b9af1755371f92a68f706051cc8c37d447c905", - "sha256:88e5fcfb52ee7b911e8bb6d6aa2fd21fbecc674eadd44118a9cc3863f938e735", - "sha256:8defac2f2ccd6805ebf65f5eeb132adcf2ab57aa11fdf4c0dd5169a004710e7d", - "sha256:98c7086708b163d425c67c7a91bad6e466bb99d797aa64f965e9d25c12111a5e", - "sha256:9add70b36c5666a2ed02b43b335fe19002ee5235efd4b8a89bfcf9005bebac0d", - "sha256:9bf40443012702a1d2070043cb6291650a0841ece432556f784f004937f0f32c", - "sha256:ade5e387d2ad0d7ebf59146cc00c8044acbd863725f887353a10df825fc8ae21", - "sha256:b00c1de48212e4cc9603895652c5c410df699856a2853135b3967591e4beebc2", - "sha256:b1282f8c00509d99fef04d8ba936b156d419be841854fe901d8ae224c59f0be5", - "sha256:b2051432115498d3562c084a49bba65d97cf251f5a331c64a12ee7e04dacc51b", - "sha256:ba59edeaa2fc6114428f1637ffff42da1e311e29382d81b339c1817d37ec93c6", - "sha256:c8716a48d94b06bb3b2524c2b77e055fb313aeb4ea620c8dd03a105574ba704f", - "sha256:cd5df75523866410809ca100dc9681e301e3c27567cf498077e8551b6d20e42f", - "sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7" - ], - "version": "==1.1.1" - }, - "mdx-include": { - "hashes": [ - "sha256:25be36d39ef861831f53a310d99fe40461632cad3cba738c66dd3c1aa8ad36a1", - "sha256:a6c27011c57947d2fd1367e12559a6d2213329790d3be9e251fe2fc6b6ae9d99" - ], - "index": "pypi", - "version": "==1.3.3" - }, - "mkdocs": { - "hashes": [ - "sha256:17d34329aad75d5de604b9ed4e31df3a4d235afefdc46ce7b1964fddb2e1e939", - "sha256:8cc8b38325456b9e942c981a209eaeb1e9f3f77b493ad755bfef889b9c8d356a" - ], - "index": "pypi", - "version": "==1.0.4" - }, - "mkdocs-markdownextradata-plugin": { - "hashes": [ - "sha256:64d1c966b288d653f51f7531c03204eb988d0d77e56055c9d703d99105259a36" - ], - "index": "pypi", - "version": "==0.0.5" - }, - "mkdocs-material": { - "hashes": [ - "sha256:8f0a5217c24bd8635c0bda2a0ee4f91766448e9e3dd6429f1111dd992327345e", - "sha256:c2c6ef6b3e3ab4744a45d03a276e1eb106c91abf610d180d148613fd1a525c7c" - ], - "index": "pypi", - "version": "==4.1.1" - }, - "mkdocs-mermaid-plugin": { - "git": "https://github.com/pugong/mkdocs-mermaid-plugin", - "ref": "abf14392b0ed0c7022210b32c4e7c9c3e4c5c68a" - }, - "pathspec": { - "hashes": [ - "sha256:54a5eab895d89f342b52ba2bffe70930ef9f8d96e398cccf530d21fa0516a873" - ], - "version": "==0.5.9" - }, - "pygments": { - "hashes": [ - "sha256:5ffada19f6203563680669ee7f53b64dabbeb100eb51b61996085e99c03b284a", - "sha256:e8218dd399a61674745138520d0d4cf2621d7e032439341bc3f647bff125818d" - ], - "version": "==2.3.1" - }, - "pymdown-extensions": { - "hashes": [ - "sha256:25b0a7967fa697b5035e23340a48594e3e93acb10b06d74574218ace3347d1df", - "sha256:6cf0cf36b5a03b291ace22dc2f320f4789ce56fbdb6635a3be5fadbf5d7694dd" - ], - "index": "pypi", - "version": "==6.0" - }, - "pyyaml": { - "hashes": [ - "sha256:1adecc22f88d38052fb787d959f003811ca858b799590a5eaa70e63dca50308c", - "sha256:436bc774ecf7c103814098159fbb84c2715d25980175292c648f2da143909f95", - "sha256:460a5a4248763f6f37ea225d19d5c205677d8d525f6a83357ca622ed541830c2", - "sha256:5a22a9c84653debfbf198d02fe592c176ea548cccce47553f35f466e15cf2fd4", - "sha256:7a5d3f26b89d688db27822343dfa25c599627bc92093e788956372285c6298ad", - "sha256:9372b04a02080752d9e6f990179a4ab840227c6e2ce15b95e1278456664cf2ba", - "sha256:a5dcbebee834eaddf3fa7366316b880ff4062e4bcc9787b78c7fbb4a26ff2dd1", - "sha256:aee5bab92a176e7cd034e57f46e9df9a9862a71f8f37cad167c6fc74c65f5b4e", - "sha256:c51f642898c0bacd335fc119da60baae0824f2cde95b0330b56c0553439f0673", - "sha256:c68ea4d3ba1705da1e0d85da6684ac657912679a649e8868bd850d2c299cce13", - "sha256:e23d0cc5299223dcc37885dae624f382297717e459ea24053709675a976a3e19" - ], - "version": "==5.1" - }, - "rcslice": { - "hashes": [ - "sha256:1b12fc0c0ca452e8a9fd2b56ac008162f19e250906a4290a7e7a98be3200c2a6", - "sha256:a2ce70a60690eb63e52b722e046b334c3aaec5e900b28578f529878782ee5c6e" - ], - "version": "==1.1.0" - }, - "six": { - "hashes": [ - "sha256:3350809f0555b11f552448330d0b52d5f24c91a322ea4a15ef22629740f3761c", - "sha256:d16a0141ec1a18405cd4ce8b4613101da75da0e9a7aec5bdd4fa804d0e0eba73" - ], - "version": "==1.12.0" - }, - "tornado": { - "hashes": [ - "sha256:1174dcb84d08887b55defb2cda1986faeeea715fff189ef3dc44cce99f5fca6b", - "sha256:2613fab506bd2aedb3722c8c64c17f8f74f4070afed6eea17f20b2115e445aec", - "sha256:44b82bc1146a24e5b9853d04c142576b4e8fa7a92f2e30bc364a85d1f75c4de2", - "sha256:457fcbee4df737d2defc181b9073758d73f54a6cfc1f280533ff48831b39f4a8", - "sha256:49603e1a6e24104961497ad0c07c799aec1caac7400a6762b687e74c8206677d", - "sha256:8c2f40b99a8153893793559919a355d7b74649a11e59f411b0b0a1793e160bc0", - "sha256:e1d897889c3b5a829426b7d52828fb37b28bc181cd598624e65c8be40ee3f7fa" - ], - "version": "==6.0.2" - }, - "yamllint": { - "hashes": [ - "sha256:5a53b6ebea563f944420d2964233173532af00a9579ab2c48c4cf8c56b704050", - "sha256:8f25759997acb42e52b96bf3af0b4b942e6516b51198bebd3402640102006af7" - ], - "index": "pypi", - "version": "==1.15.0" - } - }, - "develop": {} -} diff --git a/README.md b/README.md index bd5dd311..cfcd4a74 100644 --- a/README.md +++ b/README.md @@ -10,20 +10,19 @@ 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. @@ -31,7 +30,7 @@ This will launch a server on http://localhost:8000. Content in the server will l ### 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 ` 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 diff --git a/requirements.in b/requirements.in new file mode 100644 index 00000000..4fdacb3f --- /dev/null +++ b/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 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..c615a6c9 --- /dev/null +++ b/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 diff --git a/scripts/build b/scripts/build new file mode 100755 index 00000000..ccc7b739 --- /dev/null +++ b/scripts/build @@ -0,0 +1,3 @@ +#!/bin/sh + +exec mkdocs build diff --git a/scripts/lint-yaml b/scripts/lint-yaml new file mode 100755 index 00000000..8885d174 --- /dev/null +++ b/scripts/lint-yaml @@ -0,0 +1,3 @@ +#!/bin/sh + +exec yamllint -sc yamllint.yml yamllint.yml docs/ mkdocs.yml diff --git a/scripts/serve b/scripts/serve new file mode 100755 index 00000000..39f04f6f --- /dev/null +++ b/scripts/serve @@ -0,0 +1,3 @@ +#!/bin/sh + +exec mkdocs serve From 46cf74b4a11bd26ff990791c498f2d990c7c1cea Mon Sep 17 00:00:00 2001 From: Peter Law Date: Sat, 31 Aug 2019 18:19:45 +0100 Subject: [PATCH 3/4] Better way of detecting unwanted changes Until https://github.com/jazzband/pip-tools/issues/882 is solved, this is probably as reliable as we're going to get. --- .circleci/config.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index c7b6910b..69110d61 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -33,7 +33,11 @@ jobs: 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 + pip-compile --quiet + # show what the changes are, for nicer debugging + git diff + # error-exit if there are changes + git diff-index --quiet HEAD -- deploy: docker: From c4a9e9a064065ffb6aa0ae46da23fa0781a8bff5 Mon Sep 17 00:00:00 2001 From: Peter Law Date: Mon, 2 Sep 2019 20:26:20 +0100 Subject: [PATCH 4/4] Simplify has-changed check --- .circleci/config.yml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 69110d61..d73c4207 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -34,10 +34,7 @@ jobs: command: | . venv/bin/activate pip-compile --quiet - # show what the changes are, for nicer debugging - git diff - # error-exit if there are changes - git diff-index --quiet HEAD -- + git diff --exit-code deploy: docker: