You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
CAPI-SNAP-Doc/doc_dev_guide/sec_template_structure.xml

90 lines
6.5 KiB
XML

<!--
Copyright (c) 2016 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_structure">
<title xml:id="section_template_structure_title">Understanding the project structure</title>
<para>The 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.</para>
<para>As mentioned multiple times throughout this guide, successful build of any OpenPOWER Foundation
document requires two things:</para>
<orderedlist>
<listitem><para>The cloning of the <literal>Docs-Master</literal> project.</para></listitem>
<listitem><para>The cloning of the specific documentation project into the same parent directory as the
<literal>Docs-Master</literal> project.</para></listitem>
</orderedlist>
<para>To begin to understand why, let us use a picture. The following graphic illustrates
the directory structure of three projects: two existing OpenPOWER Foundation GitHub projects,
<literal>Docs-Master</literal> and <literal>Docs-Template</literal>, and a
hypothetical new project named <literal>my_project</literal>.</para>
<figure pgwide="1" xml:id="project_structure_label">
<title>Directory structure and key files in the OpenPOWER Foundation Docbook projects</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/project_structure_graphic.svg" format="SVG" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
<para>To create this structure, one would clone the <literal>Docs-Master</literal> project to
get the <literal>Docs-Master</literal> directory and all its contents (shown above in green),
clone the <literal>Docs-Template</literal> project to get the <literal>Docs-Template</literal> directory
and all its contents (shown in blue), and clone <literal>my_project</literal> project to get the
<literal>my_project</literal> directory and all its contents (shown in red).</para>
<para>Among these projects, the most important directory and project is <literal>Docs-Master</literal>. Without this project
and associated directory, no document will build. As depicted in the above figure, the <literal>Docs-Master</literal> directory
must sit at a level equal to all other project directories. Details on how to install this project can be found in the
<xref linkend="section_cloning_master_doc"/> section.</para>
<para>Inside the <literal>Docs-Master</literal>project directory, the two most important pieces are a
<literal>commmon</literal> directory
and a <literal>pom.xml</literal> file. The directory contains common files used by all projects such as the common preface
(<literal>ch_preface.xml</literal>) and the common appendix (<literal>app_foundation.xml</literal>). The <literal>pom.xml</literal> file
in this directory serves as the "Master POM" (POM stands for Program Object Model and serves as the main configuration file)
for all builds. This file references the OpenPOWER Maven Plugin JAR
(found in the OpenPOWER Foundation Repository at
<link xlink:href="http://openpowerfoundation.org/repo.openpowerfoundation.org/">http://openpowerfoundation.org/repo.openpowerfoundation.org/</link>)
used to control the OpenPOWER
Foundation document builds where all other dependencies, supporting tools, and document build rules are defined. </para>
<para>The <literal>Docs-Template</literal> project and directory are depicted in blue in the above figure. The top level of the
project <literal>Docs-Template</literal> must be cloned into the same parent directory as the <literal>Docs-Master</literal>
for Maven builds to complete successfully.
At the top level of the <literal>Docs-Template</literal> project
are a <literal>pom.xml</literal> referred to as the "Workgroup POM" and a single document directory (<literal>template</literal>).
The "Workgroup POM" is a minimal POM file that locates the parent, "Master POM" in the <literal>Docs-Master</literal>project directory
with a <literal>&lt;relativePath></literal> definition of <literal>../Docs-Master/pom.xml</literal>.
The document directory contains the unique files used to create the document. The two most important files in the
<literal>Docs-Template/doc_dev_guide</literal> directory (and in any project) are the <literal>pom.xml</literal> or "Document POM" which describes
how to build the document and which points to the main document file, the <literal>bk_main.xml</literal> file. This book file
contains all the Docbook source, directly or through include statements (<literal>&lt;xi:include href="..."</literal>),
to build the document.</para>
<para>For completeness of understanding, a hypothetical project <literal>my_project</literal> is also depicted in red. Like all
OpenPOWER Foundation projects, it is cloned at the correct level, equal to <literal>Docs-Master</literal>. Like the
<literal>Docs-Template</literal> project, it has a "Workgroup POM" which will differ only in the <literal>&lt;modules></literal>
section where it will describe two document projects, <literal>my_doc_1</literal> and <literal>my_doc_2</literal>. But, each
document directory has similar contents to <literal>Docs-Template/template</literal> -- a "Document POM" (<literal>pom.xml</literal>)
and a "Main book file" (<literal>bk_main.xml</literal>).</para>
</section>