Skip to content

Latest commit

 

History

History
203 lines (131 loc) · 10.1 KB

README.md

File metadata and controls

203 lines (131 loc) · 10.1 KB
Raw

Foreman Guides

This is upstream source code of Red Hat Satellite 6 documentation as well as parts of the orcharhino documentation. All content in this repository uses AsciiDoctor syntax and aims to follow Guidelines for Red Hat Documentation. This is a work in progress, an attempt to take content written by Red Hat documentation team, modularize it, incorporate existing documentation and eventually make this the only and official documentation for Foreman, Katello and all plugins.

Contributions are welcome. Please read the Contribution guidelines before opening a Pull Request.

Building

Install the required tools. In Fedora perform:

dnf -y install make linkchecker

In MacOS required tools can be installed via brew but instead "make" call "gmake":

brew install make

Alternatively, XCode development environment can be installed to have make utility available on PATH, however this takes about an hour to download and install and requires several gigabytes of HDD space:

	xcode-select --install

Install ruby gems in foreman-documentation folder:

	bundle install

Then simply run make or make html which builds HTML artifacts. Generating PDF output is slow, therefore command make pdf must be used separately. To make both formats in one command, use make html pdf.

Few additional make targets are available on the guide level. To quickly build HTML version and open new tab in a browser do:

cd doc-Provisioning_Guide
make browser

Similarly, to build and open PDF version do:

make open-pdf

To speed up the build process, make sure to use -j option. Ideally, set it to amount of cores plus one:

	make -j9

An alias is often useful:

	alias make="make -j$(nproc)"

Currently there are three different versions:

make BUILD=foreman-el - This is the default that is generated with make html or pdf.

make BUILD=satellite - This generates a downstream preview of the guide.

make BUILD=katello - this generates a katello build of the guide

make BUILD=foreman-deb - This generates a version for Foreman installed on Debian.

make BUILD=orcharhino - This generates a downstream preview of the guide for orcharhino.

The final artifacts can be found in the ./build subdirectory. Note that GNU Makefile tracks changes and only builds relevant artifacts, to trigger full rebuild use make clean to delete build directory and start over.

It's also possible to check links; the following command will check all links except example.com domain:

make linkchecker

Building Locally Using a Container

You can build Foreman documentation locally using a container image. This requires the cloned git repository plus an application such as Podman or Docker to build and run container images.

  1. Build container image:

    podman build --tag foreman_documentation .

  2. Build Foreman documentation. Run this command in your foreman-documentation repository:

    rm -rf guides/build && podman run --rm -v $(pwd):/foreman-documentation foreman_documentation make html

    On SELinux enabled systems, run this command:

    rm -rf guides/build && podman run --rm -v $(pwd):/foreman-documentation:Z foreman_documentation make html

Reading or Publishing

We do not publish the content yet to prevent users confusion, however this section will cover steps required to publish the content. We should make sure that only the last stable version of the HTML document is indexed by search engines, old and nightly builds should not be indexed. All PDFs should be available for download though.

Contribution guidelines

Please read these guidelines before opening a Pull Request. For more information, see Guidelines for Red Hat Documentation.

Variables

The content in this repository is shared between the upstream Foreman community and branded downstream products such as Red Hat Satellite and orcharhino by ATIX. Therefore, never write "Foreman", "Satellite", or "orcharhino" words directly, but use the following variables:

Variable Upstream value Downstream by Red Hat Downstream by ATIX
{Project} Foreman Satellite orcharhino
{ProjectName} Foreman Red Hat Satellite orcharhino
{ProjectServer} Foreman server Satellite Server orcharhino server
{SmartProxy} Smart Proxy Capsule orcharhino Proxy
{SmartProxyServer} Smart Proxy server Capsule Server orcharhino Proxy

Every build uses common base attributes, more are defined in the build specific attribute files:

By default, variables cannot be used in shell or code examples. To use them, use "attributes" keyword:

[options="nowrap" subs="+quotes,attributes"]
----
# ls {VariableName}
----

Hide or show specific blocks, paragraphs, warnings or chapters via special variable called "build". Its value can be set either to "foreman-el" or "satellite":

ifeval::["{build}" == "katello"]
NOTE: This part is only relevant for deployments with Katello plugin.
endif::[]

This syntax does not allow multiple conditionals, in that case use, now preferred, ifdef syntax:

ifdef::katello[]
NOTE: This part is only relevant for deployments with Katello plugin.
endif::[]

Use comma for logic "or":

ifdef::katello,satellite[]
NOTE: This part is only relevant for deployments with Katello plugin or in Satellite environment.
endif::[]

Some files are included in different contexts, there are attributes to find the correct context. In these cases use both ifdef and ifeval:

ifdef::foreman-el,foreman-deb[]
ifeval::["{context}" == "{project-context}"]
* A minimum of 4 GB RAM is required for {ProjectServer} to function.
endif::[]
endif::[]

When doing review, consider checking out the topic branch and putting necessary changes on top of author's work to making many comments on github.

Avoid using phrases like "Starting from version 6.5 or 1.22" because it is not possible to easily translate these strings into all streams.

Conventions

Use the following markup conventions:

  • User input is surrounded by underscores (_) to indicate variable input, e.g. hammer organization create --name "_My Organization_" --label "_my_organization_".
  • A single line only contains one sentence. Please do not wrap lines by hand. This makes git diff much easier to read and helps reviewing changes.
  • No trailing whitespace on lines and in files. Whitespace after partial files has to be handled in the file using the include:: directive.
  • Source files use UTF-8 character encoding.
  • Image file names use dashes (-) and suffix a build target, e.g. foreman.

Structure

If you create a new file, use the file structure described here.

Files that are included in more than one guide are kept in the common/ subdirectory, and have prefixes to distinguish their type of content.

Assemblies are kept at the top of the common/ subdirectory:

  • assembly: Files starting with assembly_ contain user stories and the modules required to accomplish those user stories. See the assembly template.

Modules are kept in the common/modules/ subdirectory:

  • con: Files starting with con_ contain concepts and explain the what and why. See the concept template.
  • proc: Files starting with proc_ contain procedures and explain how to achieve a specific goal. See the procedure template.
  • ref: Files starting with ref_ contain references and append other files, e.g. tables with options. See the reference template.
  • snip: Files starting with snip_ contain snippets that are reused throughout multiple guides, e.g. admonitions. Snippets do not require an ID.

Images

Each guide must have an images/ subdirectory with images/common symlink into the common/images directory. Images local to the guide shall be kept in the images/ directory. Images which are supposed to be reused across guides shall be kept in the images/common directory. Subdirectories can be created and are actually recommended. To insert an image, use image::common/global_image.png or image::local_image.png.

For more information, see the Modular Documentation Reference Guide.