Merge pull request #178 from torchbox/chore/devcontainer

Add VS Code devcontainer config

Author: Ben Dickinson

.devcontainer/devcontainer.json

@@ -0,0 +1,27 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.209.6/containers/docker-existing-docker-compose
+{
+  "name": "django-pattern-library devcontainer",
+  "dockerComposeFile": [
+    "../docker-compose.yml"
+  ],
+  "service": "web",
+  "workspaceFolder": "/app",
+  "settings": {
+      "terminal.integrated.profiles.linux": {
+          "bash": {
+              "path": "bash",
+              "icon": "terminal-bash"
+          },
+      },
+      "terminal.integrated.defaultProfile.linux": "bash"
+  },
+  "extensions": [
+      "editorconfig.editorconfig",
+      "github.vscode-pull-request-github",
+      "ms-python.python",
+      "ms-python.vscode-pylance",
+      "syler.sass-indented"
+  ],
+  "remoteUser": "dpl"
+}

.github/workflows/ci.yml

@@ -81,12 +81,12 @@ jobs:
       # Docs website build.
       - run: poetry run mkdocs build --strict
       # Demo website build.
-      - run: wget --mirror --page-requisites --no-parent --no-verbose http://localhost:8000/django-pattern-library/demo/pattern-library/
+      - run: wget --mirror --page-requisites --no-parent --no-verbose http://localhost:8000/django-pattern-library/demo/
       - run: mv localhost:8000/django-pattern-library/demo site
       # Demo render_patterns.
       - run: poetry run django-admin render_patterns --settings=tests.settings.production --pythonpath=. --wrap-fragments --output=site/dpl-rendered-patterns
       # Package build, incl. publishing an experimental pre-release via GitHub Pages for builds on `main`.
-      - run: cat pyproject.toml| awk '{sub(/^version = .+/,"version = \"0.0.0.dev\"")}1' > pyproject.toml.tmp && mv pyproject.toml.tmp pyproject.toml
+      - run: cat pyproject.toml | awk '{sub(/^version = .+/,"version = \"0.0.0.dev\"")}1' > pyproject.toml.tmp && mv pyproject.toml.tmp pyproject.toml
       - run: poetry build
       - run: mv dist site
       - uses: actions/upload-artifact@v2

CHANGELOG.md

@@ -6,6 +6,12 @@
 
 - Support for Django 4.0 ([#164](https://github.com/torchbox/django-pattern-library/pull/164)).
 - Support for Python 3.10 ([#163](https://github.com/torchbox/django-pattern-library/pull/163)).
+- VS Code devcontainer for development [#178](https://github.com/torchbox/django-pattern-library/pull/178)
+
+### Changed
+
+- Change Poetry version to be `>=1.1.12,<2` in Docker development setup (prevents `JSONDecodeError` issue under Python 3.10) [#178](https://github.com/torchbox/django-pattern-library/pull/178)
+- Move demo/test app pattern-library from `/pattern-library/` to `/` [#178](https://github.com/torchbox/django-pattern-library/pull/178)
 
 ### Removed
 
@@ -29,7 +35,7 @@ This addresses the following limitations of the pattern library:
 - [#113 Django form fields not well supported](https://github.com/torchbox/django-pattern-library/issues/113)
 - [#135 Competing tag/context config for image provides inconsistent result](https://github.com/torchbox/django-pattern-library/issues/135)
 
-View the [documentation](https://torchbox.github.io/django-pattern-library/guides/defining-template-context/#modifying-template-contexts-with-python), as well as demos leveraging the new capability: [forms](https://torchbox.github.io/django-pattern-library/demo/pattern-library/pattern/patterns/pages/forms/example_form.html) (see [forms and fields recipe](https://torchbox.github.io/django-pattern-library/recipes/forms-and-fields/)), and [pagination](https://torchbox.github.io/django-pattern-library/demo/pattern-library/pattern/patterns/pages/search/search.html) (see [pagination recipe](https://torchbox.github.io/django-pattern-library/recipes/pagination/)).
+View the [documentation](https://torchbox.github.io/django-pattern-library/guides/defining-template-context/#modifying-template-contexts-with-python), as well as demos leveraging the new capability: [forms](https://torchbox.github.io/django-pattern-library/demo/pattern/patterns/pages/forms/example_form.html) (see [forms and fields recipe](https://torchbox.github.io/django-pattern-library/recipes/forms-and-fields/)), and [pagination](https://torchbox.github.io/django-pattern-library/demo/pattern/patterns/pages/search/search.html) (see [pagination recipe](https://torchbox.github.io/django-pattern-library/recipes/pagination/)).
 
 ## [0.4.0](https://github.com/torchbox/django-pattern-library/releases/tag/v0.4.0) - 2021-05-20
 

CONTRIBUTING.md

@@ -2,48 +2,68 @@
 
 This document contains information for anyone wishing to contribute to the project.
 
-## Install
+
+
+## Installation
 
 The repo includes a simple test application that can be run locally to develop the pattern library itself.
+
 First, clone the repo:
 
 ```sh
 git clone git@github.com:torchbox/django-pattern-library.git
 cd django-pattern-library
 ```
 
-### Run a local build with Poetry
+Once you have the code, there are several ways of running the project:
 
-We use [Poetry](https://poetry.eustace.io/docs/) to manage Python dependencies, so make sure you've got it installed.
+- [In a VS Code devcontainer](#vs-code-devcontainer)
+- [In Docker, via docker-compose](#docker-compose)
+- [Locally, with Poetry](#run-locally-with-poetry)
 
-Then you can install the dependencies and run the test app:
+### VS Code devcontainer
 
-```sh
-poetry install
-# Start the server for testing:
-poetry run django-admin runserver --settings=tests.settings.dev --pythonpath=.
-# Or to try out the render_patterns command:
-poetry run django-admin render_patterns --settings=tests.settings.dev --pythonpath=. --dry-run --verbosity 2
-```
+For users of Docker and VS Code, there is a [devcontainer](https://code.visualstudio.com/docs/remote/containers) setup included in the repository
+that will automatically install the Python dependencies and start the frontend tooling.
+
+Once the container is built, open a terminal with VS Code and run `django-admin runserver` and click the URL (normally http://127.0.0.1:8000/) to open the app in your browser. You'll see a 404 page, because there's nothing at `/`, add `pattern-libary/` to the end of the URL to view the demo app.
 
-### Run a local build with docker
+### `docker-compose`
 
-First [install Docker and docker-compose](https://docs.docker.com/compose/install/), and make sure Docker is started.
+First [install Docker and docker-compose](https://docs.docker.com/compose/install/), and make sure Docker is started. Then:
 
 ```sh
 # Install the front-end tooling in the docker container:
 docker-compose run frontend npm ci
-# Start the dev server and run the front-end tooling in watch mode:
+# Bring up the web container and run the front-end tooling in watch mode:
 docker-compose up
+# Run the development server:
+docker-compose exec web django-admin runserver 0.0.0.0:8000
 ```
 
-Once the server is started, the pattern library will be available at `http://localhost:8000/pattern-library/`.
+Once the server is started, the pattern library will be available at `http://localhost:8000/`.
+
+### Run locally with Poetry
 
-### Front-end tooling
+We use [Poetry](https://python-poetry.org/docs/) to manage Python dependencies, so make sure you've got it installed.
+
+Then you can install the dependencies and run the test app:
+
+```sh
+poetry install
+# Start the server for testing:
+poetry run django-admin runserver --settings=tests.settings.dev --pythonpath=.
+# Or to try out the render_patterns command:
+poetry run django-admin render_patterns --settings=tests.settings.dev --pythonpath=. --dry-run --verbosity 2
+```
+
+## Front-end tooling
 
 If you want to make changes to the front-end assets (located in the `pattern_library/static/pattern_library/src` folder), you'll need to ensure the tooling is set up in order to build the assets.
 
-If you are using Docker you will already have the tooling set up and running in watch mode. Otherwise,
+If you are using Docker, you will already have the tooling set up and running in watch mode. You can view the logs with `docker-compose logs frontend` from your host machine.
+
+Otherwise, we recommend using [`nvm`](https://github.com/nvm-sh/nvm):
 
 ```sh
 # Install the correct version of Node
@@ -56,7 +76,7 @@ npm run build
 npm run start
 ```
 
-### Documentation
+## Documentation
 
 The project’s documentation website is built with [MkDocs](https://www.mkdocs.org/).
 

Dockerfile

@@ -1,9 +1,9 @@
-FROM python:3.7
+FROM python:3.10
 
 WORKDIR /app
 
-RUN useradd dpl && \
-    pip install --pre poetry && \
+RUN useradd --create-home dpl && \
+    pip install "poetry>=1.1.12,<2" && \
     poetry config virtualenvs.create false
 
 COPY pyproject.toml ./

README.md

@@ -2,7 +2,7 @@
 
 [![PyPI](https://img.shields.io/pypi/v/django-pattern-library.svg)](https://pypi.org/project/django-pattern-library/) [![PyPI downloads](https://img.shields.io/pypi/dm/django-pattern-library.svg)](https://pypi.org/project/django-pattern-library/) [![Build status](https://github.com/torchbox/django-pattern-library/workflows/CI/badge.svg)](https://github.com/torchbox/django-pattern-library/actions) [![Total alerts](https://img.shields.io/lgtm/alerts/g/torchbox/django-pattern-library.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/torchbox/django-pattern-library/alerts/)
 
-> UI pattern libraries for Django templates. Try our [online demo](https://torchbox.github.io/django-pattern-library/demo/pattern-library/).
+> UI pattern libraries for Django templates. Try our [online demo](https://torchbox.github.io/django-pattern-library/demo/).
 
 ![Screenshot of the pattern library UI, with navigation, pattern rendering, and configuration](https://raw.githubusercontent.com/torchbox/django-pattern-library/main/.github/pattern-library-screenshot.webp)
 
@@ -31,8 +31,8 @@ Learn more by watching our presentation – [Reusable UI components: A journey f
 
 The pattern library is dependent on Django for rendering – but also supports exporting as a static site if needed. Try out our online demo:
 
-- For a component, [accordion.html](https://torchbox.github.io/django-pattern-library/demo/pattern-library/pattern/patterns/molecules/accordion/accordion.html)
-- For a page-level template, [person_page.html](https://torchbox.github.io/django-pattern-library/demo/pattern-library/pattern/patterns/pages/people/person_page.html)
+- For a component, [accordion.html](https://torchbox.github.io/django-pattern-library/demo/pattern/patterns/molecules/accordion/accordion.html)
+- For a page-level template, [person_page.html](https://torchbox.github.io/django-pattern-library/demo/pattern/patterns/pages/people/person_page.html)
 
 ## Documentation
 

docker-compose.yml

@@ -12,6 +12,7 @@ services:
         source: .
         target: /app
         consistency: delegated
+    command: tail -f /dev/null
 
   frontend:
     command: npm start

docs/getting-started.md

@@ -1,6 +1,6 @@
 # Getting started
 
-> If you just want to see django-pattern-library up and running, have a look at our [online demo](https://torchbox.github.io/django-pattern-library/demo/pattern-library/pattern/patterns/molecules/accordion/accordion.html).
+> If you just want to see django-pattern-library up and running, have a look at our [online demo](https://torchbox.github.io/django-pattern-library/demo/pattern/patterns/molecules/accordion/accordion.html).
 
 ## Installation
 

docs/index.md

@@ -29,8 +29,8 @@ Pattern libraries will change your workflow for the better:
 
 The pattern library is dependent on Django for rendering – but also supports exporting as a static site if needed. Try out our online demo:
 
-- For a component, [accordion.html](https://torchbox.github.io/django-pattern-library/demo/pattern-library/pattern/patterns/molecules/accordion/accordion.html)
-- For a page-level template, [person_page.html](https://torchbox.github.io/django-pattern-library/demo/pattern-library/pattern/patterns/pages/people/person_page.html)
+- For a component, [accordion.html](https://torchbox.github.io/django-pattern-library/demo/pattern/patterns/molecules/accordion/accordion.html)
+- For a page-level template, [person_page.html](https://torchbox.github.io/django-pattern-library/demo/pattern/patterns/pages/people/person_page.html)
 
 ## Why this exists
 

mkdocs.yml

@@ -58,4 +58,4 @@ nav:
     - 'Related projects': 'community/related-projects.md'
     - 'Code of conduct': 'community/code-of-conduct.md'
     - 'Security policy': 'community/security-policy.md'
-  - 'Online demo': '/django-pattern-library/demo/pattern-library/'
+  - 'Online demo': '/django-pattern-library/demo/'