RocketChat/redoc

Name: redoc

Owner: Rocket.Chat

Description: redoc - generate documentation from multiple project repos.

Created: 2016-01-20 12:07:38.0

Updated: 2016-05-04 13:51:56.0

Pushed: 2016-05-05 20:32:03.0

Homepage:

Size: 3979

Language: HTML

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

redoc

redoc is a Meteor application that can be used to present styled markdown from multiple Github repositories.

redoc fetches content from GitHub and renders markdown, caching the HTML to be managed with a Table of Contents and stylized with theme packages.

clone https://github.com/reactioncommerce/redoc.git
edoc && npm install
or --settings settings.json

To run tests:

npm run test - run unit tests npm run test-app - run “full app” tests npm run chimp run browser tests (while app running) npm run chimp-watch run browser tests in watch mode (while app running)

redoc is the application used for the Reaction documentation.

redoc is using meteor 1.3, with imported npm dependencies. It also uses react and react-router to render HTML server-side for the docs.

Since we use this project to generate docs for Reaction Commerce, we've included our settings.json and redoc.json that we use to generate our documentation as an example.

Initialization

redoc is initialized with an array of repositories repos, and a Table of Contents, tocData array. These are defined in settings.json redoc.initRepoData.

settings.json example

ublic": {
"ga": {
  "account": ""
},
"gitter": {
  "room": "reactioncommerce/reaction"
},
"redoc": {
  "branch": "master",
  "publicBranches": [
    "master"
  ]
}

ervices": [{
"github": {
  "clientId": "",
  "secret": "",
  "webhook": {
    "updateDocs": ""
  }
}
,
edoc": {
"users": [
  {
    "username": "github_username",
    "roles": ["admin"]
  }
],
"initRepoData": {
  "repos": [{
    "org": "reactioncommerce",
    "repo": "reaction-docs",
    "label": "Reaction",
    "description": "Reaction Commerce Guide"
  }],
  "tocData": [{
    "class": "guide-nav-item",
    "alias": "intro",
    "label": "Introduction",
    "repo": "reaction-docs",
    "docPath": "index.md",
    "default": true
  }, {
    "class": "guide-sub-nav-item",
    "alias": "dashboard",
    "label": "Dashboard",
    "repo": "reaction-docs",
    "docPath": "admin/dashboard.md"
  }]
}

Document Structure

Documents is split into one of two sides. Left - Explanation Right - Examples

Heading levels (h1, h2, h3) create distinct sections. Heading level (h4) does not create a section, instead lives in the current heading section. Heading levels (h5, h6) create an example sub section within the current heading section.

The following example shows how this works:

 - (creates a section)
oduction Content

# h5 - (starts the example section for the h1)
ple Content
ple ends at the h2. h2 is a new section

2 - (creates a section)
ent for h2

# h5 - (starts the example section for the h2)
ple Content
ple ends at the h3. h3 is a new section

h3 - (creates a section)
ent for h3

 h4
 h4
 h4

# h5 - (starts the example section for the h3, h4's are not distinct sections)

graph
e

..

## h6 - (same effect as h5)
ent...
ple ends at the h3. h3 is a new section

h3
ent for h3
no example content. The right hand side will be empty, and thats OK.

The environment variable METEOR_SETTINGS can also be used.

Remote configuration

You can supply a url in initRepoData as well, and we'll fetch from the remote location.

oc": {
nitRepoData": "https://raw.githubusercontent.com/reactioncommerce/redoc/master/private/redoc.json"

initRepoData can also be an object defining the initRepoData.

TOC Example Data

epos": [{
"org": "reactioncommerce",
"repo": "reaction-docs",
"label": "Reaction",
"description": "Reaction Commerce Guide"
 {
"org": "reactioncommerce",
"class": "guide-sub-nav-item",
"repo": "reaction-braintree",
"label": "Braintree",
"docPath": "README.md"
 {
"class": "guide-sub-nav-item",
"org": "reactioncommerce",
"repo": "reaction-paypal",
"label": "Paypal",
"docPath": "README.md"

If you supply only a repo, the TOC data will be generated from the repo's folder/file structure.

Theme

To customize the theme, copy the packages/reaction-doc-theme to a new package folder, and update the packages.js with your new theme package name.

Gitter

Use Meteor.settings.public.gitter.room to configure the Gitter Sidecar room. To remove Gitter:

or remove reactioncommerce:redoc-gitter

Scheduling

Meteor.settings.redoc.schedule is configurable in settings.json, and defaults to “every 4 hours”.

This configures a schedule for flushing the collections and fetching updates.

Deployment

Although you can deploy Redoc with any of the deployment methods supported by Meteor, the recommended method is to use Docker. Redoc has several Dockerfiles to choose from that are intended for different use cases.

All Dockerfiles and the associated build scripts are in the docker/ directory. The default Dockerfile in the root of the project is an alias that points to docker/redoc.prod.docker (which is the recommended Dockerfile for production deployments). However, the production image builds from a base OS from scratch every time and will take a bit longer to build than the development image (found at docker/redoc.dev.docker). So when you're developing locally, you may prefer to have the faster build time that the development image gives you (by caching each build step layer). Just note that you don't ever want to use the development image for production because the image size is usually about 4x the size of the production image.

Build

The Docker build step is optional and is only required if you have a customized version of Redoc. If you haven't customized the app, skip to the next section.

To build your custom version of Redoc:

oduction image
er build -t <your org>/redoc .

 a local development image for quicker debugging
er build -f docker/redoc.dev.docker -t <your org>/redoc .

Once you have built a production image, you can push it to your Docker Hub account:

er push <your org>/redoc

Run

Running the official Redoc image (assuming you're using settings.json in the project root and an external MongoDB):

er run -d \
 80:80 \
 ROOT_URL='http://example.com' \
 MONGO_URL='mongodb://url...' \
 METEOR_SETTINGS='$(cat settings.json)' \
actioncommerce/redoc:latest

We've also provided an example Docker Compose config (docker-compose.yml) that can be used as a starting point if you'd like to use the official MongoDB image from Docker Hub.

c:
age: reactioncommerce/redoc:latest
rts:
- 80:80
nks:
- mongo
start: always
vironment:
ROOT_URL: "http://example.com" # set to your domain name
MONGO_URL: "mongodb://mongo:27017/redoc" # this is fine as-is
METEOR_SETTINGS: # provide a JSON stringified version of your settings.json here

o:
age: mongo:latest
start: always
mmand: mongod --storageEngine=wiredTiger

Once you've added your METEOR_SETTINGS, you can then run start up the containers with:

er-compose up -d

Once the containers have started, your app should be linked to the mongo container and serving content on port 80.