You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This ensures that you are tracking the remote repository to keep your local
60
60
repository in sync with it.
61
61
62
-
== Install AsciiBinder and dependencies
62
+
== Install Podman or Docker and run AsciiBinder as a container image
63
+
63
64
When you have the documentation repository cloned and set up, you are ready to
64
65
install the software and tools you will use to create the content. All OpenShift
65
66
documentation is created in AsciiDoc, and is processed with https://github.com/redhataccess/ascii_binder[AsciiBinder],
66
67
which is an http://asciidoctor.org/[AsciiDoctor]-based docs management system.
67
68
68
-
69
-
=== What you require
70
-
The following are minimum requirements:
71
-
72
-
* A bash shell environment (Linux and OS X include a bash shell environment out
73
-
of the box, but if you are on Windows you can use http://cygwin.com/[Cygwin])
74
-
* https://www.ruby-lang.org/en/[Ruby]
75
-
* http://www.git-scm.com/[Git]
76
-
* A web browser (Firefox, Chrome, or Safari)
77
-
* An editor that can strip trailing whitespace, such as
78
-
link:https://code.visualstudio.com/[Visual Studio Code].
79
-
80
-
=== Building using the asciibinder container image
69
+
The recommended way to run AsciiBinder is on a container image using Podman or Docker.
81
70
82
71
. Install the _docker_ or _link:https://podman.io/docs/installation[Podman]_ package.
83
-
. Change to the `openshift-docs` directory and build every distribution by entering the `run` 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.
72
+
. Change to the `openshift-docs` directory and build every distribution by entering the `run` 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.
filename as the original `.adoc` file you edited, but with an
92
81
`.html` extension.
93
82
94
-
=== Install the required software dependencies on a Linux system
95
-
The following instructions describe how to install all the required tools to do
96
-
live content editing on a Fedora Linux system.
97
-
98
-
1. Install the _RubyGems_ package with `yum install rubygems`
99
-
+
100
-
[NOTE]
83
+
[IMPORTANT]
101
84
====
102
-
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]:
85
+
Previously, installing AsciiBinder directly on your system was recommended. However, on recent Linux distribution releases, AsciiBinder does not work because of Ruby version incompatibility.
2. Install _Ruby_ development packages with `yum install ruby-devel`
111
-
3. Install _gcc_ with `yum install gcc-c++`
112
-
4. Install _redhat-rpm-config_ with `yum install redhat-rpm-config`
113
-
5. Install _make_ with `yum install make`
114
-
6. Install _asciidoctor-diagram_ with `gem install asciidoctor-diagram`
115
-
7. Install the _ascii_binder_ gem with `gem install ascii_binder`
116
-
117
-
NOTE: If you already have AsciiBinder installed, you might be due for an update.
118
-
These directions assume that you are using AsciiBinder 0.2.0 or newer. To check
119
-
and update if necessary, simply run `gem update ascii_binder`. Note that you might require root permissions.
120
-
121
-
=== Install the required software dependencies in a toolbox container on Linux
122
-
123
-
You can use link:https://containertoolbx.org/[`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.
124
-
125
-
.Prerequisites
126
-
127
-
* Your distro has link:https://podman.io/[Podman] 1.4.0 or greater.
128
-
129
-
.Procedure
130
-
131
-
. If you don't already have `toolbx`, link:https://containertoolbx.org/install/[install it].
132
-
133
-
. To create a Fedora 37 container, on a command line, enter:
You now have a toolbox container that you can use to build our documentation no matter which distribution you use.
166
-
167
-
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.
168
-
169
-
=== Building the collection
170
-
With the initial setup complete, you are ready to build the collection.
171
-
172
-
1. From the `openshift-docs` directory, run an initial build:
173
-
+
174
-
----
175
-
$ cd openshift-docs
176
-
$ asciibinder build
177
-
----
178
-
2. Open the generated HTML file in your web browser. This will be located in the
179
-
`openshift-docs/_preview/<distro>/<branch>` directory, with the same path and
180
-
filename as the original `.adoc` file you edited, only it will be with the
181
-
`.html` extension.
182
-
183
-
== Clean up
184
-
The `.gitignore` file is set up to prevent anything under the `_preview` and
185
-
`_package` directories from being committed. However, you can reset the
186
-
environment manually by running:
187
-
188
-
----
189
-
$ asciibinder clean
190
-
----
191
-
192
90
== Next steps
193
91
With the repository and tools set up on your workstation, you can now either
194
92
edit existing content or create assemblies and modules.
0 commit comments