==============================================
Important Notice: This repo is no longer in use. For the current Concourse documentation using MKDocs, see https://github.com/pivotal/docs-concourse-pcf
==============================================
This repository contains documentation for Pivotal Concourse, the Pivotal supported version of OSS Concourse. It is a CI/CD tool that is also effective for continuously deploying and managing Pivotal Cloud Foundry (PCF).
https://github.com/pivotal-cf/docs-book-concourse-olm
Branch name | Use for… | Currently lives… |
---|---|---|
master | Originally the next version in development (6.x) | |
5.x | Previously published branch (5.2.0) | |
4.x | Previously published branch (4.0.0) | |
3.x | Previously published branch |
There are two pipelines for this doc at the moment: Edge (Staging):https://concourse.run.pivotal.io/teams/cf-docs/pipelines/cf-services-edge?groups=concourse-edge
Production (Public): https://concourse.run.pivotal.io/teams/cf-docs/pipelines/cf-services?groups=concourse-olm
Changes to the master branch in this repo appear here: Staging: http://docs-pcf-staging.cfapps.io/p-concourse/6-x/index.html
Production (public): https://docs.pivotal.io/p-concourse/5-x/index.html - Making changes public requires a manual push to production.
If you are not on the docs team, please make edits to this repo through PR's. Follow the instructions in this document: https://docs.google.com/document/d/14Go0uCj20BFMBzL2ddEKsZp-GONhVp0yr2cEFSskWnQ/edit?usp=sharing
Bookbinder is a command-line utility for stitching Markdown docs into a hostable web app. The PCF Docs Team uses Bookbinder to publish our docs site, but you can also use Bookbinder to view a live version of your documentation on your local machine.
Bookbinder draws the content for the site from docs-content
, the subnav from docs-book
, and various layout configuration and assets from docs-layout
.
To use Bookbinder to view your documentation, perform the following steps:
- Install Bookbinder by running
gem install bookbindery
. If you have trouble, consult the Zero to Bookbinder section to make sure you have the correct dependencies installed. - On your local machine,
cd
intodocs-book
in the cloned repo. - Run
bundle install
to make sure you have all the necessary gems installed. - Build your documentation site with
bookbinder
in one of the two following ways:- Run
bundle exec bookbinder watch
to build an interactive version of the docs and navigate tolocalhost:4567/myservice/
in a browser. (It may take a moment for the site to load at first.) This builds a site from your content repo atdocs-content
, and then watches that repo to update the site if you make any changes to the repo. - Run
bundle exec bookbinder bind local
to build a Rack web-app of the book. After the bind has completed,cd
into thefinal_app
directory and runrackup
. Then navigate tolocalhost:9292/myservice/
in a browser.
- Run
If you are reading this, Pivotal has invited you to a git repo where you can build and edit documentation in the Ruby / Markdown / HTML format that the online publishing tool Bookbinder uses to build Pivotal's documentation.
Here's how to install Bookbinder and build your docs from the repo, starting from scratch, on a Mac OS X machine.
Note: All steps below are implicitly preceded with, "If you haven't already..." You should skip any installation steps that have already contributed to your environment.
In Terminal window:
-
Make and
cd
into a workspace directory.$ mkdir workspace
$ cd workspace
-
Follow the instructions at
http://brew.sh
to install brew / homebrew$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
-
Install your own (non-system) ruby.
$ brew install ruby
-
Download and Install git by following the instructions at git-scm.com.
-
Install your own (non-system) bash-completion (optional).
$ brew install git bash-completion
-
If you don't already have one, generate a public/private RSA key pair, and save the key to your
~/.ssh
directory.$ ssh-keygen Generating public/private rsa key pair. Enter file in which to save the key (/Users/pspinrad/.ssh/id_rsa):
-
Get a Github account.
-
Add your RSA public key to your Github account / profile page.
$ cat ~/.ssh/id_rsa.pub # copy and paste this into Github profile page as new key
-
Install a Ruby manager such as chruby.
$ brew install chruby
-
Add your Ruby manager to your
~/.bashrc
by appending the following line:source /usr/local/opt/chruby/share/chruby/chruby.sh
-
Install the
ruby-install
installer.$ brew install ruby-install
-
Run
ruby-install
to install Ruby 2.3.0.$ ruby-install ruby 2.3.0
-
Select the following Ruby version.
chruby ruby-2.3.0
-
Install
bundler
.$ gem install bundler
-
Install bookbinder (the
bookbindery
gem).$ gem install bookbindery
-
Clone the docs template repo you will be building from.
$ git clone git@github.com:pivotal-cf/docs-partners-template
-
cd
into thebook
subdirectory of the repo.$ cd docs-partners-template/docs-book
-
Run
bundle install
to install all book dependencies.$ bundle install
-
Run
bundle exec bookbinder watch
to build the book on your machine.$ bundle exec bookbinder watch
-
Browse to
localhost:4567
to view the book locally and "watch" any changes that you make to sourcehtml.md.erb
files. As you make and save changes to the local source files for your site, you will see them in your browser after a slight delay. -
After each session of writing or revising your docs source files, commit and push them to your github repo.
Happy documenting!