docs: usage guide via slate (#536)

* add Slate-based "Inertia Usage" documentation and build scripts * add `docs` and `run-docs` targets to Makefile * update `make clean` to remove docs_build * remove now redundant parts from README (since a lot of content is in the usage guide now) * add 'why use inertia' to README * add CNAME to point `inertia.ubclaunchpad.com` to GH-pages in `/docs` * add documentation issue template * add section on building documentation in CONTRIBUTING.md
ubclaunchpad · Feb 9, 2019 · 40bfc25 · 40bfc25
1 parent 680e21d
commit 40bfc25
Show file tree

Hide file tree

Showing 30 changed files with 2,213 additions and 98 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -6,3 +6,6 @@
 *.png binary
 *.jpg binary
 *.pdf binary
+
+# Mark docs as generated
+docs/* linguist-generated
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md → .github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug_report.md → .github/ISSUE_TEMPLATE/bug-report.md
diff --git a/.github/ISSUE_TEMPLATE/doc-issue.md b/.github/ISSUE_TEMPLATE/doc-issue.md
@@ -0,0 +1,15 @@
+---
+name: Documentation issue
+about: Let us know if something is wrong with our documentation!
+title: 'docs: '
+labels: 'type: docs :book:'
+assignees: ''
+
+---
+
+**Describe the issue**
+A clear and concise description of what the issue is.
+
+**Additional context**
+Add any other context about the problem here, such as screenshots and links to
+relevant documentation.
diff --git a/.gitignore b/.gitignore
@@ -40,3 +40,6 @@ public/
 
 # JetBrains
 .idea
+
+# Doc build
+docs_build
diff --git a/.scripts/build_docs.sh b/.scripts/build_docs.sh
@@ -0,0 +1,68 @@
+#! /bin/bash
+
+set -e
+
+###
+# This script is a wonderful hack I made to get around the fact that Slate
+# (https://github.com/lord/slate) documentation recommends that you fork the
+# repository and then write your documentation inside it.
+#
+# To convert Slate into a pure "doc builder", this script does a few things:
+#   * clone my (Robert's) fork of Slate into temporary /docs_build
+#   * write and sed custom configuration into the repository
+#   * symlink our doc assets (primarily in /docs_src, but also a few image assets
+#     from .static) into the cloned Slate repository
+#   * build the documentation into /docs, which is deployed by GH-pages
+#
+# The symlink + config hacks also allows live-reload local dev deployment (using
+# the 'make run-docs' target in /Makefile).
+###
+
+# Get Slate
+echo "[INFO] Getting Slate"
+mkdir -p docs_build
+cd docs_build
+if [ ! -d slate ]; then
+  # Using Robert's fork for now, for extra swag and configuration options not
+  # available in vanilla Slate
+  git clone https://github.com/bobheadxi/slate.git
+else
+  echo "[INFO] Slate already present in docs_build/slate"
+fi
+
+# Add custom config to Slate
+echo "[INFO] Hacking Slate configuration"
+TEMPLATE_FILES_WATCH="files.watch :source, path: File.join(root, '../../docs_src')"
+if ! grep -q "$TEMPLATE_FILES_WATCH" slate/config.rb ; then
+  # We want to symlink our doc assets into the repo, so to retain live reload
+  # functionality, we want the generator Slate uses (Middleman) to watch our
+  # symlink sources for changes too
+  echo "$TEMPLATE_FILES_WATCH" \
+    >> slate/config.rb
+fi
+if ! grep -q "<%= favicon_tag 'favicon.ico' %>" slate/source/layouts/layout.erb ; then
+  # This inserts a favicon reference into the <head /> element of the
+  # documentation layout
+  sed -i '' '/<head>/a\
+  <%= favicon_tag '\''favicon\.ico'\'' %>
+  ' slate/source/layouts/layout.erb
+fi
+
+# Set up Slate for build
+echo "[INFO] Linking assets"
+ln -fs "$(dirname "$(pwd)")"/docs_src/index.html.md \
+  slate/source/index.html.md
+ln -fs "$(dirname "$(pwd)")"/docs_src/stylesheets/_variables.scss \
+  slate/source/stylesheets/_variables.scss
+ln -fs "$(dirname "$(pwd)")"/.static/inertia.png \
+  slate/source/images/logo.png
+ln -fs "$(dirname "$(pwd)")"/.static/favicon.ico \
+  slate/source/images/favicon.ico
+echo "[INFO] Installing Slate dependencies"
+cd slate
+bundle install
+
+# Execute build
+echo "[INFO] Building documentation"
+rm -rf docs
+bundle exec middleman build --clean --build-dir=../../docs
diff --git a/.static/favicon.ico b/.static/favicon.ico
diff --git a/.static/inertia.png b/.static/inertia.png
diff --git a/CNAME b/CNAME
@@ -1 +1 @@
-inertia.ubclaunchpad.com
+inertia.ubclaunchpad.com
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -178,6 +178,18 @@ $> make web-run    # run local instance of application
 
 Make sure you have a local daemon set up for this web app to work - see the previous section for more details.
 
+### Documentation
+
+Our [usage documentation website]() is built with [Slate](https://github.com/lord/slate).
+The builds are in `/docs`, but the documentation source is in `/docs_src`.
+
+To build and deploy the documentation locally:
+
+```bash
+$> make docs
+$> make run-docs # visit http://localhost:4567/
+```
+
 ## Setting up a Testing Environment
 
 You will need Docker installed and running to run whole the Inertia test suite,

diff --git a/Makefile b/Makefile
@@ -16,6 +16,7 @@ ls:
 clean: testenv-clean
 	go clean -testcache
 	rm -f ./inertia
+	rm -rf ./docs_build
 	find . -type f -name inertia.\* -exec rm {} \;
 
 # Install all dependencies
@@ -182,3 +183,11 @@ web-run-sandbox:
 .PHONY: web-build
 web-build:
 	(cd ./daemon/web; npm install --production; npm run build)
+
+.PHONY: docs
+docs:
+	sh .scripts/build_docs.sh
+
+.PHONY: run-docs
+run-docs:
+	( cd docs_build/slate ; bundle exec middleman server --verbose )
diff --git a/README.md b/README.md
@@ -41,7 +41,7 @@
 <br>
 
 <p align="center">
-  <a href="#package-getting-started"><strong>Getting Started</strong></a> · 
+  <a href="#package-usage"><strong>Usage</strong></a> · 
   <a href="#bulb-motivation-and-design"><strong>Motivation & Design</strong></a> · 
   <a href="#books-contributing"><strong>Contributing</strong></a> · 
   <a href="https://github.com/ubclaunchpad/inertia/wiki"><strong>Wiki</strong></a>
@@ -71,107 +71,24 @@ Inertia is a simple cross-platform command line application that enables quick a
 
 <br>
 
-# :package: Getting Started
+# :package: Usage
 
-All you need to get started is a [compatible project](https://github.com/ubclaunchpad/inertia/wiki/Project-Compatibility), the Inertia CLI, and access to a virtual private server. 
+Check out our new **[Inertia Usage Guide](https://inertia.ubclaunchpad.com)** to
+get started with using Inertia for your project! The guide will walk you through
+installing Inertia, setting up a project, deploying to a remote, managing your
+deployment, and advanced usage tips.
 
-MacOS users can install the CLI using [Homebrew](https://brew.sh):
+### Why Use Inertia?
 
-```bash
-$> brew install ubclaunchpad/tap/inertia
-```
+If you...
 
-Windows users can install the CLI using [Scoop](http://scoop.sh):
+* want a simple utility to quickly build and deploy the latest iterations of your projects
+* are new to the concept of "deployment" and related tooling
+* are not deploying to production
+* are on a tight budget and need to switch between cloud providers as your free trials run out
+* want some lightweight team features for managing your deployment
 
-```bash
-$> scoop bucket add ubclaunchpad https://github.com/ubclaunchpad/scoop-bucket
-$> scoop install inertia
-```
-
-For other platforms, you can [download the appropriate binary from the Releases page](https://github.com/ubclaunchpad/inertia/releases).
-
-### Setup
-
-Initializing a project for use with Inertia only takes a few simple steps:
-
-```bash
-$> inertia init
-```
-
-#### Using an Existing Remote
-
-To use an existing host, you must first add it to your Inertia configuration and initialize it - this will install Inertia on your remote.
-
-```bash
-$> inertia remote add $VPS_NAME
-$> inertia $VPS_NAME init
-$> inertia $VPS_NAME status
-# Confirms that the daemon is online and accepting requests
-```
-
-See our [wiki](https://github.com/ubclaunchpad/inertia/wiki/VPS-Compatibility) for more details on VPS platform compatibility.
-
-#### Provisioning a New Remote
-
-Inertia offers some tools to easily provision a new VPS instance and set it up for Inertia. For example, to create an EC2 instance and initialize it, just run:
-
-```bash
-$> inertia provision ec2 $VPS_NAME
-$> inertia $VPS_NAME status
-```
-
-### Deployment Management
-
-To manually deploy your project, you must first grant Inertia permission to clone your repository. This can be done by adding the GitHub Deploy Key that is displayed in the output of `inertia $VPS_NAME init` to your repository settings:
-
-```bash
-GitHub Deploy Key (add here https://www.github.com/<your_repo>/settings/keys/new):
-ssh-rsa <...>
-```
-
-Once this is done, you can use Inertia to bring your project online on your remote VPS:
-
-```bash
-$> inertia $VPS_NAME up
-```
-
-Run `inertia $VPS_NAME --help` to see the other commands Inertia offers for managing your deployment.
-
-Inertia also offers a web application - this can be accessed at `https://$ADDRESS:4303/web` once users have been added through the `inertia $VPS_NAME user` commands.
-
-### Continuous Deployment
-
-To enable continuous deployment, you need the webhook URL that is printed during `inertia $VPS_NAME init`:
-
-```bash
-GitHub WebHook URL (add here https://www.github.com/<your_repo>/settings/hooks/new):
-http://myhost.com:4303/webhook
-Github WebHook Secret: inertia
-``` 
-
-The daemon will accept POST requests from GitHub at the URL provided. Add this webhook URL in your GitHub settings area (at the URL provided) so that the daemon will receive updates from GitHub when your repository is updated. Once this is done, the daemon will automatically build and deploy any changes that are made to the deployed branch.
-
-### Release Streams
-
-The version of Inertia you are using can be seen in Inertia's `.inertia.toml` configuration file, or by running `inertia --version`. The version in `.inertia.toml` is used to determine what version of the Inertia daemon to use when you run `inertia $VPS_NAME init`.
-
-You can manually change the daemon version used by editing the Inertia configuration file. If you are building from source, you can also check out the desired version and run `make inertia-tagged` or `make RELEASE=$STREAM`. Inertia daemon releases are tagged as follows:
-
-- `v0.x.x` denotes [official, tagged releases](https://github.com/ubclaunchpad/inertia/releases) - these are recommended.
-- `latest` denotes the newest builds on `master`.
-- `canary` denotes experimental builds used for testing and development - do not use this.
-
-The daemon component of an Inertia release can be patched separately from the CLI component - see our [wiki](https://github.com/ubclaunchpad/inertia/wiki/Daemon-Releases) for more details.
-
-### Swag
-
-Add some bling to your Inertia-deployed project :sunglasses: 
-
-[![Deployed with Inertia](https://img.shields.io/badge/deploying%20with-inertia-blue.svg)](https://github.com/ubclaunchpad/inertia)
-
-```
-[![Deployed with Inertia](https://img.shields.io/badge/deploying%20with-inertia-blue.svg)](https://github.com/ubclaunchpad/inertia)
-```
+Inertia might be for you!
 
 <br><br>
 

diff --git a/docs/fonts/slate.eot b/docs/fonts/slate.eot
diff --git a/docs/fonts/slate.svg b/docs/fonts/slate.svg
diff --git a/docs/fonts/slate.ttf b/docs/fonts/slate.ttf
diff --git a/docs/fonts/slate.woff b/docs/fonts/slate.woff
diff --git a/docs/fonts/slate.woff2 b/docs/fonts/slate.woff2
diff --git a/docs/images/aws-ec2-iam-add.png b/docs/images/aws-ec2-iam-add.png
diff --git a/docs/images/aws-ec2-iam-perm.png b/docs/images/aws-ec2-iam-perm.png
diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico
diff --git a/docs/images/logo.png b/docs/images/logo.png
diff --git a/docs/images/navbar.png b/docs/images/navbar.png