Dev branch support plus doc standards tweaks

_build_cfg.yml

@@ -19,6 +19,8 @@ Dir: welcome
 Topics:
   - Name: Welcome
     File: index
+  - Name: Contributing
+    File: doc_guidelines
 
 ---
 Name: Getting Started
@@ -72,7 +74,7 @@ Topics:
     File: domains
   - Name: Applications
     File: apps
-    
+
 ---
 Name: Developing Cartridges
 Dir: cartridge_specification_guide

_builder_lib/docsitebuilder/helpers.rb

@@ -82,6 +82,11 @@ def build_config
       validate_config(YAML.load_stream(open(build_config_file)))
     end
 
+    # Protip: Do cache this! It contains the dev branch config
+    def dev_build_config
+      @dev_build_config ||= validate_config(YAML.load_stream(open(build_config_file)))
+    end
+
     def distro_map
       @distro_map ||= begin
         { 'openshift-origin' => {
@@ -432,9 +437,9 @@ def generate_docs(build_distro,single_page=nil)
         single_page_file = single_page.split(':')[1]
         puts "Rebuilding '#{single_page}' on branch '#{working_branch}'."
       end
+
       if not build_distro == ''
         if not distro_map.has_key?(build_distro)
-          puts "Unrecognized distro '#{build_distro}'; cancelling build."
           exit
         else
           puts "Building the #{distro_map[build_distro][:name]} distribution(s)."
@@ -443,6 +448,16 @@ def generate_docs(build_distro,single_page=nil)
         puts "Building all available distributions."
       end
 
+      development_branch = nil
+      if not distro_branches.include?(working_branch)
+        development_branch = working_branch
+        if not build_distro == ''
+          puts "The working branch '#{working_branch}' will be rendered as #{build_distro} documentation."
+        else
+          puts "The working branch '#{working_branch}' will be rendered for each build distribution."
+        end
+      end
+
       # First, notify the user of missing local branches
       missing_branches = []
       distro_branches(build_distro).sort.each do |dbranch|
@@ -458,12 +473,12 @@ def generate_docs(build_distro,single_page=nil)
       end
 
       distro_map.each do |distro,distro_config|
-        if not build_distro == '' and not build_distro == distro
+        if single_page.nil? and not build_distro == '' and not build_distro == distro
           next
         end
         first_branch = single_page.nil?
         distro_config[:branches].each do |branch,branch_config|
-          if not single_page.nil? and not working_branch == branch
+          if not single_page.nil? and not working_branch == branch and development_branch.nil?
             next
           end
           if first_branch
@@ -474,10 +489,13 @@ def generate_docs(build_distro,single_page=nil)
             puts "- skipping #{branch}"
             next
           end
-          if single_page.nil?
+          if single_page.nil? and development_branch.nil?
             puts "- building #{branch}"
             git_checkout(branch)
           end
+          if not development_branch.nil?
+            branch_config[:dir] = "#{development_branch}_#{distro}"
+          end
 
           # Create the target dir
           branch_path = File.join(preview_dir,branch_config[:dir])
@@ -495,7 +513,7 @@ def generate_docs(build_distro,single_page=nil)
           system("cp -r _images/* #{branch_path}/images")
 
           # Read the _build_config.yml for this distro
-          distro_build_config = build_config
+          distro_build_config = development_branch.nil? ? build_config : dev_build_config
 
           # Build the landing page
           navigation = nav_tree(distro,distro_build_config)
@@ -549,6 +567,10 @@ def generate_docs(build_distro,single_page=nil)
               end
             end
           end
+
+          if not development_branch.nil?
+            break
+          end
         end
 
         # Create a distro landing page

doc_guidelines.adoc → welcome/doc_guidelines.adoc

@@ -12,7 +12,7 @@ toc::[]
 
 == Directory and file naming conventions
 
-All topic directory groups and topic filenames must be lowercase in order for the build system work correctly, as shown in the following example:
+All topic directory groups and topic filenames must be lowercase, and must not include whitespace, in order for the build system work correctly. Refer to the following example:
 
 ....
 /
@@ -55,7 +55,7 @@ After the heading block and a single whitespace line, you can include any conten
 
 [NOTE]
 ====
-Section headers within the topic must be level 2 ( == ) or lower.
+The topic title, which is the first line of the document, is the only level 1 ( = ) title. Section headers within the topic must be level 2 ( == ) or lower.
 ====
 
 If using section anchors, they must be all lowercase letters, with no line spaces between the anchor and the section title:
@@ -73,13 +73,15 @@ If you want to link to a different website, use:
 http://othersite.com/otherpath[friendly descriptor]
 ----
 
+TIP: If you want to build a link from a URL _without_ changing the text from the actual URL, just print the URL without adding a `[friendly text]` block at the end; it will automatically be rendered as a link.
+
 If you want to link to another topic in the same topic group directory:
 
 ----
-link:<filename>.html[friendly title]
+link:<filename>[friendly title]
 ----
 
-Be aware of the use of '.html' in the link. Do not use the '.adoc' file extension because the link is to the resulting HTML file. 
+Do not use the `.adoc` file extension. The document processor will correctly link this to the resulting HTML file. 
 
 There probably are two scenarios for linking to other content: 
 
@@ -96,15 +98,15 @@ The following examples use the example directory structure shown here:
 /baz/zag.adoc
 ....
 
-If you are working on bar.adoc and you want to link to zig.adoc, do it this way:
+If you are working on `bar.adoc` and you want to link to `zig.adoc`, do it this way:
 
 ----
 link:../baz/zig[see the ZIG manual for more]
 ----
 
-Note there is no suffix with the filename. (.adoc or .html)
+Note there is no suffix with the filename. (`.adoc` or `.html`)
 
-If you are working on zig.adoc and want to link to zag.adoc, do it this way:
+If you are working on `zig.adoc` and want to link to `zag.adoc`, do it this way:
 
 ----
 link:zag[comment]
@@ -118,16 +120,14 @@ link:../baz/zig/#subtopic
 
 If you want to link to an image:
 
-1. Put it in <topic_dir>/images 
+1. Put it in `<topic_dir>/images`
 2. In the topic document, use this format to link to an image:
 
 ----
 image:<name_of_image>[image]
 ----
 
-You only need to specify <name_of_image>. The build mechanism automatically specifies the file path. 
-
-If you want to build a link from a URL without changing the text from the actual URL, just print the URL without adding a [friendly text] block at the end; it will automatically be rendered as a link.
+You only need to specify `<name_of_image>`. The build mechanism automatically specifies the file path. 
 
 == Conditional text between products
 OpenShift documentation uses the AsciiDoc `ifdef/endif` macro to conditionalize document segments for specific OpenShift distributions down to the single-line level.
@@ -213,38 +213,38 @@ Which renders as:
 Lists are created as shown in this example:
 
 ....
-.  Item 1 (2 spaces between the period and the first character)
+. Item 1 (2 spaces between the period and the first character)
 
-.  Item 2
+. Item 2
 
-.  Item 3
+. Item 3
 ....
 
 This will render as such:
 
-.  Item 1
+. Item 1
 
-.  Item 2
+. Item 2
 
-.  Item 3
+. Item 3
 
 If you need to add any text, admonitions, or code blocks you need to add the continuous +, as shown in the example:
 
 ....
-.  Item 1
+. Item 1
 +
 ----
 some code block
 ----
 
-.  Item 2
+. Item 2
 
-.  Item 3
+. Item 3
 ....
 
 This renders as shown:
 
-.  Item 1
+. Item 1
 +
 ----
 some code block
@@ -301,4 +301,4 @@ Type [userinput]#Yes# when prompted.
 |$$[replaceable]#<Name>#$$
 a|This represents text that a user must replace with an actual value. For example:
 
-`rhc app delete [replaceable]#<App_Name>#`
+`rhc app delete [replaceable]#<App_Name>#`