Skip to content
Permalink
Browse files

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
  • Loading branch information...
bobheadxi committed Feb 9, 2019
1 parent 680e21d commit 40bfc25c78e5110c690b379b96476f258d3d897b
@@ -6,3 +6,6 @@
*.png binary
*.jpg binary
*.pdf binary

# Mark docs as generated
docs/* linguist-generated
File renamed without changes.
@@ -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.
@@ -40,3 +40,6 @@ public/

# JetBrains
.idea

# Doc build
docs_build
@@ -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
BIN +4.19 KB .static/favicon.ico
Binary file not shown.
BIN +371 KB .static/inertia.png
Binary file not shown.
2 CNAME
@@ -1 +1 @@
inertia.ubclaunchpad.com
inertia.ubclaunchpad.com
@@ -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,
@@ -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 )
111 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>

BIN +1.83 KB docs/fonts/slate.eot
Binary file not shown.

Some generated files are not rendered by default. Learn more.

BIN +1.68 KB docs/fonts/slate.ttf
Binary file not shown.
BIN +1.75 KB docs/fonts/slate.woff
Binary file not shown.
BIN +796 Bytes docs/fonts/slate.woff2
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
BIN +371 KB docs/images/logo.png
Binary file not shown.
BIN +96 Bytes docs/images/navbar.png
Binary file not shown.

0 comments on commit 40bfc25

Please sign in to comment.
You can’t perform that action at this time.