Pivotal Cloud Foundry Partners Template
This template helps partners prepare documentation for Pivotal Cloud Foundry (PCF) partner services that appear on Pivotal Network.
Every partner service in PCF is documented on our PCF documentation site. The links to these partner service docs appear on the front page under Partner Services for Pivotal Cloud Foundry.
For a good example of a partner service doc, see ISS Knowtify Search Analytics.
Partners use this template to develop the documentation for their PCF service. This repo currently includes templates for the following topics:
- index.html.md.erb: The index of your docs.
- installing.html.md.erb: How to install and configure your product tile.
- using.html.md.erb: How to use your product.
- release-notes.html.md.erb: Release notes for your product.
To begin using this repo to develop your documentation, perform the following steps:
- Make a fork of this repo.
- Clone your fork onto your local machine.
- Work your way through each topic, replacing the placeholders in ALL-CAPS and following the instructions in bold.
- When writing your documentation, follow the guidelines in Style Notes for Tile Authors.
- Complete the subnav by replacing the placeholders in ALL-CAPS in the subnav file at
docs-book/master_middleman/source/subnavs/myservice_subnav.erbin this repo.
- View your documentation as a live local site in a browser, by following the steps below in the How To Use Bookbinder To View Your Docs section.
- When you've finished your documentation, make a pull request to merge your fork into this repo and email the PCF Docs Team at email@example.com.
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
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,
docs-bookin the cloned repo.
bundle installto make sure you have all the necessary gems installed.
- Build your documentation site with
bookbinderin one of the two following ways:
bundle exec bookbinder watchto build an interactive version of the docs and navigate to
localhost: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 at
docs-content, and then watches that repo to update the site if you make any changes to the repo.
bundle exec bookbinder bind localto build a Rack web-app of the book. After the bind has completed,
final_appdirectory and run
rackup. Then navigate to
localhost:9292/myservice/in a browser.
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:
cdinto a workspace directory.
$ mkdir workspace
$ cd workspace
Follow the instructions at
http://brew.shto 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
Set up Git
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-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
Get the Correct Ruby Version for Bookbinder: Ruby 2.3.0
Install a Ruby manager such as chruby.
$ brew install chruby
Add your Ruby manager to your
~/.bashrcby appending the following line:
$ brew install ruby-install
ruby-installto install Ruby 2.3.0.
$ ruby-install ruby 2.3.0
Select the following Ruby version.
$ gem install bundler
Install bookbinder (the
$ gem install bookbindery
Build the Docs Locally
Clone the docs template repo you will be building from.
$ git clone firstname.lastname@example.org:pivotal-cf/docs-partners-template
booksubdirectory of the repo.
$ cd docs-partners-template/docs-book
bundle installto install all book dependencies.
$ bundle install
bundle exec bookbinder watchto build the book on your machine.
$ bundle exec bookbinder watch
localhost:4567to view the book locally and "watch" any changes that you make to source
html.md.erbfiles. 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.
About Subnavs of Published Tile Documentation
After your tile documentation has been published, the subnav used for the live documentation is contained in this directory: https://github.com/pivotal-cf/docs-book-partners/tree/master/master_middleman/source/subnavs
However, you should also continue to maintain the local subnav file so that the subnav looks correct when you or a Pivotal writer builds your documentation locally with bookbinder for review or editing.
To edit a subnav for your tile documentation, follow these steps:
Make a pull request against the subnav file in https://github.com/pivotal-cf/docs-book-partners/tree/master/master_middleman/source/subnavs
Make the same changes in the subnav file (in /docs-book/master_middleman/source/subnavs/ of your tile repo) and make a pull request for that change too.