mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
Update tools page
- macOS guidance now doesn't seem so shaky. - Default to podman - Link out to podman installation docs for non-Fedora OSes
This commit is contained in:
@@ -59,26 +59,14 @@ $ 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 Podman or Docker and run AsciiBinder as a container image
|
||||
== Previewing the documentation locally
|
||||
|
||||
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],
|
||||
After you clone the documentation repository, you are ready to
|
||||
install the software you need to build our content from source. All OpenShift
|
||||
documentation is written in AsciiDoc, and is processed with https://github.com/redhataccess/ascii_binder[AsciiBinder],
|
||||
which is an http://asciidoctor.org/[AsciiDoctor]-based docs management system.
|
||||
|
||||
The recommended way to run AsciiBinder is on a container image using Podman or Docker.
|
||||
|
||||
. Install the _docker_ or _link:https://podman.io/docs/installation[Podman]_ package.
|
||||
. 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.
|
||||
+
|
||||
----
|
||||
$ 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 recommended way to run AsciiBinder is on a container image using link:https://podman.io/[Podman]. However, if you already have Docker on your system, you can use it in place of Podman.
|
||||
|
||||
[IMPORTANT]
|
||||
====
|
||||
@@ -87,6 +75,38 @@ Previously, installing AsciiBinder directly on your system was recommended. Howe
|
||||
Use AsciiBinder by running the container image.
|
||||
====
|
||||
|
||||
=== Installing Podman on your system
|
||||
|
||||
Install Podman so that you can run the AsciiBinder container image on your machine.
|
||||
|
||||
If you are using Fedora, from a command line, enter:
|
||||
|
||||
[source,terminal]
|
||||
----
|
||||
$ sudo dnf install podman
|
||||
----
|
||||
|
||||
If you are using another operating system, follow the link:https://podman.io/docs/installation[Podman installation docs].
|
||||
|
||||
=== Building the documentation
|
||||
|
||||
Run the container image with an AsciiBinder command to build the OpenShift documentation.
|
||||
|
||||
. From a command line, change to the `openshift-docs` directory.
|
||||
|
||||
. To build every distribution in the docs, enter the following command:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ podman run --rm -it -v `pwd`:/docs:Z quay.io/openshift-cs/asciibinder asciibinder build
|
||||
----
|
||||
+
|
||||
The `asciibinder build` command runs within the image. The AsciiDoc files are transformed into HTML files in your local repository under the `_preview` directory. By default, AsciiBinder generates a documentation set for each distribution.
|
||||
|
||||
TIP: To choose which link:https://github.com/openshift/openshift-docs/blob/main/contributing_to_docs/doc_guidelines.adoc#product-title-and-version[distributions] to build, use the `-d` option in the command. For example, to only build `openshift-enterprise`, change `asciibinder build` to `asciibinder build -d openshift-enterprise`.
|
||||
|
||||
|
||||
|
||||
== Next steps
|
||||
With the repository and tools set up on your workstation, you can now either
|
||||
edit existing content or create assemblies and modules.
|
||||
|
||||
Reference in New Issue
Block a user