openshift-docs/contributing_to_docs/tools_and_setup.adoc

[id="contributing-to-docs-tools-and-setup"]
= Install and set up the tools and software
:icons:
:toc: macro
:toc-title:
:toclevels: 1
:linkattrs:
:description: How to set up and install the tools to contribute

toc::[]

== Create a GitHub account
Before you can contribute to OpenShift documentation, you must
https://www.github.com/join[sign up for a GitHub account].

== Set up authentication
When you have your account set up, follow the instructions to
https://help.github.com/articles/generating-ssh-keys/[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.

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

== 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 https://github.com/redhataccess/ascii_binder[AsciiBinder],
which is an http://asciidoctor.org/[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 http://cygwin.com/[Cygwin])
* https://www.ruby-lang.org/en/[Ruby]
* http://www.git-scm.com/[Git]
* A web browser (Firefox, Chrome, or Safari)
* An editor that can strip trailing whitespace, such as
link:https://atom.io/[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`

[NOTE]
====
On 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 link:https://rvm.io/rvm/install[RVM site]:

[source,terminal]
----
$ curl -sSL https://get.rvm.io | bash -s stable --ruby
----
====

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 _asciidoctor-diagram_ with `gem install asciidoctor-diagram`
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.2.0 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.

* link:doc_guidelines.adoc[Review the documentation guidelines] to understand
some basic guidelines to keep things consistent across our content.
* link:create_or_edit_content.adoc[Create a local working branch] on your
workstation to edit existing content or create content.

=== 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
link:https://docs.okd.io/latest/dev_guide/builds/build_inputs.html#source-secrets-combinations[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
----