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 git@github.com
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.
-
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.
-
In the terminal on your workstation, change into the directory where you want to clone the forked repository.
-
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
-
Change into the directory for the local repository you just cloned.
$ cd openshift-docs
-
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.
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.
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)
-
A web browser (Firefox, Chrome, or Safari)
-
An editor that can strip trailing whitespace, such as Visual Studio Code.
-
Install the docker or Podman package.
-
Change to the
openshift-docs
directory and build every distribution by entering therun
command for the tool that you are using. The following example uses Docker and is identical for Podman on Linux. This example might require some setup on a Mac.$ cd openshift-docs $ docker run --rm -it -v `pwd`:/docs:Z quay.io/openshift-cs/asciibinder 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, but with an.html
extension.
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
NoteOn certain systems,
yum
installs an older version of RubyGems that can cause issues. As an alternative, you can install RubyGems by using RVM. The following example is referenced from the RVM site:$ curl -sSL https://get.rvm.io | bash -s stable --ruby
-
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 make with
yum install make
-
Install asciidoctor-diagram with
gem install asciidoctor-diagram
-
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.2.0 or newer. To check
and update if necessary, simply run gem update ascii_binder . Note that you might require root permissions.
|
You can use toolbx
to create a Fedora-based container for our tools on most Linux distributions, including RHEL. By using Fedora as the base, you have access to relatively recent versions of required software packages.
-
Your distro has Podman 1.4.0 or greater.
-
If you don’t already have
toolbx
, install it. -
To create a Fedora 37 container, on a command line, enter:
$ toolbox create --distro fedora --release f37 <container_name>
where:
- <container_name>
-
Specifies the name that you want to give your toolbox container.
-
Enter the container. From the command line, run:
$ toolbox enter <container_name>
-
Install dependencies for our tools. Within the toolbox that you entered, run:
[toolbox] $ sudo dnf install ruby-devel gcc-c++ redhat-rpm-config make
-
Install the required Ruby gems:
[toolbox] $ gem install ascii_binder asciidoctor-diagram
You now have a toolbox container that you can use to build our documentation no matter which distribution you use.
Note
|
Press Ctrl + D or enter exit to exit the container. To use AsciiBinder or update the software in the container, remember to toolbox enter <container_name> first.
|
With the initial setup complete, you are ready to build the collection.
-
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.
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
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.