From e0160c74b9d0d327c4cadc4b9f385d4b6605243b Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Tue, 10 Dec 2024 23:41:47 +0000 Subject: [PATCH 1/5] feat(docs): add pymdownx.details extension allows for collapsible admonition blocks https://squidfunk.github.io/mkdocs-material/reference/admonitions/#collapsible-blocks also alphabetized the list of extensions --- mkdocs.yml | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 94c39f2..7bc1a5f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,21 +45,22 @@ markdown_extensions: - codehilite: linenums: true - mdx_truly_sane_lists + - meta + - pymdownx.details - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg - pymdownx.inlinehilite - - pymdownx.tasklist: - custom_checkbox: true - - pymdownx.tabbed + - pymdownx.smartsymbols - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format - - pymdownx.smartsymbols - - meta + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tabbed + - smarty - toc: # insert a blank space before the character permalink: " ΒΆ" - - smarty From 67e17b0167e88e3f89b44d826fc0a4a4f0fdc839 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Tue, 10 Dec 2024 23:28:19 +0000 Subject: [PATCH 2/5] docs: getting started prerequisites --- docs/.pages | 1 + docs/development/README.md | 131 +++++++++++++++++++++++++++++++++++++ 2 files changed, 132 insertions(+) create mode 100644 docs/development/README.md diff --git a/docs/.pages b/docs/.pages index b783fad..5589571 100644 --- a/docs/.pages +++ b/docs/.pages @@ -1,2 +1,3 @@ nav: - Home: README.md + - development diff --git a/docs/development/README.md b/docs/development/README.md new file mode 100644 index 0000000..dd61c9c --- /dev/null +++ b/docs/development/README.md @@ -0,0 +1,131 @@ +# Getting started with development + +!!! info + + This guide will take you through the process of getting the [`pems`](https://github.com/compilerla/pems) project running in + your local development environment. + + `pems` uses [VS Code devcontainers](https://code.visualstudio.com/docs/devcontainers/containers) to provide a + platform-agnostic, standardized development environment. + + For more about why we use Dev Containers, check our Compiler's blog post: + [_How to support a platform-agnostic engineering team with VS Code Dev Containers_](https://compiler.la/blog/2024/devcontainer-platform-agnostic-team). + +## Prerequisites + +This section describes the tooling you need to have installed and configured on your development machine before continuing. + +### Git + +Git is an open source version control system that we use in `pems` to track changes to the codebase over time. Many operating +systems come with Git already installed. Check if you have Git installed in a terminal with the following command: + +```shell +git --version +``` + +If git is installed, the output should look similar to: + +```console +$ git --version +git version 2.39.5 +``` + +If Git is not installed, head to the [Git downloads page](https://git-scm.com/downloads) to get an installer for your operating +system. + +### Docker and Docker Compose + +Docker and Docker Compose (or just Compose) are key tools that allow for running the various services required for `pems`. + +Confirm if you already have Docker installed, in a terminal: + +```shell +docker --version +``` + +If Docker is installed, the output should look similar to: + +```console +$ docker --version +Docker version 27.4.0, build bde2b89 +``` + +And similarly to check if Compose is installed: + +```shell +docker compose version +``` + +When Compose is installed, output will look similar to: + +```console +$ docker compose version +Docker Compose version v2.31.0 +``` + +There are different ways to acquire this software depending on your operating system. The simplest approach for Windows and +MacOS users is to install [Docker Desktop](https://docs.docker.com/desktop/). + +??? warning "License requirements for Docker Desktop" + + Use of Docker Desktop is subject to [Docker's licensing terms](https://www.docker.com/legal/docker-subscription-service-agreement/). + In particular, note that **Section 4.2** calls out government users specifically: + + > Government Entities shall not use Docker Desktop or access other Entitlements of the Service without purchasing a Subscription. + +#### Windows + +It is possible to run Docker and Compose on Windows without installing Docker Desktop. This involves using the [Windows Subsystem +for Linux v2 (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/install#step-2-update-to-wsl-2), where Docker is configured +to run. + +This article walks through this procedure in more detail: +[_How to run docker on Windows without Docker Desktop_](https://dev.to/_nicolas_louis_/how-to-run-docker-on-windows-without-docker-desktop-hik). + +#### MacOS + +With MacOS and [Homebrew](https://brew.sh/), installing Docker and Compose are as simple as: + +```shell +brew install docker docker-compose colima +``` + +Once the install completes, start `colima` (an [open source container runtime](https://github.com/abiosoft/colima)): + +```shell +brew services start colima +``` + +#### Linux + +Docker CE (also known as Docker Engine) is how to run Docker and Compose on Linux. Docker provides an +[installation guide for Docker CE](https://docs.docker.com/engine/install/). + +### VS Code and Dev Containers extension + +VS Code is an open source Integrated Development Environment (IDE) from Microsoft. Check if you already have it installed: + +```shell +code -v +``` + +If installed, output should look similar to: + +```console +$ code -v +1.95.3 +f1a4fb101478ce6ec82fe9627c43efbf9e98c813 +x64 +``` + +Otherwise, [download VS Code](https://code.visualstudio.com/download) for your operating system. + +Once installed, open VS Code and enter `Ctrl`/`Cmd` + `P` to open the VS Code Quick Open pane. Then enter: + +```console +ext install ms-vscode-remote.remote-containers +``` + +`ms-vscode-remote.remote-containers` is the Extension ID of the +[Dev Containers extension from Microsoft](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). From cd0f8a4665786c274785ab2ab9aa5f12d868a651 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Wed, 11 Dec 2024 22:43:31 +0000 Subject: [PATCH 3/5] docs: getting started - get the code - run with docker compose - open in vs code devcontainer - explore devcontainer --- docs/development/README.md | 90 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/docs/development/README.md b/docs/development/README.md index dd61c9c..b4d0e49 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -129,3 +129,93 @@ ext install ms-vscode-remote.remote-containers `ms-vscode-remote.remote-containers` is the Extension ID of the [Dev Containers extension from Microsoft](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). + +## Get the project code + +Use Git to clone the repository to your local machine: + +```shell +git clone https://github.com/compilerla/pems.git +``` + +Then change into the `pems` directory and create an environment file from the sample: + +```shell +cd pems +cp .env.sample .env +``` + +Feel free to inspect the environment file, but leave the defaults for now. + +## Run the application + +Start the application service with Compose: + +```shell +docker compose up -d app +``` + +The `-d` flag starts the service in "detatched" mode, so your terminal is still available for additional commands. Without this flag, your terminal attaches to the service container's standard output. + +The application is now running on `http://localhost:8000`. + +Stop the running service with Compose: + +```shell +docker compose down +``` + +## Open the project in a VS Code devcontainer + +Still in your terminal, enter the following command to open the project in VS Code: + +```shell +code . +``` + +Once the project is loaded in VS Code, you should see a notification pop-up that will ask if you want to reopen the project in +a devcontainer. + +If you don't see this notification, or if you dismissed it, use the VS Code Quick Open pane with `Ctrl`/`Cmd` + `P` and enter: + +```md +> Dev Containers: Rebuild and Reopen in Container +``` + +The VS Code window will reload into the devcontainer. + +Once loaded, hit `F5` to start the application in debug mode. The application is now running on `http://localhost:8000`. + +## Explore the devcontainer + +This section describes other areas to explore within the VS Code devcontainer. + +### Debugger + +Open a Python file in the `pems/` directory and add a breakpoint by clicking the space next to a line number, +leaving a small red circle where you clicked. + +Step through the running application on `http://localhost:8000` to trigger the code path you selected. Execution is paused +and VS Code allows you to inspect the runtime environment, context, etc. + +### Integrated terminal + +Press `Ctrl` + `~` to bring up the integrated `TERMINAL` window. You are now in a `bash` terminal running inside the +context of the devcontainer. + +### Docs site + +Open the `PORTS` tab to see port bindings for additional services. Look for the `Forwarded Address` of the `docs` service and +click to open the docs site in your browser, running on `localhost`. + +Edit the documentation files in VS Code, and once saved, the local docs site will rebuild with the changes. + +### Test runner + +Use the VS Code Quick Open pane with `Ctrl`/`Cmd` + `P` and enter: + +```md +> Testing: Focus +``` + +To focus on the `Testing` pane on the left side. Click the play button to run the unit tests. From ed763ef5fc9b551ea42b00c5a709f96ec04b2f71 Mon Sep 17 00:00:00 2001 From: Luis Alvergue Date: Thu, 12 Dec 2024 15:06:39 +0000 Subject: [PATCH 4/5] ci: tests run for all pushes to main regardless if it's a commit or a tag push --- .github/workflows/deploy.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index ee9c295..55cb1aa 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -18,11 +18,9 @@ defaults: jobs: tests-ui: uses: ./.github/workflows/tests-ui.yml - if: github.ref_type == 'tag' tests-pytest: uses: ./.github/workflows/tests-pytest.yml - if: github.ref_type == 'tag' permissions: pull-requests: write contents: write From 83cdc015b97621e76fd87b2be368d40ab7fd172e Mon Sep 17 00:00:00 2001 From: Luis Alvergue Date: Thu, 12 Dec 2024 20:38:07 +0000 Subject: [PATCH 5/5] ci: remove if condition on deploy job so that deploy does not run regardless of the success or failure of tests-ui and tests-pytest, i.e., needs actually behaves as expected --- .github/workflows/deploy.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 55cb1aa..b63133a 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -28,7 +28,6 @@ jobs: deploy: runs-on: ubuntu-latest needs: [tests-ui, tests-pytest] - if: (!cancelled()) permissions: packages: write