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/template/sec_template_structure.xml

71 lines
5.6 KiB
XML

<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
<literal>Docs-Master</literal> and <literal>Docs-Template</literal>, both existing OpenPOWER Foundation GitHub projects 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 get the green directories and files by cloning <literal>Docs-Master</literal>, blue
directories and files by cloning <literal>Docs-Template</literal>, and the red files by cloning a hypothetical project
<literal>my_project</literal>.</para>
<para>Among these directories, 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" 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 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/template</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 depected 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>