diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 53ca2c4..e337156 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -6,6 +6,9 @@ "dev", "docs" ], + "forwardPorts": [ + "docs:8001" + ], "workspaceFolder": "/compiler/app", "postCreateCommand": [ "/bin/bash", diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml index dca8300..03c5978 100644 --- a/.github/workflows/mkdocs.yml +++ b/.github/workflows/mkdocs.yml @@ -7,7 +7,6 @@ on: paths: - ".github/workflows/mkdocs.yml" - "docs/**" - - ".markdownlint.yaml" - "mkdocs.yml" jobs: diff --git a/.markdownlint.yaml b/.markdownlint.yaml index f4c8d40..ed65633 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,10 +1,6 @@ # includes/excludes all rules by default default: true -# 4-space list indentation works best with MkDocs -MD007: - indent: 4 - # Remove line length limit - no one wants to hard wrap all their paragraphs MD013: false diff --git a/docs/.pages b/docs/.pages index 2547f3e..23b15a5 100644 --- a/docs/.pages +++ b/docs/.pages @@ -1,4 +1,4 @@ nav: - Home: README.md - - Features: features - - Usage: usage + - Setup: setup.md + - Development: development.md diff --git a/docs/README.md b/docs/README.md index 8163e6d..2a6321a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,45 +1,21 @@ -# template-devcontainer Docs +# Slackronyms Docs ## Introduction -This is the documentation site for [`compilerla/template-devcontainer`](https://github.com/compilerla/template-devcontainer). +This is the documentation site for [`compilerla/slackronyms`](https://github.com/compilerla/slackronyms), an open-source Slack app to help teams keep track of acronyms and other abbreviations. -`template-devcontainer` is a [template repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository) -with a minimal [VS Code devcontainer](https://code.visualstudio.com/docs/remote/containers) setup. +## Usage -`template-devcontainer` can be used as the basis for another language-specific devcontainer, -or as a quick ready-made Linux development environment. +When added to your workspace, Slackronyms provides a `/define` command that is used to both ouput and set definitions for a term, depending on the way the command is formatted. -Docs are built using [`mkdocs`](https://www.mkdocs.org/). This site is built using [`mkdocs-material`](https://squidfunk.github.io/mkdocs-material/). +### `/define ` -## Use this template +Outputs a definition for the given term as a public message in the current channel. The output does not reveal the identity of the person who requested it. -[Generate a new repository from the template](https://github.com/compilerla/template-devcontainer/generate){.md-button} +![example output from running the command /define TDQ](img/define-output-example.png) -## Why? +### `/define : ` -In no particular order, here are some reasons Compiler likes to use devcontainers as part of our software engineering workflow: +Appending a colon and a definition to a basic `/define ` command will set the definition for that term. -_Read more in our blog post: [How to support a platform-agnostic engineering team with VS Code Dev Containers](https://compiler.la/blog/2024/devcontainer-platform-agnostic-team)_. - -| Reason | More | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **Cross-platform** | With only VS Code and Docker as dependencies, devcontainers allow developers on Linux, Mac, and Windows to work in a consistent environment, no matter the project's stack | -| **Easily extendable** | The VS Code community maintains a [library of extensions](https://marketplace.visualstudio.com/VSCode) to add features and functionality to the development environment; individual personalizations can be made via [dotfiles](https://code.visualstudio.com/docs/remote/containers#_personalizing-with-dotfile-repositories) | -| **Enforce best practices** | Baking linters, `pre-commit` checks, test runners, and more into the devcontainer ensures the team's best practices are no-brainer always-on features of the development workflow | -| **Rapid onboarding** | By minimizing the steps from `git clone` to getting tests to pass or the app running locally, devcontainers make it easier to onboard as a new developer and spend time contributing instead of wallowing in environment setup | -| **Unified code style** | With common editor settings like code formatting on save, standard indentation characters and spacing, consistent line endings, and more, the team never has to worry about what the code looks like or accidentally committing BOMs | - -## Prior art - -This template was informed by our work on recent projects as a remote-first, cross-platform development team. - -Some of our recent work built on the devcontainer pattern includes: - -- [`cal-itp/benefits`](https://github.com/cal-itp/benefits) (Python/Django web app) -- [`cal-itp/eligibility-api`](https://github.com/cal-itp/eligibility-api) (Python API library) -- [`cal-itp/eligibility-server`](https://github.com/cal-itp/eligibility-server) (Python/Flask API server) -- [`cal-itp/hashfields`](https://github.com/cal-itp/hashfields) (Python CLI tool) -- [`cal-itp/mobility-marketplace`](https://github.com/cal-itp/mobility-marketplace) (Jekyll static site) -- [`compilerla/compiler.la`](https://github.com/compilerla/compiler.la) (Jekyll static site) -- [`compilerla/conventional-pre-commit`](https://github.com/compilerla/conventional-pre-commit) (Python pre-commit hook) +![example output from running the command /define CDT: California Department of Technology](img/define-set-example.png) diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..66e017c --- /dev/null +++ b/docs/development.md @@ -0,0 +1,50 @@ +# Development + +!!! info "See also" + + VS Code tutorial: [Remote development in Containers](https://code.visualstudio.com/docs/devcontainers/tutorial) + +## Setting up the dev container + +We include a [Dev Container](https://code.visualstudio.com/docs/devcontainers/containers) configuration to help with local testing and development. + +First, follow the [Setup](../setup/) steps to create the app in your Slack workspace and load your keys into a `.env` file. + +**The first time you run this project** you'll have to manually build the app container in your terminal, because the dev container is built from the app container. + +```sh +docker compose build app +``` + +From there, connect to the dev container to begin working on the project: + +1. Open the repository directory in VS Code +1. Ctrl/Cmd+Shift+P to bring up the Command Palette +1. Start typing `devcontainers` to filter the command list +1. Select **Rebuild and Reopen in Container** to start from scratch +1. Select **Reopen in Container** to reopen the last dev container used + +Once inside the dev container, you have to manually start the app by pressing F5 (or switch the primary sidebar to Run and Debug and click the play button). + +You should see output in a new terminal indicating that the app is now running, and you should now be able to invoke it in your Slack test workspace! Try the `/define` command to confirm. + +!!! important + After modifying app code, it will need to be restarted for the changes to take effect. Press Ctrl/Cmd+Shift+F5 to restart it (or click the refresh icon that appeared in the top menu bar). Your updated code will now be invoked the next time you run a command in Slack. + +The app can be stopped with Shift+F5 (or the stop icon in the top menu bar). + +To exit the dev container, use the **Reopen Folder Locally** command. + +## Run the tests + +Python unit tests are written with [`pytest`](https://docs.pytest.org/en/latest/) and can be run when the dev container is open by using the VS Code Testing sidebar or in a terminal: + +1. Open a new terminal + +1. ```bash + cd slackronyms/ + ``` + +1. ```bash + pytest + ``` diff --git a/docs/features/.pages b/docs/features/.pages deleted file mode 100644 index 0318277..0000000 --- a/docs/features/.pages +++ /dev/null @@ -1,3 +0,0 @@ -nav: - - Devcontainer: devcontainer.md - - ... diff --git a/docs/features/dependabot.md b/docs/features/dependabot.md deleted file mode 100644 index f67bd78..0000000 --- a/docs/features/dependabot.md +++ /dev/null @@ -1,21 +0,0 @@ -# Dependabot - -!!! summary "Configuration" - - - **Main config file:** [`.github/dependabot.yml`](https://github.com/compilerla/template-devcontainer/blob/main/.github/dependabot.yml) - -## Introduction - -[Dependabot](https://docs.github.com/en/code-security/dependabot) is GitHub's service for keeping repository dependencies -up to date and staying ahead of security vulnerabilities in open source packages. - -Based on the configured package ecosystems, Dependabot will send alerts to repository administrators for security-related events -in referenced packages. Dependabot will also open Pull Requests to update dependencies when fixes are published. - -## Features - -### GitHub Actions - -Watches for updates to GitHub Actions workflow steps, e.g. [`actions/checkout`](https://github.com/actions/checkout). - -Read more about [Keeping actions up to date with Dependabot](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot) diff --git a/docs/features/devcontainer.md b/docs/features/devcontainer.md deleted file mode 100644 index 424964b..0000000 --- a/docs/features/devcontainer.md +++ /dev/null @@ -1,57 +0,0 @@ -# Devcontainer - -!!! summary "Configuration" - - - **Main config file:** [`devcontainer.json`](https://github.com/compilerla/template-devcontainer/blob/main/.devcontainer/devcontainer.json) - - **Dependencies:** [`requirements.txt`](https://github.com/compilerla/template-devcontainer/blob/main/.devcontainer/requirements.txt) - - **Dockerfile:** [`Dockerfile`](https://github.com/compilerla/template-devcontainer/blob/main/.devcontainer/Dockerfile) - - **Service definition:** [`compose.yml`](https://github.com/compilerla/template-devcontainer/blob/main/compose.yml) - - **Finalization:** [`postAttach.sh`](https://github.com/compilerla/template-devcontainer/blob/main/.devcontainer/postAttach.sh) - -## Introduction - -[VS Code](https://code.visualstudio.com/) can be used together with Docker via the -[Remote - Containers](https://code.visualstudio.com/docs/remote/containers) extension to enable a container-based development -environment. - -As a remote-first, cross-platform development team, Compiler uses devcontainers to ease the onboarding -and local development process for our engineering team, and to ensure our Open Source projects are widely accessible and easily -reproducable for others. - -## The image - -The devcontainer's image is called `compilerla/template-devcontainer`. - -### Base - -The image is based on [`python:3.11`](https://hub.docker.com/_/python), to ease installation of common tooling like -[`mkdocs`](docs.md) and [`pre-commit`](pre-commit.md). - -### Setup - -Most setup is performed as the non-root `$USER`, with a default of `compiler`. - -A home directory is created at `/home/$USER` and the working directory is set to `/home/$USER/src`. - -Additional command-line tools included in the image: - -- `curl` -- `git` -- `pip` -- `wget` - -See the official [`python` image on DockerHub](https://hub.docker.com/_/python) for more. - -### Requirements - -The `.devcontainer/requirements.txt` file lists [`PyPI`](https://pypi.org/) packages installed by default into the devcontainer. - -### Extensions - -The `devcontainer/devcontainer.json` file lists VS Code extensions installed with the devcontainer. These include: - -- [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) for supercharing the `git` experience -- [Git Graph](https://marketplace.visualstudio.com/items?itemName=mhutchie.git-graph) for visualizing the `git` commit history -- [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) for Markdown linting and style checking directly in VS Code -- [Mermaid Markdown Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=bpruitt-goddard.mermaid-markdown-syntax-highlighting) for editing Mermaid diagrams in [documentation](docs.md) -- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for good default formatting and linting of most file types diff --git a/docs/features/docs.md b/docs/features/docs.md deleted file mode 100644 index 35d758b..0000000 --- a/docs/features/docs.md +++ /dev/null @@ -1,34 +0,0 @@ -# Documentation - -!!! summary "Configuration" - - - **Main config file:** [`mkdocs.yml`](https://github.com/compilerla/template-devcontainer/blob/main/mkdocs.yml) - - **Additional dependencies:** [`docs/requirements.txt`](https://github.com/compilerla/template-devcontainer/blob/main/docs/requirements.txt) - - **Installation:** [`Dockerfile`](https://github.com/compilerla/template-devcontainer/blob/main/.devcontainer/Dockerfile) - - **Service definition:** [`compose.yml`](https://github.com/compilerla/template-devcontainer/blob/main/compose.yml) - -## Introduction - -The devcontainer includes a system for building project documentation, useful for developing and publishing a full-featured -documentation website, either as a standalone entity or as part of a software library/project. - -Documenation is written in plaintext files using the popular [Markdown syntax](https://www.markdownguide.org/basic-syntax/). -Besides being widely supported and straightfowrad to edit in a variety of platforms, documentation written as Markdown is -easily versioned by systems like `git`. - -The Python-based [`mkdocs`](https://www.mkdocs.org/) tool builds Markdown documentation files into a website structure. - -Themeing and additional documentation content functionality are provided by the -[`mkdocs-material`](https://squidfunk.github.io/mkdocs-material/) extension. - -## Features - -- Complete color themes for both light and dark modes -- Google Analytics support (with a `G-xxxxxxxxxx` configuration) -- Site search -- Icons from [`FontAwesome`](https://fontawesome.com/) -- [Diagram support via Mermaid.js](https://squidfunk.github.io/mkdocs-material/reference/diagrams/) -- Better site navigation with [`awesome-pages`](https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/) -- Redirect old URLs when content moves around with [`redirects`](https://github.com/mkdocs/mkdocs-redirects) - -See the [`mkdocs-material` Reference](https://squidfunk.github.io/mkdocs-material/reference/) for more supported features. diff --git a/docs/features/editor.md b/docs/features/editor.md deleted file mode 100644 index f00c11e..0000000 --- a/docs/features/editor.md +++ /dev/null @@ -1,22 +0,0 @@ -# Editor - -!!! summary "Configuration" - - - **Main config file:** [`.vscode/settings.json`](https://github.com/compilerla/template-devcontainer/blob/main/.vscode/settings.json) - -## Introduction - -The core editor experience and configuration of VS Code - -## Features - -### Shared settings - -- `utf-8` file encoding -- `\n` newlines, final newlines trimmed, final newline added -- trailing whitespace trimmed -- Prettier as the default file formatter - -### Custom settings - -Further personalization can be loaded by individual developers using a [dotfiles repository](https://code.visualstudio.com/docs/remote/containers#_personalizing-with-dotfile-repositories). diff --git a/docs/features/pre-commit.md b/docs/features/pre-commit.md deleted file mode 100644 index 431aad6..0000000 --- a/docs/features/pre-commit.md +++ /dev/null @@ -1,38 +0,0 @@ -# pre-commit - -!!! summary "Configuration" - - - **Main config file:** [`.pre-commit-config.yaml`](https://github.com/compilerla/template-devcontainer/blob/main/.pre-commit-config.yaml) - - **Initialization:** [`Dockerfile`](https://github.com/compilerla/template-devcontainer/blob/main/.devcontainer/Dockerfile) - - **Finalization:** [`postAttach.sh`](https://github.com/compilerla/template-devcontainer/blob/main/.devcontainer/postAttach.sh) - -## Introduction - -[`pre-commit`](https://pre-commit.com/) is a Python framework for running "hooks" during various points in the `git commit` -workflow. - -`pre-commit` hooks do things like enforce commit message formatting and check and automatically clean up file formatting. - -Integrating these checks with the `git commit` workflow ensures every commit follows team conventions and reduces the chance -for simple syntax errors and other hidden bugs. - -## Features - -### Conventional Commits - -Compiler follows the [Conventional Commits](https://www.conventionalcommits.org/) specification for writing commit messages. - -[`compilerla/conventional-pre-commit`](https://github.com/compilerla/conventional-pre-commit) is a `pre-commit` hook that -enforces this convention for every commit. - -### Markdownlint - -[`markdownlint`](https://github.com/DavidAnson/markdownlint) is a static analysis tool (linter) for Markdown documents. - -The related [`markdownlint-cli`](https://github.com/igorshubovych/markdownlint-cli#use-with-pre-commit) tool can be used as -a `pre-commit` hook. - -### Pre-Commit Hooks - -[`pre-commit-hooks`](https://github.com/pre-commit/pre-commit-hooks) is a collection of useful hooks maintained by the -`pre-commit` team. diff --git a/docs/img/define-output-example.png b/docs/img/define-output-example.png new file mode 100644 index 0000000..0abfa19 Binary files /dev/null and b/docs/img/define-output-example.png differ diff --git a/docs/img/define-set-example.png b/docs/img/define-set-example.png new file mode 100644 index 0000000..6a264d0 Binary files /dev/null and b/docs/img/define-set-example.png differ diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..332b98c --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,48 @@ +# Setup + +Setting up this Slack app requires two main things: + +1. A Slack workspace where you have permission to install apps (or can request it) +1. Standing up the application provided in the `slackronyms` folder of this repo somewhere it can run persistently + +## 1. Create and install your Slack app + +1. Open [https://api.slack.com/apps/new](https://api.slack.com/apps/new) and choose **From a manifest**. +1. Choose the workspace you want to install the application to. +1. Replace the contents of the JSON code block with the contents of [`manifest.json`](https://github.com/compilerla/slackronyms/blob/main/slackronyms/manifest.json). +1. Review the configuration and click **Create**. +1. Click **Install to Workspace** and **Allow** on the screen that follows. You'll then be redirected to the App Configuration dashboard. + +The app is now "installed" in the workspace, but it won't do anything until it can connect to the running code. + +## 2. Stand up the Python app + +### Prerequisites + +- An environment where you can run a Python 3.14 app +- A place to store the JSON file that holds the terms and definitions data + - This could be the local filesystem of the Python app, if it's persistent (e.g., an EC2 instance). + - If you use the container provided in `appcontainer/Dockerfile`, you'll need to store the file in some other location and configure the app to read and write from that. + +### Environment Variables + +Before you can run the app, you'll need to store some environment variables. If you're planning to use the containerized app, you can do this by creating a `.env` file and using the `docker compose` configuration provided in `compose.yml` to start the container. + +1. Create a `.env` file from the sample at the root of the repo: + + ```sh + cp .env.sample .env + ``` + +1. Open your app's configuration page from [this list](https://api.slack.com/apps), click **OAuth & Permissions** in the left hand menu, then copy the Bot User OAuth Token. Paste it for `SLACK_BOT_TOKEN` in your `.env` file. +1. Click **Basic Information** from the left hand menu and follow the steps in the App-Level Tokens section to create an app-level token with the `connections:write` scope. Copy this token and paste it for `SLACK_APP_TOKEN` in your `.env` file. + +### Running the application + +A `Dockerfile` is provided in the `appcontainer` folder that will install necessary dependencies and run the app. To build and run it: + +```sh +docker compose up app +``` + +You should see output in a new terminal indicating that the app is now running, and you should now be able to invoke it in your Slack test workspace! Try the `/define` command to confirm. diff --git a/docs/usage/.pages b/docs/usage/.pages deleted file mode 100644 index f3df8c7..0000000 --- a/docs/usage/.pages +++ /dev/null @@ -1,4 +0,0 @@ -nav: - - generate.md - - run-local.md - - reference-image.md diff --git a/docs/usage/generate.md b/docs/usage/generate.md deleted file mode 100644 index 62ca590..0000000 --- a/docs/usage/generate.md +++ /dev/null @@ -1,16 +0,0 @@ -# Generate a new repository - -!!! info "See also" - - GitHub docs: [Creating a repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) - -The simplest way to get started is to create a new repository from the template: - -[Generate a new repository from the template](https://github.com/compilerla/template-devcontainer/generate){.md-button} - -This will copy the files and directory structure from the template into a new repository of your choosing. - -If you intend to publish a [Documentation website](../features/docs.md), be sure to make this a `Public` repository and check the -box to `Include all branches`: - -![Screenshot of creating a new repository from the template on GitHub](img/generate-repo.png) diff --git a/docs/usage/img/generate-repo.png b/docs/usage/img/generate-repo.png deleted file mode 100644 index 884cae0..0000000 Binary files a/docs/usage/img/generate-repo.png and /dev/null differ diff --git a/docs/usage/img/reopen-devcontainer.png b/docs/usage/img/reopen-devcontainer.png deleted file mode 100644 index 6df7e3b..0000000 Binary files a/docs/usage/img/reopen-devcontainer.png and /dev/null differ diff --git a/docs/usage/reference-image.md b/docs/usage/reference-image.md deleted file mode 100644 index 23cb16c..0000000 --- a/docs/usage/reference-image.md +++ /dev/null @@ -1,65 +0,0 @@ -# Reference the pre-built image - -!!! summary "Configuration" - - - **Workflow file:** [`.github/workflows/publish-devcontainer.yml`](https://github.com/compilerla/template-devcontainer/blob/main/.github/workflows/publish-devcontainer.yml) - - **GHCR Packages:** [`compilerla/template-devcontainer`](https://github.com/compilerla/template-devcontainer/pkgs/container/template-devcontainer) - - **Minimal devcontainer.json:** [`devcontainer.pre-built.json`](https://github.com/compilerla/template-devcontainer/blob/main/.devcontainer/devcontainer.pre-built.json) - -`template-devcontainer` maintains a [GitHub Actions](https://github.com/features/actions) workflow that publishes Docker -images to [GitHub Container Registry (GHCR)](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry). - -The publish is triggered for every push to the `main` branch, and multiple image tags are created: - -- `main` uses the default Python version of 3.11 -- `main_3.10` uses Python 3.10 -- `main_3.12` uses Python 3.12 - -There are also corresponding tags for the git SHA of the commit on `main` that triggered the build -(e.g. `sha`, `sha_3.10`, and `sha_3.12`). - -This makes the pre-built devcontainer image available for use in other projects, potentially decreasing startup and onboarding -time even further. - -## From a `devcontainer.json` configuration - -The pre-built devcontainer image can be used as the basis for another `devcontainer.json` configuration, similar to how one -might reference any other image on Docker Hub or GHCR: - -```json -{ - "name": "compilerla/template-devcontainer-pre-built", - "image": "ghcr.io/compilerla/template-devcontainer:main", - // initialize pre-commit hooks on attach (assumes .pre-commit-config.yaml) - "postAttachCommand": "pre-commit install --overwrite" - // other settings -} -``` - -Our [`devcontainer.pre-built.json`](https://github.com/compilerla/template-devcontainer/blob/main/.devcontainer/devcontainer.pre-built.json) -shows a minimal example to get a devcontainer running with the same configuration as the normal `devcontainer.json`, using the -pre-built image. - -See the full [`devcontainer.json` Reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference) for details. - -## Using Docker Compose - -In a `docker-compose.yml` or `compose.yml` file, you can reference the GHCR image directly in a service definition: - -```yaml -services: - myservice: - image: ghcr.io/compilerla/template-devcontainer:main - volume: ./:/home/compiler/src -``` - -Note the `volume` entry mapping the current directory (with the `compose.yml` file) into the [devcontainer working directory](../features/devcontainer.md#setup). - -And then starting the service with: - -```shell -docker compose up myservice -``` - -This is perhaps a less useful approach, with the default `CMD` and `ENTRYPOINT` set in such a way as to make the container -essentially hang (useful when attaching from VS Code). diff --git a/docs/usage/run-local.md b/docs/usage/run-local.md deleted file mode 100644 index e452ee9..0000000 --- a/docs/usage/run-local.md +++ /dev/null @@ -1,68 +0,0 @@ -# Run the devcontainer locally - -!!! info "See also" - - VS Code tutorial: [Remote development in Containers](https://code.visualstudio.com/docs/remote/containers-tutorial) - -## Prerequisites - -### Docker - -Docker is required; the easiest way to get Docker is by downloading and installing [Docker Desktop](https://www.docker.com/products/docker-desktop/) for Linux, Mac (including Apple Silicon!) and Windows. - -### VS Code - -You will also need [VS Code](https://code.visualstudio.com/) and the -[`Remote - Containers` extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) installed. - -### Source code - -Ensure you have a local copy of this template repository: - -```shell -git clone https://github.com/compilerla/template-devcontainer -``` - -Or another repository you generated from this template. - -## Open the repo in VS Code - -From the command line: - -```shell -code /path/to/repository -``` - -Or from the VS Code UI: - -`File > Open Folder > /path/to/repository` - -## Reopen in devcontainer - -At this point, the VS Code UI should prompt you to reopen the folder in the devcontainer: - -![VS Code notification to Reopen the folder in the devcontainer](img/reopen-devcontainer.png) - -### Rebuild and Reopen - -To completely rebuild the devcontainer from scratch and reopen the VS Code window, attached to the running devcontainer: - -1. Bring up the VS Code _Command Palette_ with: `Ctrl/Cmd + Shift + P` -1. Enter `Remote-Containers` to filter the list -1. Enter or select the `Rebuild and Reopen in Container` option - -### Reopen - -To reopen VS Code attached to the most recently built and used devcontainer (the build is skipped if not needed): - -1. Bring up the VS Code _Command Palette_ with: `Ctrl/Cmd + Shift + P` -1. Enter `Remote-Containers` to filter the list -1. Enter or select the `Reopen in Container` option - -## Close the devcontainer - -From within the devcontainer, to close the connection and reopen VS Code on your local (host) machine: - -1. Bring up the VS Code _Command Palette_ with: `Ctrl/Cmd + Shift + P` -1. Enter `Remote-Containers` to filter the list -1. Enter or select the `Reopen Folder Locally` option diff --git a/mkdocs.yml b/mkdocs.yml index 3217da0..53e91f8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,7 +1,7 @@ -site_name: "compilerla/template-devcontainer: Documentation" -repo_url: https://github.com/compilerla/template-devcontainer +site_name: "compilerla/slackronyms: Documentation" +repo_url: https://github.com/compilerla/slackronyms edit_uri: edit/main/docs -site_url: https://compilerla.github.io/template-devcontainer +site_url: https://compilerla.github.io/slackronyms theme: name: material