Embedded Documentation

Overview

Documentation can be embedded in a Partner installation in a variety of ways, but the current standard is to place the documentation within a module or mapset, in one of several predefined locations.

The Help/Documentation menu item, found in most top-level Partner programs, generates an HTML index of available documentation appropriate to the user’s context by examining the filesystem, then opens it in the OS web browser. Since the modules and mapsets involved vary by customer or even individual installation, this is not a single standard listing.

Types of Embedded Documentation

These major categories of embedded documentation are supported:

  • User Manuals - formal user documentation,
  • Mapset Manuals - user manuals for a specific mapset,
  • Workbench Manuals - manuals intended only for Workbench users,
  • Module Manuals - manuals associated with the module, and
  • Module Documentation - other documentation for the module.

User Manuals are always displayed in the Documentation index, and are given the highest priority.

Mapset Manuals are only displayed if the Map Viewer is open and if that mapset is marked as loaded in Preferences.

Workbench Manuals, Module Manuals, and Module Documentation are only displayed if the Workbench is open. The distinction between these three types is not strong at the moment; all three are included to a large extent because they have been used historically.

However, here is the intended distinction:

  • a Workbench Manual is a technical manual that addresses broader topics and not just the module containing them;
  • Module Manuals are specific to the module, but are designed as instructional manuals; and
  • Module Documentation may include housekeeping, implementation details, change logs and other janitorial tidbits about the module.

File Paths and Index Generation

The HTML index file generator is located in com.partnersoft.help.HelpLib. It uses the following path patterns to find documentation. It looks for index.html files only; however you may use those to link to PDF or other types of documentation.

User Manuals

User manuals are placed in individual directories beneath the module in doc/user/. Each subdirectory must have a corresponding index.html file.

This means you can have more than one manual in a module.

For example, a manual named “My Awesome Manual” in module “MyManuals” would need to have at least an index file in MyManuals/doc/user/My Awesome Manual/index.html.

Mapset Manuals

Mapset manuals must start with an index file in the doc/manual/index.html under the mapset directory. Generally this should be placed in the module’s copy of the mapset if it’s a modular mapset.

This means you can only have one manual per mapset.

For example, the manual for mapset “Mappity Map” in module “MappityModule” would need to have an index file in MappityModule/mapsets/Mappity Map/doc/user/index.html.

Workbench Manuals

Workbench Manuals are only one to a module, and must begin with the file workbench/doc/manual/index.html under the module’s root.

Module Manuals

Module Manuals are only one to a module, and must begin with the file doc/manual/index.html under the module’s root.

Module Documentation

Module Documentation is only one to a module, and must begin with the file doc/index.html under the module’s root.

DocumentationTest Module

A module for testing the documentation framework is also useful as an example of the above paths and their behavior.

Here is a listing of the index.html files in that module:

DocumentationTest/doc/index.html
DocumentationTest/doc/manual/index.html
DocumentationTest/doc/user/Documentation Test User Manual/index.html
DocumentationTest/mapsets/DocumentationTest/doc/manual/index.html
DocumentationTest/workbench/doc/manual/index.html

Building Module Manual From Markdown

Our current convention for Module Manual is to write it in the markdown format and have the build system generate the HTML version from that source.

Place the source under source/markdown/doc/manual/index.md.

The build system will generate the corresponding html into build/unpacked/MODULE/doc/manual/index.html.

You should mark installation/doc/manual as svn:ignore to avoid committing documentation there.

Manual Manual Generation

Other manuals are typically generated manually from other sources, and placed in the installation/ hierarchy of the module for the build process to include as it does other files.

If the manual source is included with the module’s source, it should be placed under source/ and an appropriate subdirectory - e.g. source/markdown, source/sphinx, etc.