Skip to content

Latest commit

 

History

History
169 lines (138 loc) · 6.77 KB

tools_and_setup.adoc

File metadata and controls

169 lines (138 loc) · 6.77 KB
Raw

Install and set up the tools and software

Create a GitHub account

Before you can contribute to OpenShift documentation, you must sign up for a GitHub account.

Set up authentication

When you have your account set up, follow the instructions to generate and set up SSH keys on GitHub for proper authentication between your workstation and GitHub.

Confirm authentication is working correctly with the following command:

Fork and clone the OpenShift documentation repository

You must fork and set up the OpenShift documentation repository on your workstation so that you can create PRs and contribute. These steps must only be performed during initial setup.

  1. Fork the https://github.com/openshift/openshift-docs repository into your GitHub account from the GitHub UI. You can do this by clicking on Fork in the upper right-hand corner.

  2. On your workstation, clone the forked repository on your workstation with the following command. Be sure to change into the directory where you want to clone, and replace <user_name> with your actual GitHub username.

    $ git clone [email protected]:user_name/openshift-docs.git

  3. From your local repository you just cloned, add an upstream pointer back to the OpenShift’s remote repository, in this case openshift-docs.

    $ git remote add upstream [email protected]:openshift/openshift-docs.git

This ensures that you are tracking the remote repository to keep your local repository in sync with it.

Install AsciiBinder and dependencies

When you have the documentation repository cloned and set up, you are ready to install the software and tools you will use to create the content. All OpenShift documentation is created in AsciiDoc, and is processed with AsciiBinder, which is an AsciiDoctor-based docs management system.

What you require

The following are minimum requirements:

  • A bash shell environment (Linux and OS X include a bash shell environment out of the box, but if you are on Windows you can use Cygwin)

  • Ruby

  • Git

  • A web browser (Firefox, Chrome, or Safari)

  • An editor that can strip trailing whitespace, such as Atom.

Install the required software dependencies on a Linux system

The following instructions describe how to install all the required tools to do live content editing on a Fedora Linux system.

  1. Install the RubyGems package with yum install rubygems

  2. Install Ruby development packages with yum install ruby-devel

  3. Install gcc with yum install gcc-c++

  4. Install redhat-rpm-config with yum install redhat-rpm-config

  5. Install make with yum install make

  6. Install (1.5.6 version of) asciidoctor-diagram with gem install asciidoctor-diagram --version=1.5.6

  7. Install the ascii_binder gem with gem install ascii_binder

Note
 If you already have AsciiBinder installed, you might be due for an update. These directions assume that you are using AsciiBinder 0.1.15 or newer. To check and update if necessary, simply run gem update ascii_binder. Note that you might require root permissions.

Building the collection

With the initial setup complete, you are ready to build the collection.

  1. From the openshift-docs directory, run an initial build:

    $ cd openshift-docs
$ asciibinder build

  2. Open the generated HTML file in your web browser. This will be located in the openshift-docs/_preview/<distro>/<branch> directory, with the same path and filename as the original .adoc file you edited, only it will be with the .html extension.

Clean up

The .gitignore file is set up to prevent anything under the _preview and _package directories from being committed. However, you can reset the environment manually by running:

$ asciibinder clean

Next steps

With the repository and tools set up on your workstation, you can now either edit existing content or create assemblies and modules.

How to deploy to your own OpenShift cluster for testing

You can deploy to your own OpenShift cluster for development. This process will use your github repo to launch the website, and therefore your github repo must have all of the upstream branches. master is used for site changes, so assuming all your work is in master, you can remove all remote branches and then push the upstream branches.

Removing remote branches and updating with upstream branches (this assumes remote repos called origin and upstream)

Warning

This is a destructive process, make sure that this is purely a development repo, as all local and remote branches will be deleted by performing the below commands.

 
$ git fetch --all
$ for branch in $(git branch -r | grep -v "master" | grep "^  origin"); do git push origin --delete $(echo $branch | cut -d '/' -f 2); done
$ git branch -D $(git branch | grep -v 'master' | xargs)
$ for branch in $(git branch -r | grep -v "master" | grep "^  upstream"); do git branch --track $(echo $branch | cut -d '/' -f 2) $(echo $branch | tr -d '[:space:]'); done
$ for branch in $(git branch | grep -v "master"); do git push origin $(echo $branch | tr -d '[:space:]'); done

Deploying the docs site to an OpenShift cluster

$ oc process -f asciibinder-template.yml -p NAME=community-docs \
    -p SOURCE_REPOSITORY_URL=$(git remote get-url origin) \
    -p SOURCE_REPOSITORY_REF=$(git rev-parse --abbrev-ref HEAD) \
    -p DOC_TYPE=community \
    | oc create -f -
$ oc process -f asciibinder-template.yml -p NAME=commercial-docs \
    -p SOURCE_REPOSITORY_URL=$(git remote get-url origin) \
    -p SOURCE_REPOSITORY_REF=$(git rev-parse --abbrev-ref HEAD) \
    -p DOC_TYPE=commercial \
    | oc create -f -
Note

If the build fails with "Fetch source failed" status, you can delete all the created objects and re-run above with an HTTP uri as the SOURCE_REPOSITORY_URL, or you can create a source secret and add it to the stg1 build, oc set build-secret --source bc/stg1-docs <secret name>.

You can delete all created objects by running

$ oc delete all -l app=community-docs
$ oc delete all -l app=commercial-docs