Copyright (c) 2006-2012 VMware, Inc. All Rights Reserved.
OBSOLETE
Obsolete - please go to http://cloudfoundry.github.com
docs.cloudfoundry.com
These are the Cloud Foundry docs built with nanoc.
Setup
Ruby 1.9 is required to build the site. This repo assumes(via .rvmrc) you have RVM and Ruby 1.9.2 installed and a docs gemset
To create the docs gemset follow these steps:
$ rvm use 1.9.2
Using /Users/<your_username>/.rvm/gems/ruby-1.9.2-p290
$ rvm gemset create docs
'docs' gemset created (/Users/<your_username>/.rvm/gems/ruby-1.9.2-p290@docs).
$ rvm gemset use docs
Use this command to get all the necessary gems to build the docs:
$ bundle install
You can see the available commands with nanoc:
nanoc -h
Nanoc has some nice documentation to get you started. Though if you're mainly concerned with editing or adding content, you won't need to know much about nanoc.
Writing Docs
-
Add a markdown doc
mydoc.md
to thecontent
folder. If you need to add screenshots, add them tostatic/images/screenshot/<page-name>/
folder -
Specify title, description and tags.
-
Reuse tags instead of making new ones wherever possible.
Changing the layout
If you need to change the layout you can edit default.haml in the layouts folder. Many of the values used in this template are set in the confi.yaml including:
- Base urls for all the links
- Test version of docs vs production version of docs
- Social buttons preferences
Colorized Code Blocks
You can have nanoc pretty print (colorize) your code, by placing the code inside a fenced block quote (three backquotes) followed by language name. This style is compatible with GitHub Flavored Markdown code blocks.
Example:
``` ruby
# this is a simple Ruby Sinatra app
get '/' do
"Hello from Sinatra!"
end
```
Supported languages include java, javascript, ruby, erb, groovy, scala, bash
html and xml (see Rules
for full list).
Some things to watch out for:
- Avoid
TAB
characters in the code, as tabs confuse the nanoc filters. - Make sure the three backquotes have no leading spaces
- You dont have to escape HTML or XML inside the fenced quotes
Development
Nanoc compiles the site into static files living in ./output/public
. It's
smart enough not to try to compile unchanged files:
$ nanoc tags
$ nanoc compile
Loading site data...
Compiling site...
identical [0.37s] output/public/frameworks.html
identical [1.54s] output/public/frameworks/java/spring/grails.html
identical [12.77s] output/public/frameworks/java/spring/spring.html
identical [1.01s] output/public/frameworks/nodejs/nodejs.html
identical [0.08s] output/public/frameworks/ruby/installing-ruby.html
identical [0.57s] output/public/frameworks/ruby/rails-3-0.html
identical [2.05s] output/public/frameworks/ruby/rails-3-1.html
identical [0.54s] output/public/frameworks/ruby/ruby-simple.html
identical [0.08s] output/public/frameworks/ruby/ruby.html
identical [3.13s] output/public/frameworks/ruby/sinatra.html
identical [0.90s] output/public/frameworks/scala/scala.html
identical [0.05s] output/public/getting-started.html
identical [0.07s] output/public/index.html
identical [0.09s] output/public/infrastructure/micro/installing-mcf.html
identical [0.14s] output/public/infrastructure/micro/using-mcf.html
identical [0.07s] output/public/infrastructure/overview.html
identical [0.06s] output/public/quick-start.html
update [0.53s] output/public/services.html
Site compiled in 42.48s.
You can setup whatever you want to view the files. If you have the adsf gem, however (I hope so, it was in the Gemfile), you can start Webrick:
$ nanoc view
You can then open your browser to http://localhost:3000
Compilation times got you down? Use autocompile
!
$ nanoc tags
$ nanoc autocompile
This starts a web server too, so there's no need to run nanoc view
.
One thing: remember to add trailing slashes to all nanoc links!
Since Cloud Foundry doesn't support deploying a static app we use Sinatra. The Sinatra app is inside the output doc You can run this app by doing
$ cd output
$ bundle install
$ ruby sample.rb
You can then open your browser to http://0.0.0.0:4567/ and see the same pages
as with nanoc view
and opening http://localhost:3000
Contributing to the documentation
- Signup at https://reviews.cloudfoundry.org
- Install the
gerrit-cli
gem gerrit clone
the repossh://<your-username>@reviews.cloudfoundry.org:29418/cf-docs
and cd into it- Update the pages (inside of folder
content
) - Remove the old pages
rm -rf output/public
- If you changed tags, regenerate them with
nanoc tags
- Recompile
nanoc compile
- Test
nanoc autocompile
ornanoc view
- Commit your change
git commit -am "Changes to have a simpler tutorial"
- Squash commits into one if you want to send your changes upstream.
- Submit changes with
gerrit push
License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License