1
0
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:
Max Bridges
2024-05-23 17:21:26 -04:00
parent a569396dd7
commit 665a42441a

View File

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