Understanding the project structureThe OpenPOWER Foundation documentation build process involves dependency on a common
framework and shared files. As such a deeper explanation about the relationships of key projects and their
components may be helpful to prevent and diagnose documentation build problems. This section
provides a pictorial layout of key files and explains their roles and relationships.As mentioned multiple times throughout this guide, successful build of any OpenPOWER Foundation
document requires two things:The cloning of the Docs-Master project.The cloning of the specific documentation project into the same parent directory as the
Docs-Master project.To begin to understand why, let us use a picture. The following graphic illustrates
the directory structure of three projects -- two
Docs-Master and Docs-Template, both existing OpenPOWER Foundation GitHub projects and a
hypothetical new project named my_project.To create this structure, one would clone the Docs-Master project to
get the Docs-Master directory and all its contents (shown above in green),
clone the Docs-Template project to get the Docs-Template directory
and all its contents (shown in blue), and clone my_project project to get the
my_project directory and all its contents (shown in red).Among these projects, the most important directory and project is Docs-Master. Without this project
and associated directory, no document will build. As depicted in the above figure, the Docs-Master directory
must sit at a level equal to all other project directories. Details on how to install this project can be found in the
section.Inside the Docs-Masterproject directory, the two most important pieces are a
commmon directory
and a pom.xml file. The directory contains common files used by all projects such as the common preface
(ch_preface.xml) and the common appendix (app_foundation.xml. The pom.xml file
in this directory serves as the "Master POM" for all builds. This file references the OpenPOWER Maven Plugin JAR
(found in the OpenPOWER Foundation Repository at
http://openpowerfoundation.org/repo.openpowerfoundation.org/)
used to control the OpenPOWER
Foundation document builds where all other dependencies, supporting tools, and document build rules are defined. The Docs-Template project and directory are depicted in blue in the above figure. The top level of the
project Docs-Template must be cloned into the same parent directory as the Docs-Master
for Maven builds to complete successfully.
At the top level of the Docs-Template project
are a pom.xml referred to as the "Workgroup POM" and a single document directory (template).
The "Workgroup POM" is a minimal POM file that locates the parent, "Master POM" in the Docs-Masterproject directory
with a <relativePath> definition of ../Docs-Master/pom.xml.
The document directory contains the unique files used to create the document. The two most important files in the
Docs-Template/template directory(and in any project) are the pom.xml or "Document POM" which describes
how to build the document and which points to the main document file, the bk_main.xml file. This book file
contains all the Docbook source, directly or through include statements (<xi:include href="..."),
to build the document.For completeness of understanding, a hypothetical project my_project is also depected in red. Like all
OpenPOWER Foundation projects, it is cloned at the correct level, equal to Docs-Master. Like the
Docs-Template project, it has a "Workgroup POM" which will differ only in the <modules>
section where it will describe two document projects, my_doc_1 and my_doc_2. But, each
document directory has similar contents to Docs-Template/template -- a "Document POM" (pom.xml)
and a "Main book file" (bk_main.xml).