Merge pull request #6 from nhr/readme_update

Updated README to relfect build system changes

Author: nhr

README.adoc

@@ -35,15 +35,86 @@ Each directory of the repo represents a different collection of topics (you can
 
 == Metadata
 
-In order to construct the documentation site from these sources, the build system looks at certain metdata files. The actual format of these configuration files is TBD.
+In order to construct the documentation site from these sources, the build system looks at the `_build_cfg.yml` metdata file. The format of this files is as indicated:
 
-=== builder_top_cfg.yaml
+----
+--- <1>
+Name: Origin of the Species <2>
+Dir:  origin_of_the_species <3>
+Topics:
+  - Name: The Majestic Marmoset <4>
+    File: the_majestic_marmoset <5>
+  - Name: The Curious Crocodile
+    File: the_curious_crocodile
+----
+<1> Record separator at the top of each topic group
+<2> Display name of topic group
+<3> Directory name of topic group
+<4> Topic name
+<5> Topic file under the topic group dir withour without '.adoc'
+
+The build system only looks in this file for information on which files to include, so any new file submissions must be accompanied by an update to this metadata file.
+
+== Live Editing
+If you would like to work on one of the documentation files in an editing environment that automatically redraws the resulting HTML, follow these steps.
+
+=== Prerequisites
+You will need the following tools in your editing environment:
+
+* A bash shell environment (Linux distributions and OS X include these out of the box, for Windows consider http://cygwin.com/[Cygwin])
+* https://www.ruby-lang.org/en/[Ruby]
+* http://www.git-scm.com/[git]
+* A web browser (Firefox, Chrome or Safari) with the http://livereload.com/[LiveReload] extension
+
+With these tools available, first perform a one-time setup:
+
+1. Clone the https://github.com/openshift/openshift-docs[openshift-docs] repo from GitHub:
++ 
+----
+$ git clone https://github.com/openshift/openshift-docs.git
+----
+2. From the cloned directory, run a bundle install:
++ 
+----
+$ cd openshift-docs
+$ bundle install
+----
++
+TIP: If you don't have bundler installed, you can get it by running `gem install bundler`
 
-The top-level configuration file tells the build system the order in which to display the "book-grouped" topics.
+That's it for setup, the next section explains how to run the LiveReload system.
 
-=== builder_book_cfg.yaml
+=== Running with LiveReload
+Once you've installed the link:#prerequisites[prerequisites] you can fire up the LiveReload setup as follows:
 
-A "book" level configuration file exists in each book directory. It tells the build system the order in which to display the topics with the "book" grouping.
+1. From the `openshift-docs` directory, run a preliminary build:
++ 
+----
+$ cd openshift-docs
+$ bundle exec rake build
+----
+2. Now open the generated HTML file in your browser. It will be under `openshift-docs/_preview` with the same path and filename as the original file. The only difference will be the name ending in '.html' instead of '.adoc'.
+3. Now start up the `guard` utility:
++ 
+----
+$ bundle exec guard
+----
++ 
+TIP: This utility will run in the terminal where you started it, so you should leave it running off to the side and use other terminals for regular tasks.
+4. Finally, back in your browser, enable the LiveReload plugin in the same tab where the preview file is displayed. You will know this step succeeded if the LiveReload icon changes, and if you see output similar to the following in the terminal where `guard` is running:
++ 
+----
+[1] guard(main)> 17:29:22 - INFO - Browser connected.
+----
+
+That's it. Now any changes that you make to the source file will automatically trigger a rebuild of the target HTML file.
+
+=== Clean Up
+The `.gitignore` file is set up to prevent anything under `_preview` from being committed. However, you can reset the environment manually by running:
+
+----
+$ bundle exec rake clean
+----
 
 == Contacts