Skip to content

Latest commit

 

History

History
78 lines (52 loc) · 3.79 KB

README.md

File metadata and controls

78 lines (52 loc) · 3.79 KB
Raw

Foreman Guides

This is upstream source code of Red Hat Satellite 6 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.

Building

Install required tools:

dnf -y install ruby asciidoctor asciidoctor-pdf make

If AsciiDoctor is not available in repositories or under RVM/rbenv, simply install it from rubygems:

gem install asciidoctor asciidoctor-pdf --pre

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. To build downstream version perform make BUILD=satellite.

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

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.

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

Contributing

Please read Guidelines for Red Hat Documentation before opening a Pull Request. Additional rules apply:

Never write "Foreman" or "Satellite" words directly but use the following variables:

Variable Upstream value Downstream value
{ProjectNameXY} Foreman 1.22 Red Hat Satellite 6.5
{ProjectNameX} Foreman Red Hat Satellite 6
{ProjectName} Foreman Red Hat Satellite
{ProjectXY} Foreman 1.22 Satellite 6.5
{ProjectX} Foreman Satellite 6
{Project} Foreman Satellite
{SmartProxyServer} Smart Proxy server Capsule Server
{SmartProxy} Smart Proxy Capsule

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" or "satellite":

ifeval::["{build}" == "foreman"]
NOTE: This part is only relevant for deployments with Katello plugin.
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.

The process (TODO)

This is what we are working on right now:

  • Initial import of Provisioning Guide
  • Provide Makefiles and Travis integration
  • Replace Satellite 6 with Foreman term
  • Modularize content
  • Hide irrelevant chapters
  • Incorporate parts from upstream docs
  • Incorporate https://community.theforeman.org/t/discovery-ipxe-efi-workflow-in-foreman-1-20/13026
  • Write better introduction
  • Add Anaconda-image based provisioning workflow
  • Update with PXE Grub2 steps
  • Discuss with Foreman community if to continue with other guides