Merge pull request #40 from stuartleeks/sl/docs-scaffold

Add initial GitHub Pages docs

Author: stuartleeks

.github/workflows/build-and-release.yaml

@@ -4,11 +4,13 @@ on:
   push:
     branches: [ main ]
     paths-ignore:
-    - README.md
+      - README.md
+      - 'docs/**'
   pull_request:
     branches: [ main ]
     paths-ignore:
-    - README.md
+      - README.md
+      - 'docs/**'
 
 jobs:  
   build:

docs/_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-slate

docs/exec.md

@@ -0,0 +1,67 @@
+# devcontainer exec
+
+The `devcontainer exec` command can be used to run commands inside a running dev container. When no options are passed, it will run `bash` in the dev container for the dev container for the current working directory.
+
+Some examples of using `devcontainer exec` are shown below:
+
+```bash
+# Run an interactive bash shell in the 
+# vscode-remote-test-dockerfile devcontainer
+devcontainer exec --name vscode-remote-test-dockerfile bash
+
+# Run a command with args in the 
+# vscode-remote-test-dockercompose_devcontainer/mongo 
+# devcontainer
+devcontainer exec --name vscode-remote-test-dockercompose_devcontainer/mongo ls -a /workspaces/vscode-remote-test-dockerfile
+
+# Run `bash` in the dev container for 
+# the project at `~/ source/my-proj`
+devcontainer exec --path ~/source/my-proj bash
+
+# If none of --name/--path/--prompt 
+# are specified then `--path .` is assumed 
+# (i.e. use the dev container for the current directory)
+devcontainer exec bash
+
+# If command/args not set, `bash` is assumed
+devcontainer exec --name vscode-remote-test-dockerfile
+
+# Combining these to launch bash in the 
+# dev container for the project in the current directory:
+devcontainer exec
+```
+
+## Features of devcontainer exec
+
+Under the covers, `devcontainer exec` launches `docker exec`, but it has a few features on top of this to try to increase productivity.
+
+First, it sets the working directory to be the mount path for the dev container rather than just dropping you in at the root of the container flie system. This can be overridden using `--work-dir`.
+
+Second, it checks whether you have [configured a user in the dev container](https://code.visualstudio.com/docs/remote/containers-advanced#_adding-a-nonroot-user-to-your-dev-container) and uses this user for the `docker exec`.
+
+Lastly, it checks whether you have set up an SSH agent on your host. If you have and VS Code detects it then VS Code will [forward key requests from the container](https://code.visualstudio.com/docs/remote/containers#_using-ssh-keys). In this scenario, `devcontainer exec` configures the exec session to also forward key requests. This enables operations against git remotes secured with SSH keys to succeed.
+
+
+## Prompting for the dev container
+
+
+You can use `--prompt` with `devcontainer exec` instead of `--name` or `--path` and the CLI will prompt you to pick a devcontainer to run the `exec` command against, e.g.:
+
+```bash
+$ ./devcontainer exec ? bash
+Specify the devcontainer to use:
+   0: devcontainer-cli (festive_saha)
+   1: vscode-remote-test-dockerfile (fervent_gopher)
+0
+```
+
+This works well as a terminal profile. For example, you can use this with Windows Terminal profiles:
+
+```json
+{
+    "guid": "{4b304185-99d2-493c-940c-ae74e0f14bba}",
+    "hidden": false,
+    "name": "devcontainer exec",
+    "commandline": "wsl bash -c \"path/to/devcontainer exec --prompt bash\"",
+},
+```

docs/index.md

@@ -0,0 +1,31 @@
+If you find frequently find yourself working at the terminal and are working with [Visual Studio Code dev containers](https://code.visualstudio.com/docs/remote/containers) then the `devcontainer` CLI might be of interest for you!
+
+Examples:
+
+```bash
+
+# The following command opens the current folder in 
+# VS Code as a dev container # i.e. it skips the
+# normal step of opening in VS Code and then 
+# clicking # on the "Re-open in container" prompt.
+$ devcontainer open-in-code
+
+# If you don't have a dev container definition for 
+# your folder then you can use 
+#`devcontainer template add <name>` to add a 
+# dev container definition.
+$ devcontainer template add python-3
+
+# You can use `devcontainer exec` to create a 
+# shell (or run a process) # inside a dev container.
+$ devcontainer exec
+```
+
+See the following topics for more information:
+
+* [Installation](installation)
+* Commands
+  * [open-in-code](open-in-code) - open dev containers in VS Code from the terminal
+  * [template](template) - add dev container definitions to a folder
+  * [exec](exec) - launch a terminal or other command in a dev container
+

docs/installation.md

@@ -0,0 +1,43 @@
+# Installation
+
+
+## Download latest release
+
+Head to the [latest release page](https://github.com/stuartleeks/devcontainer-cli/releases/latest) and download the archive for your platform.
+
+Extract `devcontainer` from the archive and place in a folder in your `PATH`.
+
+## Homebrew
+
+You can also install using `homebrew` with `brew install stuartleeks/tap/devcontainer`
+
+## Just give me a script
+
+Or if you just don't care and are happy to run random scripts from the internet:
+
+```bash
+export OS=linux # also darwin
+export ARCH=amd64 # also 386
+wget https://raw.githubusercontent.com/stuartleeks/devcontainer-cli/main/scripts/install.sh
+chmod +x install.sh
+sudo -E ./install.sh
+```
+
+## Enabling bash completion
+
+The `devcontainer completion <shell>` command generates a completion script for the specified shell. 
+
+To enable bash completion, add the following to you `~/.bashrc` file:
+
+```bash
+source <(devcontainer completion bash)
+```
+
+Or to alias `devcontainer` (to `dc` in this example):
+
+```bash
+alias dc=devcontainer
+complete -F __start_devcontainer dc
+```
+
+The `devcontainer completion <shell>` command accepts `bash`, `zsh`, and `powershell` for the `<shell>` parameter.

docs/open-in-code.md

@@ -0,0 +1,7 @@
+# devcontainer open-in-code
+
+The `devcontainer open-in-code` command opens the current folder in VS Code as a dev container, i.e. it skips the normal step of opening in VS Code and then clicking # on the "Re-open in container" prompt to reload the window as a dev container. With `devcontainer open-in-code` you get straight to the dev container!
+
+You can also use `devcontainer open-in-code <path>` to open a different folder as a devcontainer. 
+
+If you want to use the VS Code Insiders release, you can use `devcontainer open-in-code-insiders`.

docs/template.md

@@ -0,0 +1,92 @@
+# devcontainer template ...
+
+{:toc}
+
+## Setting up templates
+
+To use the `devcontainer template` commands you need to configure some templates.
+
+A good starting point is the the VS Code devcontainers repo. Choose a directory, and clone the repo using  `git clone https://github.com/microsoft/vscode-dev-containers`
+
+Next, we need to tell the `devcontainer` CLI to use this folder. If you haven't previously created a config file, run `devcontainer config write` to save a config file and then open `~/.devcontainer-cli/devcontainer-cli.json` in your favourite editor.
+
+The starting configuration will look something like:
+
+```json
+{
+  "templatepaths": []
+}
+```
+
+Update to include the path to the `containers` folder in the `vscode-dev-containers` repo you just cloned:
+
+```json
+{
+  "templatepaths": ["$HOME/source/vscode-dev-containers/containers"]
+}
+```
+
+## Listing templates
+
+Running `devcontainer template list` will show the templates that `devcontainer` discovered
+
+## Adding a devcontainer definition
+
+To add the files for a devcontainer definition to your project, change directory to the folder you want to add the devcontainer to and then run:
+
+```bash
+# Add the go template
+devcontainer template add go
+```
+
+This will copy in the template files for you to modify as you wish.
+
+## Adding a link to a devcontainer
+
+If you are working with a codebase that you don't want to commit the devcontainer definition to (e.g. an OSS project that doesn't want a devcontainer definition), you can use the `template add-link` command. Instead of copying template files it creates symlinks to the template files and adds a `.gitignore` file to avoid accidental git commits.
+
+As with `template add`, run this from the folder you want to add the devcontainer to:
+
+```bash
+# Symlink to the go template
+devcontainer template add-link go
+```
+
+See the [repository containers](#repository-containers) section for an alternative to template links.
+
+## Creating your own templates
+
+`devcontainer` can be configured to scan multiple folders to find templates. It is designed to work with folders structured in the same was as the [containers from in github.com/microsoft/vscode-dev-containers](https://github.com/microsoft/vscode-dev-containers/tree/master/containers), e.g.:
+
+
+```misc
+template-collection-folder
+ |-template1
+ |  |-.devcontainer
+ |  |  |-devcontainer.json
+ |  |  |-Dockerfile
+ |  |  |-<other content for the template>
+ |-misc-folder
+ |-<misc content that is ignored as there is no .devcontainer folder>
+ |-<README or other files that are ignore>
+```
+
+Assuming you cloned [github.com/microsoft/vscode-dev-containers/](https://github.com/microsoft/vscode-dev-containers/) into your `~/source/` folder and set up a custom devcontainer folder in `~/source/devcontainers` then you can configure your template paths as shown below. The sub-folder names are used as the template name and when duplicates are found the first matching folder is taken, so in the example below the `~/source/devcontainers` templates take precedence.
+
+```json
+{
+  "templatepaths": [
+    "$HOME/source/devcontainers",
+    "$HOME/source/vscode-dev-containers/containers"
+  ]
+}
+```
+
+## Repository containers
+
+VS Code dev containers have another feature called "Repository containers". These are a set of dev container definitions that VS Code will automatically apply to a project based on its git repo.
+
+The default definitions are in the [microsoft/vscode-dev-containers](https://github.com/microsoft/vscode-dev-containers/tree/master/repository-containers) repo. If you look at the repo, you will see a `github.com` folder followed by paths for `<org>/<repo>`, e.g. `django/django`. The `https://github.com/django/django` repo doesn't contain a dev container definition, but VS Code will use the repository container definition from the `microsoft/vscode-dev-containers` repo.
+
+You can also configure VS Code to look for additional local paths for repository containers by providing a value for the VS Code `remote.containers.repository-container-paths` setting (see [this issue](https://github.com/microsoft/vscode-remote-release/issues/3218) for more details). 
+