From 31d70dec99cf12510387e5c87f39d2bb4498e027 Mon Sep 17 00:00:00 2001 From: Bilhar Date: Wed, 19 Nov 2014 14:45:38 +1000 Subject: [PATCH 1/2] Adding doc guidelines topic --- doc_guidelines.adoc | 304 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 304 insertions(+) create mode 100644 doc_guidelines.adoc diff --git a/doc_guidelines.adoc b/doc_guidelines.adoc new file mode 100644 index 000000000000..c311f60b383d --- /dev/null +++ b/doc_guidelines.adoc @@ -0,0 +1,304 @@ += Documentation Guidelines [DRAFT] +{product-author} +{product-version} +:data-uri: +:icons: +:toc: +:toc-placement!: +:toc-title: Topics Covered +:description: These are basic guidelines for creating technical documentation for OpenShift. + +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: + +.... +/ +/topic_dir +/topic_dir/topic_1.adoc +/topic_dir/topic_2.adoc +/topic_dir/topic_3.adoc +.... + +== Topic Files + +Every topic file should contain the following metadata at the top, with no line spacing in between, except where noted: + +---- += Document/Topic Title <1> +{product-author} <2> +{product-version} <3> +:data-uri: <4> +:icons: <5> +:toc: <6> +:toc-placement!: <7> +:toc-title: Topics Covered <8> +:description: <9> +-----------intentional blank line-------------- +toc::[] <10> +---- + +<1> Human readable title of document/topic title line (notice the '=' top-level header) +<2> AsciiDoctor attribute for product author and gets dynamically replaced +<3> AsciiDoctor attribute for product version and gets dynamically replaced +<4> AsciiDoctor attribute to embed all images directly in the HTML +<5> AsciiDoctor attribute for icons used in admonitions and such (TIP, NOTE, WARNING, etc.) +<6> Adds a table of contents (TOC). +<7> Overrides the default placement of TOC. +<8> Overrides the default title of TOC. +<9> Brief description or synopsis of the document/topic to help with Google search. +<10> Placement of the TOC. + +After the heading block and a single whitespace line, you can include any content for the topic. + +[NOTE] +==== +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: + +---- +[[section_anchor_name]] +=== Section Title +---- + +== Links, hyperlinks, and cross references + +If you want to link to a different website, use: + +---- +http://othersite.com/otherpath[friendly descriptor] +---- + +If you want to link to another topic in the same topic group directory: + +---- +link:.html[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. + +There probably are two scenarios for linking to other content: + +1. Link to another topic file that exists in a separate topic group, or directory. +2. Link to another topic file that exists in the same topic group, or directory. + +The following examples use the example directory structure shown here: +.... +/ +/foo +/foo/bar.adoc +/baz +/baz/zig.adoc +/baz/zag.adoc +.... + +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) + +If you are working on zig.adoc and want to link to zag.adoc, do it this way: + +---- +link:zag[comment] +---- + +This type of linking should be sufficient in most cases. However, you can also link to a subtopic within a topic file: + +---- +link:../baz/zig/#subtopic +---- + +If you want to link to an image: + +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. + +== 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. + +The supported distribution attributes used with the OpenShift build mechanism are: + +* _openshift-origin_ +* _openshift-online_ +* _openshift-enterprise_ + +These attributes can be used by themselves, or in conjunction to conditionalize text within a topic document. + +Here is an example of this concept in use: + +.... +This first line is unconditionalized, and will appear for all versions. + +ifdef::openshift-online[] +This line will only appear for OpenShift Online. +endif::[] + +ifdef::openshift-enterprise[] +This line will only appear for OpenShift Enterprise. +endif::[] + +ifdef::openshift-origin,openshift-enterprise[] +This line will appear for OpenShift Origin and Enterprise, but not for OpenShift Online. +endif::[] +.... + + +Note that the following limitations exist when conditionalizing text: + +1. The `ifdef/endif` blocks have no size limit, however they should not be used to conditionalize an entire topic. If an entire topic file is specific to a given OpenShift distribution, refer to the Document Set Metadata section for information on how to conditionalize at the whole-topic level. + +2. The `ifdef/endif` blocks cannot be nested. In other words, one conditional block cannot contain other conditional blocks. + +== Formatting + +For all of the system blocks including table delimiters, use four characters. For example: + +.... +|=== for tables +---- for code blocks +.... + +=== Code blocks + +For all code blocks, you must include an empty line above a code block. + +Acceptable: + +.... +Lorem ipsum + +---- +$ lorem.sh +---- +.... + +Not acceptable: + +.... +Lorem ipsum +---- +$ lorem.sh +---- +.... + +Without the line spaces the content is likely to be not parsed correctly. + +Also, if you want to render some code inline, use backticks: + +.... +"The file can be found at `/dev/null` on your host." +.... + +Which renders as: + +"The file can be found at `/dev/null` on your host." + +=== Lists +Lists are created as shown in this example: + +.... +. Item 1 (2 spaces between the period and the first character) + +. Item 2 + +. Item 3 +.... + +This will render as such: + +. Item 1 + +. Item 2 + +. 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 ++ +---- +some code block +---- + +. Item 2 + +. Item 3 +.... + +This renders as shown: + +. Item 1 ++ +---- +some code block +---- + +. Item 2 + +. Item 3 + +=== Examples + +Use the following format when showing examples: + +.... +.Example Title +---- +Example text here +---- +.... + + +== Admonitions + +Admonitions such as notes and warnings are formatted as shown: + +.... +[ADMONITION] +==== +Text for admonition +==== +.... + +== Quick markup reference + +[cols="4,7"] +|=== +|Markup |Description + +|$$`rhc app create`$$ +|Inline commands, for example: + +Use the `rhc app create` command to create a new application. + +|$$[parameter]#MAX_GEARS#$$ +|System or software parameters: + +Set the [parameter]#MAX_GEARS# parameter to the desired value. + +|$$[userinput]#value#$$ +|Values that a user is asked to enter: + +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 From 7557b50617901b360bd72891ef1ed14edb7dfcd6 Mon Sep 17 00:00:00 2001 From: "N. Harrison Ripps" Date: Thu, 20 Nov 2014 09:10:04 -0500 Subject: [PATCH 2/2] Dev branch support plus doc standards tweaks --- _build_cfg.yml | 4 +- _builder_lib/docsitebuilder/helpers.rb | 32 +++++++++++--- .../doc_guidelines.adoc | 44 +++++++++---------- 3 files changed, 52 insertions(+), 28 deletions(-) rename doc_guidelines.adoc => welcome/doc_guidelines.adoc (84%) 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]##`