diff --git a/_build_cfg.yml b/_build_cfg.yml index 70c76b331c05..0a95e9c18ca0 100644 --- a/_build_cfg.yml +++ b/_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 diff --git a/_builder_lib/docsitebuilder/helpers.rb b/_builder_lib/docsitebuilder/helpers.rb index ddce454ead6f..191cc8470608 100644 --- a/_builder_lib/docsitebuilder/helpers.rb +++ b/_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 diff --git a/doc_guidelines.adoc b/welcome/doc_guidelines.adoc similarity index 84% rename from doc_guidelines.adoc rename to welcome/doc_guidelines.adoc index c311f60b383d..453bcedb758d 100644 --- a/doc_guidelines.adoc +++ b/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:.html[friendly title] +link:[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 /images +1. Put it in `/images` 2. In the topic document, use this format to link to an image: ---- image:[image] ---- -You only need to specify . 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 ``. 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]##$$ a|This represents text that a user must replace with an actual value. For example: -`rhc app delete [replaceable]##` \ No newline at end of file +`rhc app delete [replaceable]##`