Before you can contribute to OpenShift documentation, you must sign up for a GitHub account.
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 [email protected]
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.
-
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.
-
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
-
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.
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.
You can work on a topic file in an editing environment that automatically processes and updates the rendered HTML.
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)
-
A web browser (Firefox, Chrome, or Safari) with the LiveReload extension installed
The following instructions describe how to install all the required tools to do live content editing on a Fedora Linux system.
-
Install the RubyGems package with
yum install rubygems
-
Install Ruby development packages with
yum install ruby-devel
-
Install gcc with
yum install gcc-c++
-
Install redhat-rpm-config with
yum install redhat-rpm-config
-
Install the ascii_binder gem with
gem install ascii_binder
Note
|
If you already have AsciiBinder installed, you may be due for an update. These directions assume that you are using AsciiBinder 0.0.8 or newer. To check and update if necessary, simply run gem update ascii_binder . Note that you may need root permissions.
|
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.
Note
|
ditaa Support
ditaa requires $JAVA_HOME be set, which requires a JDK
installed (try e.g. |
With the initial setup complete, you are ready to use LiveReload to edit your content.
-
From the
openshift-docs
directory, run an initial build:$ cd openshift-docs $ asciibinder build
-
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. -
Run the
watch
utility:$ asciibinder watch
TipThis utility will run in the terminal where you started it, so you should leave it running and open new terminal windows for other tasks. -
In your browser, enable the LiveReload plug-in 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.
With the repository and tools set up on your workstation, you can now either edit existing content or create new topics.
-
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 topics or create new topics.