pivotal-cf / docs-book-tiledev

PCF Services Documentation Template

This template helps Pivotal development teams prepare documentation for Pivotal Cloud Foundry (PCF) services that appear on Pivotal Network.

Breaking Change:

The 2.10 and later docs have been migrated to docs.vmware.com. For these branches, this repo is only being used for redirects located in the redirects.rb file.

For all files related to this documentation, including the table of contents (toc.md), see the content repo pivotal-cf/docs-tiledev.

Overview

Every PCF service has (or should have) documentation on the main Pivotal documentation site, docs.pivotal.io under Pivotal Cloud Foundry Services.

How To Use This Template

You can use this template to develop documentation for a new PCF service. It includes sections for a Product Snapshot, prerequisites, instructions for installation and use, release notes, license information, and other generally useful and expected documentation.

To begin using this repo to develop your documentation, perform the following steps:

1. Clone this repo onto your local machine.
2. Work your way through each topic, replacing the placeholders in ALL-CAPS and following the instructions in bold.
3. Complete the subnav by replacing the placeholders in ALL-CAPS in the subnav file at book/master_middleman/source/subnavs/service_subnav.erb in this repo.
4. 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.
5. When you've finished your documentation, push your docs up to the remote and email the PCF Docs Team at [email protected].

How To Use Bookbinder To View Your Docs

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:

1. On your local machine, cd into docs-book in the cloned repo.
2. Run bundle install to make sure you have all the necessary gems installed.
3. Build your documentation site with bookbinder in one of the two following ways:
   • Run bookbinder watch to 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.
   • Run bookbinder bind local to build a Rack web-app of the book. After the bind has completed, cd into the final_app directory and run rackup. Then navigate to localhost:9292/myservice/ in a browser.

Zero to Bookbinder: How to Install Bookbinder and Build, View, and Edit Your Docs from Nothing

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.

Install Ruby

In Terminal window:

1. Make and cd into a workspace directory.

   $ mkdir workspace

   $ cd workspace

2. 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)"

3. Install your own (non-system) ruby.

   $ brew install ruby

Set up Git

1. Download and Install git by following the instructions at git-scm.com.

2. Install your own (non-system) bash-completion (optional).

   $ brew install git bash-completion

3. 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/YOUR-USERID/.ssh/id_rsa):
   

4. Get a Github account.

5. 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

1. Install a Ruby manager such as chruby.

   $ brew install chruby

2. Add your Ruby manager to your ~/.bashrc by appending the following line:

   source /usr/local/opt/chruby/share/chruby/chruby.sh

3. Install the ruby-install installer.

   $ brew install ruby-install

4. Run ruby-install to install Ruby.

   $ ruby-install ruby 2.3

Install Bookbinder

1. Install bundler.

   $ gem install bundler

2. Install bookbinder (the bookbindery gem).

   $ gem install bookbindery

Build the Docs Locally

1. Clone the docs template repo you will be building from.

   $ git clone [email protected]:pivotal-cf-experimental/docs-pcfservices-template

2. cd into the book subdirectory of the repo.

   $ cd docs-partners-template/docs-book

3. Run bundle install to install all book dependencies.

   $ bundle install

4. Run bookbinder watch to build the book on your machine. If it doesn't succeed, try prepending the command with bundle exec so that bookbinder uses local gems instead of global gems.

   $ bundle exec bookbinder watch

5. Browse to localhost:4567 to view the book locally and "watch" any changes that you make to source html.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!

docs-book-tiledev's Issues

Support for stack dropdown type?

Is your feature request related to a problem? Please describe.

We need to let operator to choose the backing applications stack, during the tile installation.

Describe the solution you'd like

It would be nice to have a dropdown type, similar to vm_type_dropdown or stemcell_selector to poplulate the available stacks automatically and let the user/operator to choose between the available stacks.

Describe alternatives you've considered

Our current workaround is a string input, which is prone to errors, typos and ...

Another option would be a dropdown type with hard coded stack values. The problem with this approach is that we are not aware of available stacks in the customer foundation.

Additional context

No response

What is the special handling for secrets?

It is a bit ambiguous what the special handling is for secrets. Can you provide more complicated password examples? How do we use quotes, single quotes, double quotes? What needs to be escaped. Can you reference a page that explains a bit more about the special handling, or at least a hint to what keywords to search for.

"property reference" descriptions incorrectly says "holds a boolean value"

Hi,

I noticed that this page (https://docs.pivotal.io/tiledev/property-reference.html#property-blueprints) says that many properties hold boolean value. I think some of these might be incorrect. For instance, the description for uuid says "Holds a boolean value". I'd expect it to say something like "Holds a uuid (without hyphens) as a string".

`cf push`ed packages do not run in their own VMs

docs-book-tiledev/docs-content/tile-structure.html.md.erb

Line 201 in 689f5c3

Each `app` or `broker` type package runs processes on its own VM, either deployed to PCF using `cf push`, or run on the BOSH layer underneath. These packages typically contain a single process, but can include more than one that share a VM.

A package type that is cf pushed (app, app-broker, docker-app, docker-app-broker) will run its process in a container on a Diego cell, not in its own VM.

docker-bosh and bosh-release packages will run processes in its own BOSH VM.

(For completeness, external-broker and buildpack packages do not start long-running processes.)

Sample code for tile migrations is incorrect

The sample code for the js migrations seems to be incorrect.

The object passed in to the migrate function contains a properties field that needs to be dereferenced.
Current:

exports.migrate = function(properties) {
    // Append text to a string

    properties['.web_server.example_string']['value'] += '!'; 

    // Rename property 'example_port' to 'example_port_renamed',
    // retaining the previous value.
    properties['.properties.example_port_renamed'] = 
        properties['.properties.example_port'];
    delete properties['.properties.example_port'];

    // Append text to a string list
    properties['.properties.example_string_list']['value'].push(
        'new-string-append-by-migration');

    return properties;
}; 

Fixed

exports.migrate = function(input) {
    // Append text to a string

    input.properties['.web_server.example_string']['value'] += '!'; 

    // Rename property 'example_port' to 'example_port_renamed',
    // retaining the previous value.
    input.properties['.properties.example_port_renamed'] = 
        input.properties['.properties.example_port'];
   delete input.properties['.properties.example_port'];

    // Append text to a string list
    input.properties['.properties.example_string_list']['value'].push(
        'new-string-append-by-migration');

    return input;
}; 

"