Contains information about how to add and modify Trafodion documentation that is part of the Trafodion source tree. This documentation is written in asciidoc.
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 |
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.
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 |
Publish
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.