Enable devcontainer (home-assistant#490)

Co-Authored-By: Franck Nijhof <[email protected]>

.devcontainer/Dockerfile

@@ -0,0 +1,8 @@
+FROM node:lts
+
+WORKDIR /workspaces
+
+# Set an environment variable to be able to detect we are in dev container
+ENV NODE_ENV=devcontainer
+
+EXPOSE 3000

.devcontainer/devcontainer.json

@@ -0,0 +1,29 @@
+{
+    "name": "developers.home-assistant",
+    "dockerFile": "Dockerfile",
+    "appPort": [
+        3000
+    ],
+    "postCreateCommand": "yarn install",
+    "extensions": [
+        "davidanson.vscode-markdownlint",
+        "editorconfig.editorconfig",
+        "streetsidesoftware.code-spell-checker",
+        "yzhang.markdown-all-in-one"
+    ],
+    "settings": {
+        "editor.rulers": [80, 100, 120],
+        "editor.renderWhitespace": "boundary",
+        "errorLens.gutterIconsEnabled": true,
+        "errorLens.addAnnotationTextPrefixes": false,
+        "errorLens.enabledDiagnosticLevels": [
+            "error",
+            "warning"
+        ],
+        "terminal.integrated.shell.linux": "/bin/bash",
+        "[markdown]":{
+            "editor.wordWrap": "wordWrapColumn",
+            "editor.wordWrapColumn": 80,
+        }
+    }
+}

.npmrc

@@ -0,0 +1 @@
+scripts-prepend-node-path=true

.vscode/cSpell.json

@@ -0,0 +1,48 @@
+// cSpell Settings
+// Contains additional words for our project
+{
+    "version": "0.1",
+    "language": "en",
+    "words": [
+        "arest",
+        "automations",
+        "bloomsky",
+        "bluesound",
+        "BTLE",
+        "Denon",
+        "endconfiguration",
+        "endraw",
+        "Etekcity",
+        "fitbit",
+        "Flexit",
+        "geizhals",
+        "Harman",
+        "hass",
+        "Hass.io",
+        "HassOS",
+        "hcitool",
+        "heos",
+        "hikvision",
+        "Homematic",
+        "IBAN",
+        "icloud",
+        "kardon",
+        "macos",
+        "Modbus",
+        "Mosquitto",
+        "nginx",
+        "ohmconnect",
+        "Onkyo",
+        "paulus",
+        "templating",
+        "waqi",
+        "Webhook"
+    ],
+    // flagWords - list of words to be always considered incorrect
+    // This is useful for offensive words and common spelling errors.
+    // For example "hte" should be "the"
+    "flagWords": [
+        "hte",
+        "asssistant"
+    ]
+}

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+    "recommendations": [
+        "davidanson.vscode-markdownlint",
+        "editorconfig.editorconfig",
+        "streetsidesoftware.code-spell-checker",
+        "yzhang.markdown-all-in-one"
+    ]
+}

.vscode/tasks.json

@@ -0,0 +1,23 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Generate",
+            "type": "shell",
+            "command": "yarn build",
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "Preview",
+            "type": "shell",
+            "command": "yarn start",
+            "group": {
+                "kind": "test",
+                "isDefault": true,
+            }
+        },
+    ]
+}

README.md

@@ -6,29 +6,82 @@ This is the source for the [Home Assistant Development documentation](https://de
 
 ## Updating the docs
 
-Documentation is build using [Docusaurus](https://docusaurus.io/docs/en/doc-markdown.html).
+Documentation is built using [Docusaurus](https://v2.docusaurus.io/).
 
-### Preparing environment
+## Editing on GitHub
+
+Small changes to text can be made directly on GitHub. At the bottom of each page there is an "Edit This Page" link which will load the document in GitHub ready for changes. This method doesn't easily allow for additional documents or images to be added.
+
+### Preparing a local environment
+
+There are two options for developing the documentation on a local system.
+
+#### Visual Studio Code and devcontainer
+
+The easiest way to get started with development is to use Visual Studio Code with devcontainers. This approach will create a preconfigured development environment with all the tools you need. This approach is enabled for all Home Assistant repositories.
+
+##### Prerequisites
+
+- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+- Docker
+  - For Linux, macOS, or Windows 10 Pro/Enterprise/Education use the [current release version of Docker](https://docs.docker.com/install/)
+  - Windows 10 Home requires [WSL 2](https://docs.microsoft.com/windows/wsl/wsl2-install) and the current Edge version of Docker Desktop (see instructions [here](https://docs.docker.com/docker-for-windows/wsl-tech-preview/)). This can also be used for Windows Pro/Enterprise/Education.
+- [Visual Studio code](https://code.visualstudio.com/)
+- [Remote - Containers (VSC Extension)][extension-link]
+
+[More info about requirements and devcontainer in general](https://code.visualstudio.com/docs/remote/containers#_getting-started)
+
+[extension-link]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers
+
+##### Getting started
+
+1. Fork the repository.
+2. Clone the repository to your computer.
+3. Open the repository using Visual Studio code.
+
+When you open this repository with Visual Studio code you are asked to "Reopen in Container", this will start the build of the container.
+
+_If you don't see this notification, open the command palette and select `Remote-Containers: Reopen Folder in Container`._
+
+##### Tasks
+
+The devcontainter comes with some useful tasks to help you with development, you can start these tasks by opening the command palette and select `Tasks: Run Task` then select the task you want to run.
+
+When a task is currently running (like `Preview` for the docs), it can be restarted by opening the command palette and selecting `Tasks: Restart Running Task`, then select the task you want to restart.
+
+When using devcontainers and starting a preview via `yarn start`, `script/setup` or the Task in Code, a browser window will not be opened automatically, instead you will need to open a browser window to [localhost:3000](http://localhost:3000). If port 3000 was already in use, Docusaurus will use the next available port. You can check the port used in the terminal window of Visual Studio Code. Look for the line `Project is running at http://0.0.0.0:XXXX/` where `XXXX` 3000 or greater, open a browser window to `<http://localhost:XXXX>`.
+
+#### Setting Up Your Own Environment
 
 Running the documentation locally requires [NodeJS](https://nodejs.org/en/) and [Yarn](https://yarnpkg.com/) to be installed. Inside a cloned fork of this repository, run:
 
 ```bash
 $ script/setup
 ```
 
-This will install [docusaurus](https://www.npmjs.com/package/docusaurus) amongst other things.
+Or in Windows, just run:
+
+```bash
+yarn
+```
 
-### Running docs locally
+This will install [docusaurus](https://github.com/facebook/docusaurus#readme) amongst other things.
+
+##### Running docs locally
 
 ```bash
 $ script/server
 ```
 
-It will start a server at [localhost:3000](http://localhost:3000). You will need to navigate to the `next` version of the docs to see your changes applied. To do so click on the version number in the header and select `next` -> `Documentation`.
+In Windows, just run
+
+```bash
+yarn start
+```
+
+It will start a server at [localhost:3000](http://localhost:3000).
 
 ### Adding a page
 
 - Create new page in `docs/`
-- Add new doc to `website/sidebars.json`
-
-You will need to restart the server when creating a new file or make changes to `sidebars.json`. If you're updating a document, you will only need to refresh your browser to get the latest changes.
+- Add new doc to `sidebars.js`

package.json

@@ -3,14 +3,17 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "start": "docusaurus start",
+    "start": "by-node-env",
+    "start:development": "docusaurus start",
+    "start:devcontainer": "docusaurus start --poll --host 0.0.0.0",
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy"
   },
   "dependencies": {
-    "@docusaurus/core": "^2.0.0-alpha.54",
+    "by-node-env": "^2.0.1",
     "@docusaurus/preset-classic": "^2.0.0-alpha.54",
+    "@docusaurus/core": "^2.0.0-alpha.54",
     "classnames": "^2.2.6",
     "react": "^16.13.1",
     "react-dom": "^16.13.1"