tools_and_setup.adoc

Install and set up the tools and software

• Create a GitHub account
• Set up authentication
• Fork and clone the OpenShift documentation repository
• Previewing the documentation locally
• Next steps

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 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. In the terminal on your workstation, change into the directory where you want to clone the forked repository.

3. Clone the forked repository onto your workstation with the following command, replacing <user_name> with your actual GitHub username.

   $ git clone git@github.com:<user_name>/openshift-docs.git

4. Change into the directory for the local repository you just cloned.

   $ cd openshift-docs

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

Previewing the documentation locally

After you clone the documentation repository, you are ready to install the software you need to build our content from source. All OpenShift documentation is written in AsciiDoc, and is processed with AsciiBinder, which is an AsciiDoctor-based docs management system.

The recommended way to run AsciiBinder is on a container image using Podman. However, if you already have Docker on your system, you can use it in place of Podman.

Important

Previously, installing AsciiBinder directly on your system was recommended. However, on recent Linux distribution releases, AsciiBinder does not work because of Ruby version incompatibility. Use AsciiBinder by running the container image.

Installing Podman on your system

Install Podman so that you can run the AsciiBinder container image on your machine.

If you are using Fedora, from a command line, enter:

$ sudo dnf install podman

If you are using another operating system, follow the Podman installation docs.

Building the documentation

Run the container image with an AsciiBinder command to build the OpenShift documentation.

1. From a command line, change to the openshift-docs directory.

2. To build every distribution in the docs, enter the following command:

   $ podman run --rm -it -v `pwd`:/docs:Z quay.io/openshift-cs/asciibinder asciibinder build

   The asciibinder build command runs within the image. The AsciiDoc files are transformed into HTML files in your local repository under the _preview directory. By default, AsciiBinder generates a documentation set for each distribution.

Tip	To choose which distributions to build, use the -d option in the command. For example, to only build openshift-enterprise, change asciibinder build to asciibinder build -d openshift-enterprise.

Next steps

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

• Review the documentation guidelines to understand some basic guidelines to keep things consistent across our content.

• Create a local working branch on your workstation to edit existing content or create content.