OpenShift Documentation

This repo contains the documentation for

The documentation is sourced in AsciiDoc and transformed into HTML/CSS and other formats through AsciiDoctor-based automation.

Repo Organization

Each directory of the repo represents a different collection of topics (you can think of directories as books). The exceptions to this rule are directories whose names start with an underscore (like _builder_lib and _javascripts), which contain the assets used to generate the finished documentation. Within each 'book' directory, topics exist as separate asciidoc files and an images directory contains any images that are included in the topics.

/
/book1
/book1/topic1.adoc
/book1/topicN.adoc
/book1/images
/book1/images/img1.png
/book1/images/imgN.png
...
/bookN

Version Management

The overlap of documentation across OpenShift Origin, Online and Enterprise is no less than 80%. In many cases, this means that individual topics may need to include or exclude individual paragraphs with respect to a specific OpenShift distribution. While it is possible to accomplish this solely by using git branches to maintain slightly different versions of a given topic, doing so would make the task of maintaining internal consistency extremely difficult for content contributors.

Git branching is still extremely valuable, and serves the important role of tracking the release versions of documentation for the various OpenShift distributions.

Distribution-Specific Conditionals

OpenShift documentation uses AsciiDoc’s ifdef/endif macro to conditionalize document segments for specific OpenShift distributions down to the single-line level.

The supported distribution attributes used in the OpenShift document generator are:

openshift-origin
openshift-online
openshift-enterprise

These attributes can be used alone or together 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::[]

Two important points to keep in mind:

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.
The ifdef/endif blocks cannot be nested. In other words, one conditional block cannot contain other conditional blocks.

Release Branches

Through the use of Distribution-Specific Conditionals and Document Set Metadata, the master branch of this repository always contains a complete set of documentation that includes all of the OpenShift distributions. However, when and as new versions of the OpenShift distros are released, the master branch is merged down to new or existing release branches. Here is the general naming scheme used in the branches:

master - OpenShift Origin latest code
origin-N.N - OpenShift Origin most recent stable release
online - OpenShift Online most recent release
enterprise-N.N - OpenShift Enterprise support releases

On a nightly basis, the documentation web sites are rebuilt for each of these branches. In this manner, documentation for released versions of OpenShift will remain the same even as development continues on master. Additionally, any corrections or additions that are "cherry-picked" into the release branches will show up in the release documentation the next day.

Document Set Metadata

In order to construct the documentation site from these sources, the build system looks at the build_cfg.yml metadata file. 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.

File Format

The format of this file is as indicated:

--- (1)
Name: Origin of the Species (2)
Dir:  origin_of_the_species (3)
Distros: all (4)
Topics:
  - Name: The Majestic Marmoset (5)
    File: the_majestic_marmoset (6)
    Distros: all
  - Name: The Curious Crocodile
    File: the_curious_crocodile
    Distros: openshift-online,openshift-enterprise (7)
  - Name: The Numerous Nematodes
    Dir: the_numerous_nematodes (8)
    Topics:
      - Name: The Wily Worm (9)
        File: the_wily_worm
      - Name: The Acrobatic Ascarid  <= Sub-topic 2 name
        File: the_acrobatic_ascarid  <= Sub-topic 2 file under <group dir>/<subtopic dir>

Record separator at the top of each topic group
Display name of topic group
Directory name of topic group
Which OpenShift versions this topic group is part of
Topic name
Topic file under the topic group dir without '.adoc'
Which OpenShift versions this topic is part of
This topic is actually a subtopic group. Instead of a File path it has a Dir path and Topics, just like a top-level topic group.
Topics belonging to a subtopic group are listed just like regular topics with a Name and File.

Notes on "Distros"

The "Distros" setting is optional for topic groups and topic items. When the "Distros" setting is absent, the system treats the topic group or topic as though the user had set "Distros: all".
The "all" value for "Distros" is a synonym for "openshift-origin,openshift-enterprise,openshift-online".
The "all" value trumps other values, so "openshift-online,all" is treated as "all"

Understanding the Complete Distribution Condition Chain

It is important to understand the ordering of distribution conditionals in determining whether or not a specific piece of content appears in the documentation set. The hierarchy is fairly straightforward:

Topic group "Distros" setting from _build_cfg.yml
Topic item "Distros" setting from _build_cfg.yml
Document-level ifdef/endif blocks

In this manner:

If a topic group is configured with "Distros: openshift-online", the entire group will be skipped for OpenShift Enterprise and OpenShift Origin, regardless of the Topic-level and document-level content rules within that group.
When a topic group is available to all Distros, but a specific topic item is limited, the topic group will appear for all distros and the specific topic item will only appear for the indicated distros.

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 Cygwin)
Ruby
git
A web browser (Firefox, Chrome or Safari) with the LiveReload extension

With these tools available, first perform a one-time setup:

Clone the openshift-docs repo from GitHub:

$ git clone https://github.com/openshift/openshift-docs.git

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

That’s it for setup, the next section explains how to run the LiveReload system.

Running with LiveReload

Once you’ve installed the prerequisites you can fire up the LiveReload setup as follows:

From the openshift-docs directory, run a preliminary build:
```
$ cd openshift-docs
$ bundle exec rake build
```
Now open the generated HTML file in your browser. It will be under openshift-docs/_preview/<distro>/<branch> with the same path and filename as the original file. The only difference will be the name ending in '.html' instead of '.adoc'.
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.
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 and _package from being committed. However, you can reset the environment manually by running:

$ bundle exec rake clean

Creating New Topic Pages

The layout and style rules for new documentation are largely described in an upcoming style guide (delivery date TBD). However, a few important rules are listed here because they affect the way that the pages are rendered.

The top matter of any new topic page must have the following format:

= Human-Readable Topic Title
{product-author}
{product-version}
:data-uri:
:icons:

The article title goes on the first line with a level 1 header markup (=)
The {product-author} and {product-version} are AsciiDoc attributes that get replaced dynamically when the docs are generated.
The :data-uri: attribute tells AsciiDoctor to embed any images directly in the HTML.
The :icons: attribute tells AsciiDoctor to use cool icons for admonition blocks.

After the heading block and a single whitespace line, you can include any content for the topic.

Note	Any section headers within the article must be level 2 (==) or lower. Try to be consistent about level-nesting; it won’t break AsciiDoctor to jump from a level 1 section header down to level 3, but it isn’t good form.

Contacts

For questions or comments about the documentation system:

OpenShift team members can be found on the #openshift and #openshift-dev channels on FreeNode.
You can also join the Users or Developers mailing list.

pravisankar/openshift-docs