Skip to content

Commit

Permalink
Add containerized hosting
Browse files Browse the repository at this point in the history
  • Loading branch information
zfields committed May 20, 2019
1 parent b9d9c74 commit b8149aa
Show file tree
Hide file tree
Showing 3 changed files with 251 additions and 37 deletions.
23 changes: 23 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Base image
FROM node:10.14.1-slim

# Setup Build Environment
ARG DEBIAN_FRONTEND=noninteractive

# Setup Environment
## (optional) speeds up the build if you don't need the search
ENV SEARCH_INDEX 0

# Install dependencies
RUN ["dash", "-c", "\
apt-get update \
&& apt-get install --no-install-recommends -y \
git \
&& rm -rf /var/lib/apt/lists/* \
"]

# Setup execution environment
WORKDIR /particle-iot/docs

# Execution Environment
ENTRYPOINT ["./particle-docs"]
125 changes: 88 additions & 37 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,52 +1,96 @@
## Particle Documentation [![Build Status](https://travis-ci.org/particle-iot/docs.svg?branch=master)](https://travis-ci.org/particle-iot/docs)
Particle Documentation [![Build Status](https://travis-ci.org/particle-iot/docs.svg?branch=master)](https://travis-ci.org/particle-iot/docs)
======================

Here you'll find the documentation for the Particle platform, including
the Particle Device Cloud, Photon, Electron, and Spark Core.

To view this documentation, visit [our website](https://docs.particle.io), where the documentation is hosted.

### Installation
Local Hosting
-------------

To host this documentation locally, you'll need Node.js and npm (see the `engines` section of `package.json` for the exact versions):
This documentation uses a fabulous tool from the folks at Segment called [Metalsmith](http://www.metalsmith.io). Metalsmith is a static site generator that builds static HTML sites from source material in other formats; in this case, Markdown and Handlebars.

brew install nodejs
To set up a server running at `http://localhost:8080`, follow the installation instructions below...

Once you have Node.js set up, navigate to this repository's directory on your machine, and then:
> _**NOTE:** Any changes made to the source content should be automatically picked up by the browser via `livereload`._
npm install
### Containerized Hosting

to install any other necessary dependencies.
If you have Docker installed, then you can simply run the following commands to get started...

### Hosting locally
```none
$ alias particle-docs="docker run --interactive --mount type=bind,source=<local particle-iot/docs>,target=/particle-iot/docs --net host --rm --tty particle/docs"
$ particle-docs --help
usage: particle-docs [--build] [--deploy] [--run-tests] [--spell-check]
This documentation uses a fabulous tool from the folks at Segment called [Metalsmith](http://www.metalsmith.io). Metalsmith is a static site generator that builds static HTML sites from source material in other formats; in this case, Markdown and Handlebars.
Build, test and deploy a local documentation server.
To run a locally hosted version of the documentation, follow the installation instructions above, and then within the 'docs' directory type in your terminal:
-b, --build Build and install documentation packages.
-d, --deploy Launch documentation server at https://localhost:8080.
-h, --help Display this help and exit.
-s, --spell-check Run the spell-checker to verify spelling and update dictionary file.
-t, --run-tests Run CI tests.
NOTE: If no options are specified, then ALL options will be selected.
```
export SEARCH_INDEX=0 # optional. speeds up the build if you don't need the search
npm start

_**NOTE:** Before running the `alias` command, be sure to replace `<local particle-iot/docs>` with the absolute path to your local documentation repository._

### Bare-metal Hosting

#### Device Setup

To host this documentation locally, you'll need Node.js and npm (see the `engines` section of `package.json` for the exact versions):

```none
brew install nodejs
```

Once you have Node.js set up, navigate to the `docs` directory on your machine, and use the following commands:

#### Install Dependencies

To install any other necessary dependencies, run:

```none
npm install
```

#### Spell checking

To check the spelling of all Markdown files, run:

```none
npm run spell
```

This will set up a server running at `http://localhost:8080`. If you make changes to the source content, your browser should automatically refresh using `livereload`.
#### Testing

### Spell checking
To run the tests locally, run:

To check the spelling of all Markdown files, run `npm run spell`.
```none
npm test
```

### Testing
The result will indicate whether the build will pass Travis CI.

To run the tests locally, run `npm test` from the root of the
repository. This will tell you whether the build will pass on Travis or
not.
#### Deployment

### Deployment
```none
export SEARCH_INDEX=0 # optional. speeds up the build if you don't need the search
npm start
```

Updating Production Documention
-------------------------------

When updated documentation is pushed to the master branch, it is automatically pushed to Amazon S3 by Travis CI.
When updated documentation is pushed to the `master` branch, it is automatically pushed to Amazon S3 by Travis CI.

To see the latest build, visit the [Travis CI page](https://travis-ci.org/particle-iot/docs).

### Organization
Organization
------------

The majority of the content herein is stored in the `src/content` directory as a set of Markdown files. Assets such as images and javascript are stored in the `src/assets` directory.

Expand All @@ -68,14 +112,16 @@ If you are working on a page that has device-specific content, the
first thing you need to do is add the relevant device names to the
front-matter of the MD file, like this:

```
```markdown
devices: [ photon, electron, core ]
```

Where Photon, Electron and Core are the relevant devices to this page.

Then add a new key to [`device_features.json`](config/device_features.json) for each device that
supports the feature:
```

```markdown
{
"Core": [
...
Expand All @@ -92,7 +138,8 @@ supports the feature:
```

Then, in the body of the page, you can specify feature-specific content by using:
```

```markdown
{{#if has-backup-ram}}
## Backup RAM

Expand All @@ -104,7 +151,7 @@ For content that is exclusively for one device and where defining a new
feature name doesn't make sense (for example, which pins have PWM
support for a device), you can also device-specific content by using:

```
```markdown
{{#if photon}}
PHOTON SPECIFIC STUFFZ
{{/if}}
Expand All @@ -117,36 +164,39 @@ support for a device), you can also device-specific content by using:
ELECTRON SPECIFIC STUFFZ
{{/if}}
```

Prefer defining new feature names over using device-specific sections.

You can also insert the selected device name into text like this:
```

```none
Without a doubt, the {{device}} rocks!
```


### Adding a new device

When the firmware is available on a new device, add that device to the docs in these places:

- Make the firmware docs available for the new device by adding an entry to the `devices` frontmatter in <src/content/reference/firmware.md>
- Also update `devices` in the guides and tools frontmatter as appropriate
- Update the device selection dropdown in <templates/partials/header.hbs>
- Add the device in <src/assets/js> `rememberDevices()`
- Add a new SVG in <src/assets/image> named `<device>.svg`
- Tell the tests to crawl the new device page in <test/crawler.js>
* Make the firmware docs available for the new device by adding an entry to the `devices` frontmatter in <src/content/reference/firmware.md>
* Also update `devices` in the guides and tools frontmatter as appropriate
* Update the device selection dropdown in <templates/partials/header.hbs>
* Add the device in <src/assets/js> `rememberDevices()`
* Add a new SVG in <src/assets/image> named `<device>.svg`
* Tell the tests to crawl the new device page in <test/crawler.js>

### Redirects

When moving pages around or defining the default page for a section, add redirect links to [`redirects.json`](config/redirects.json).

### Attributions
Attributions
------------

Some of this documentation is derived from the [Arduino documentation](http://arduino.cc/en/Reference), as the Arduino/Wiring language and libraries are used extensively on the Spark Core.

This documentation was originally built using [Flatdoc](http://ricostacruz.com/flatdoc/), an awesome tool for building beautiful documentation from simple Markdown files. We have made many modifications since, but the inspiration remains.

### Contributions
Contributions
-------------

This documentation is managed by Particle, but supported by the community. We welcome contributions such as:

Expand All @@ -158,7 +208,8 @@ This documentation is managed by Particle, but supported by the community. We we

Making a contribution is as simple as forking this repository, making edits to your fork, and contributing those edits as a pull request. For more information on how to make a pull request, see [Github's documentation](https://help.github.com/articles/using-pull-requests/).

### License
License
-------

These files have been made available online through a [Creative Commons Attribution-ShareAlike 3.0 license](http://creativecommons.org/licenses/by-sa/3.0/us/).

Expand Down
140 changes: 140 additions & 0 deletions particle-docs
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
#!/bin/bash
set -o errexit -o pipefail -o noclobber -o nounset

function display_help ()
{
echo "\
usage: particle-docs [--build] [--deploy] [--run-tests] [--spell-check]
Build, test and deploy a local documentation server.
-b, --build Build and install documentation packages.
-d, --deploy Launch documentation server at https://localhost:8080.
-h, --help Display this help and exit.
-s, --spell-check Run the spell-checker to verify spelling and update dictionary file.
-t, --run-tests Run CI tests.
NOTE: If no options are specified, then ALL options will be selected.
"
}

# Utilized Enhanced `getopt`
! getopt --test > /dev/null
if [ ${PIPESTATUS[0]} -ne 4 ]; then
echo '\
`getopt --test` failed in this environment.
Please confirm "GNU getopt" is installed on this device.
'
exit 1
fi

OPTIONS=bdhst
LONGOPTS=build,deploy,help,spell-check,run-tests

# -use ! and PIPESTATUS to get exit code with errexit set
# -temporarily store output to be able to check for errors
# -activate quoting/enhanced mode (e.g. by writing out “--options”)
# -pass arguments only via -- "$@" to separate them correctly
! PARSED=$(getopt --options=$OPTIONS --longoptions=$LONGOPTS --name "$0" -- "$@")
if [ ${PIPESTATUS[0]} -ne 0 ]; then
# e.g. return value is 1
# then getopt has complained about wrong arguments to stdout
exit 2
fi

# Read getopt’s output this way to handle the quoting right:
eval set -- "$PARSED"

# Set default(s)
BUILD=false
DEPLOY=false
RUN_TESTS=false
SPELL_CHECK=false

# Parse parameter(s)
while true; do
case "$1" in
-b|--build)
BUILD=true
shift 1
;;
-d|--deploy)
DEPLOY=true
shift 1
;;
-h|--help)
shift
display_help
exit 0
;;
-s|--spell-check)
SPELL_CHECK=true
shift 1
;;
-t|--run-tests)
RUN_TESTS=true
shift 1
;;
--)
shift
break
;;
*)
echo "Encountered error while parsing arguments!"
exit 3
;;
esac
done

# Handle invalid arguments
if [ $# -ne 0 ]; then
echo "$0: Unknown argument \"$1\" supplied!"
exit 4
fi

# If no options were selected, then all options are selected
if [ $BUILD = false ] && [ $DEPLOY = false ] && [ $RUN_TESTS = false ] && [ $SPELL_CHECK = false ]; then
BUILD=true
DEPLOY=true
RUN_TESTS=true
SPELL_CHECK=true
fi

# Construct the Launch command
LAUNCH_COMMAND=""
CONCATENATION_REQUIRED=false

if [ $BUILD = true ]; then
if [ $CONCATENATION_REQUIRED = true ]; then
LAUNCH_COMMAND+=" && "
fi
LAUNCH_COMMAND+="npm install"
CONCATENATION_REQUIRED=true
fi

if [ $SPELL_CHECK = true ]; then
if [ $CONCATENATION_REQUIRED = true ]; then
LAUNCH_COMMAND+=" && "
fi
LAUNCH_COMMAND+="npm run spell"
CONCATENATION_REQUIRED=true
fi

if [ $RUN_TESTS = true ]; then
if [ $CONCATENATION_REQUIRED = true ]; then
LAUNCH_COMMAND+=" && "
fi
LAUNCH_COMMAND+="npm test"
CONCATENATION_REQUIRED=true
fi

if [ $DEPLOY = true ]; then
if [ $CONCATENATION_REQUIRED = true ]; then
LAUNCH_COMMAND+=" && "
fi
LAUNCH_COMMAND+="npm start"
CONCATENATION_REQUIRED=true
fi

echo $LAUNCH_COMMAND
eval $LAUNCH_COMMAND

0 comments on commit b8149aa

Please sign in to comment.