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.
71 lines
5.6 KiB
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><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><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><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>
|
|
|