Merge pull request #165 from nsalminen/readme-instructions

Improve local development workflow/instructions

Author: nsalminen

README.md

@@ -132,28 +132,58 @@ code below:
 </html>
 ```
 
-### Development guide
+### Development Guide
 
-Follow the steps below to clone the repository and build XR Blocks:
+#### Setup
 
 ```bash
 # Clone the repository.
 git clone --depth=1 git@github.com:google/xrblocks.git
 cd xrblocks
 
-# Install dependencies.
+# Install dependencies and build the SDK.
 npm ci
+```
+
+After setup, either serve the samples and demos or develop locally, as
+described below.
+
+#### Serve samples and demos
+
+Serve the repository to view samples and demos through
+`http://localhost:8080/`:
+
+```bash
+# Serve the repository on http://localhost:8080
+npm run serve
+```
+
+#### Develop locally
 
-# Build xrblocks.js.
-npm run build
+For active SDK development, run watch mode and local serving together:
 
-# After making changes, check ESLint and run Prettier
+```bash
+# Build the SDK in watch mode and serve the repository on http://localhost:8080
+npm run dev
+```
+
+#### Linting and formatting
+
+XR Blocks uses ESLint for linting and Prettier for formatting. Run the
+following commands to check your code before submitting a pull request:
+
+```bash
 npm run lint # ESLint check
 npm run format # Prettier format
 ```
 
-XR Blocks uses ESLint for linting and Prettier for formatting.
-If coding in VSCode, make sure to install the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) and the [Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode). Then set Prettier as your default formatter.
+If you are using VS Code, install the
+[ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
+and the
+[Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode),
+then set Prettier as your default formatter.
+
+#### Notice
 
 This is not an officially supported Google product, but will be actively
 maintained by the XR Labs team and external collaborators. This project is not

demos/README.md

@@ -8,6 +8,13 @@ everyone so they may bring their ideas to life faster.
 For basic demo to demonstrate the use of a particular module, we suggest you
 submit to `/samples/`.
 
+## Running Demos Locally
+
+Follow the [development guide](../README.md#development-guide) to serve the
+repository, then open your demo path, for example:
+
+- `http://localhost:8080/demos/math3d/`
+
 ## Contributing a New Demo
 
 ### Step 1: Clone this repository and sign contributor agreement

docs/README.md

@@ -8,18 +8,18 @@ This website is built using [Docusaurus](https://docusaurus.io/).
 Start the development server for the documentation:
 
 ```bash
-# In the xrblocks/docs folder:
+# In the xrblocks/docs/ directory
 npm start
 ```
 
-For templates and samples in the documentation site to be loaded, a web server needs to be started in the `xrblocks` folder:
+This serves the documentation site locally at `http://localhost:3000/` and
+watches for changes to the documentation source files.
 
-```bash
-# In the xrblocks folder:
-npm run build
-http-server --cors
-```
+When viewing docs pages that embed templates or samples, **also** follow the
+[development guide](../README.md#development-guide) in the root README to serve
+the SDK on port 8080. Both servers can run simultaneously.
 
 ## Deployment
 
-The documentation site is automatically deployed to https://xrblocks.github.io/docs/ whenever it is updated in the [google/xrblocks](https://github.com/google/xrblocks) repository.
+The documentation site is automatically deployed to https://xrblocks.github.io/docs/
+whenever it is updated in the [google/xrblocks](https://github.com/google/xrblocks) repository.