Skip to content

Latest commit

 

History

History
157 lines (128 loc) · 5.51 KB

tools_and_setup.adoc

File metadata and controls

157 lines (128 loc) · 5.51 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:

$ ssh -T git@github.com

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 only need to 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 git@github.com: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 git@github.com:openshift/openshift-docs.git

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

Install AsciiDoctor and required software for live editing

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 AsciiDoctor.

You can work on a topic file in an editing environment that automatically processes and updates the rendered HTML.

What you need

The following are minimum requirements to set up a live editing environment:

  • 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) with the LiveReload extension installed

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 the bundler gem with gem install bundler

Initial setup

After you have confirmed that you meet the minimum system requirements, or if you are on a Linux system you have installed the required software dependencies, you can perform the initial setup.

From the directory where you cloned the documentation repository, run a bundle install:

$ cd openshift-docs
$ bundle install

This installs the Ruby gems required for the build.

Note

Some gems may have further dependencies that need to be installed on your system. For instance, rjb requires $JAVA_HOME be set, which requires a JDK installed (try e.g. yum install java-1.8.0-openjdk-devel and export JAVA_HOME=/usr/lib/jvm/java-1.8.0). You can simply rerun the bundle install command to continue after adding any necessary dependencies.

How to use LiveReload

With the initial setup complete, you are ready to use LiveReload to edit your content.

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

    $ cd openshift-docs
$ bundle exec rake 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.

  3. 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 and open new terminal windows for other tasks.

  4. In your browser, enable the LiveReload plugin in the same tab where the preview file is open; the icon should change color once activated. The following message will also display in your terminal window:

    [1] guard(main)> 17:29:22 - INFO - Browser connected.

With this setup, a rebuild is automatically generated each time you make a change to the source .adoc file, and is immediately viewable in the corresponding .html file.

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:

$ bundle exec rake clean

Next steps

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