From 665a42441a281966734b73e1d27dfbee7d059196 Mon Sep 17 00:00:00 2001 From: Max Bridges Date: Thu, 23 May 2024 17:21:26 -0400 Subject: [PATCH] Update tools page - macOS guidance now doesn't seem so shaky. - Default to podman - Link out to podman installation docs for non-Fedora OSes --- contributing_to_docs/tools_and_setup.adoc | 54 ++++++++++++++++------- 1 file changed, 37 insertions(+), 17 deletions(-) diff --git a/contributing_to_docs/tools_and_setup.adoc b/contributing_to_docs/tools_and_setup.adoc index f137af4197..df06706ffc 100644 --- a/contributing_to_docs/tools_and_setup.adoc +++ b/contributing_to_docs/tools_and_setup.adoc @@ -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//` 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.