Excerpt |
---|
Contains information about how to add and modify Trafodion documentation that is part of the Trafodion source tree. This documentation is written in asciidoc. |
...
Table of Contents |
---|
...
Source
Documents do not include version information as part of the file name.
Source Location
Document | Source Format | Source Tree | Output Format |
---|---|---|---|
Client Installation Guide | asciidoc | docs/client_install/ | Web Book, PDF |
Command Interface Guide | asciidoc | docs/command_interface/ | Web Book, PDF |
Contributor Guide | asciidoc | docs/contributor_guide/ | Web Book, PDF |
DCS Reference Guide | asciidoc | dcs/src/main/asciidoc/ | Web Book |
DCS APIs | javadoc | dcs/src/main/java/ | Web Book |
odb User Guide | asciidoc | docs/odb/ | Web Book, PDF |
Messages Guide | asciidoc | docs/messages_guide/ | Web Book, PDF |
REST Reference Guide | asciidoc | core/rest/src/main/asciidoc/ | Web Book |
REST APIs | javadoc | core/rest/src/main/java/ | Web Book |
SQL Reference Manual | asciidoc | /docs/sql_reference/ | Web Book, PDF |
Source Tree Organization
DCS and REST
To be written.
All Other
All other documents share a common web-book style sheet definition, which is located in docs/css/trafodion-manuals.css
.
The source tree for each manual is organized as follows:
File/Directory | Content |
---|---|
pom.xml | Maven Project Object Model (POM) used to build the document. |
src/ | The source files used to define the document. |
src/asciidoc | Asciidoc files for the document. |
src/asciidoc/index.adoc | Main asciidoc defining the document. Includes the different chapters from the |
src/asciidoc/_chapters/ | Source files for the different chapters in the document. |
images/ | Images used in the document. |
resources/ | Other include materials; for example, source examples that are included with the document. |
target/ | Build output directory. Contains the web book, the PDF file, and supporting directories. |
target/index.pdf | Generated PDF version of the document. |
target/images/ | Copy of the |
target/resources/ | Copy of the |
target/site/ | Generated web-book directory. |
target/site/index.html | Generated web book. |
target/site/css/ | Style sheets related to the web book. The common style sheet is included in the index.html file. |
target/site/images/ | Copy of the |
target/site/resources/ | Copy of the |
Anchor modifying-documentation-making-changes modifying-documentation-making-changes
Making Changes
Please refer to the following web sites for guidance for information about working on asciidoc-based documentation.
Once you’ve made the desired changes, then do the following:
DCS and REST
- Build the document using
mvn clean site
against the directory containing the document; for example:dcs
orcore/rest
. Verify the content in the generated
target
directory. Thetarget/index.html
file provides the entry point for the web book; thetarget/apidocs/index.html
file contains the entry point for API documentation.
Other Documentation
- Build the document using
mvn clean site
against the directory containing the document; for example:docs/client_install
ordocs/odb_user
. Verify the content in the generated
target
directory. Thetarget/index.pdf
file contains the PDF version of the document whiletarget/site/index.html
contains the web-book version of the document.
Anchor | ||||
---|---|---|---|---|
|
Build Trafodion Document Tree
The external version of the Trafodion Document Tree is published to http://trafodion.incubator.apache.org/docs. Please refer to Publish below.
The build version of the Trafodion Document Tree is located in docs/target/docs
, which is created when you build the Trafodion web site in Maven.
...
Version Directories
The Trafodion Document Tree consists of Version Directories:
Version Directory | Content | Web Site Directory |
---|---|---|
latest | Known place for the latest version of a document. | trafodion.incubator.apache.org/docs/<document-name> |
<version> | Release-specific version of a document. | trafodion.incubator.apache.org/docs/<version>/<document-directory> |
latest
: Provides a well-known place for each document. This practice makes it possible to link to a document in instructional text, web sites, and other documents.<version>
: Provides per-release versions of documents. Previous versions are kept in the web site’s SVN repository ensuring that N versions of the documentation are available.
Document Directories
Each document is placed in its own Document Directory:
Document | Document Directory Name |
---|---|
Client Installation Guide | client_install |
Command Interface Guide | command_interface |
Contributor Guide | contributor_guide |
DCS Reference Guide | dcs_reference |
odb User Guide | odb_user |
Messages Guide | messages_guide |
REST Reference Guide | rest_reference |
SQL Reference Manual | sql_reference |
The Document Directories are organized as follows. Files and sub-directories may or may not be present in the Document Directory depending on document.
File/Directory | Content |
---|---|
*.pdf | The PDF version of the document. For example, Trafodion_SQL_Reference_Guide.pdf . |
index.html | The web book version of the document. Generated by asciidoc. |
apidocs | API documentation provided as a web book. Generated by javadoc. |
apidocs/index.html | Entry point for API documentation. Generated by javadoc. |
css | CSS definitions used by the web-version of the document. Populated by asciidoc. |
images | Images used by the web-version of the document. Populated by asciidoc. |
resources | Resource files referenced for source download etc. Populated by asciidoc. |
The Document Directories are copied under the Version Directories thereby creating the web-accessible Trafodion document tree.
Populate Trafodion Document Tree
The build version of the Trafodion Document Tree is populated as follows:
Document | Instructions |
---|---|
Client Installation Guide | Run maven |
Command Interface Guide | Run maven |
DCS Reference Guide Guide | Do the following:
|
odb User Guide | Run maven |
Messages Guide | Run maven |
REST Reference Guide Guide | Do the following:
|
SQL Reference Manual | Run maven |
Anchor modify-documentation-publish modify-documentation-publish
Publish
...
Info |
---|
Publication is done when a committer is ready to update the external web site. You do not perform these steps as part of checking in changes. |
Do the following:
- Build the web site.
- Build the different document as described in Making Changes above.
- Build the Trafodion Document Tree as described in Build Trafodion Document Tree above.
The resulting docs/target/docs/
directory is checked into the web-site SVN branch.