mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
120 lines
4.5 KiB
Plaintext
120 lines
4.5 KiB
Plaintext
[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.
|
|
|
|
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 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 http://asciibinder.org[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`
|
|
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 (1.5.6 version of) _asciidoctor-diagram_ with `gem install asciidoctor-diagram --version=1.5.6`
|
|
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.1.15 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.
|