spl-make-doc

The spl-make-doc command generates documentation for your toolkits.

Usage

Figure 1. spl-make-doc

spl-make-doc -h, --help |
  [--author [<name>]] [--check-tags] [-c, --clean] [--copy-image-files]      
	[--doc-title <title>] [ -i, --directory <toolkit-dir> ] [--image-format <format>]     
	[--include-all] [--include-composite-operator-diagram] 
	[--include-excluded-artifacts]
  [--include-function-set-header]
  [--include-private-artifacts] 	[--include-source] [--keep-dita-files] 
  [--output-directory <path>] [--suppress-primitive-operator-diagram] 
  [--suppress-reference-docs] [ -t, --toolkit-path <toolkit-path> ]     
	[-v, --verbose-mode] [--warn-no-comments] 
  [--warn-on-cross-link-error][-x, --output-format <format>]     
	[<mixed-mode-arguments>]

Authority

You do not need any authority to run this command.

Description

You can augment the documentation for your toolkits by adding SPDOC markup comments to the SPL artifacts. The documentation that is generated by the spl-make-doc command can include both text and images.

To generate documentation for a single toolkit, use the -i or --directory options. To generate documentation for multiple toolkits, use the -t or --toolkit-path options.

By default, the spl-make-doc command generates documentation for the external interfaces of the toolkits. This information is helpful for the toolkit users. To generate more internal details for toolkit developers, specify options such as --include-excluded-artifacts or --include-all.

To view the documentation, find the html/index.html file in the output directory and open it in a web browser.

Note: This command does not report formatting errors.

Options and arguments

--author name

Specifies to include the name of the toolkit author in the documentation. The name value is optional; if it is not specified, the current user name is used.

--check-tags

Specifies to treat unrecognized SPLDOC tags as warnings. Without this option, unrecognized SPLDOC tags are ignored.

-c, --clean

Specifies to delete all of the documentation artifacts from the output directory.

--copy-image-files

Specifies to copy any embedded image files that are referenced by the SPLDOC markup to the output directory and use a relative path to the image in the generated documentation. When this option is not specified, the image files are referenced by an absolute path.

--doc-title title

Specifies the title that is used for the documentation.

-h, --help

Specifies to show the command syntax and help information.

-i, --directory toolkit-directory

Specifies the directory for a single toolkit. By default, the toolkit directory is set to the current directory. The toolkit is first indexed by running the spl-make-toolkit command.

You cannot specify this option with the -t or --toolkit-path options.

--image-format format

Specifies the format of generated image files for composite and primitive operators. The following formats are valid:

addjpeg: Generates both JPEG (Joint Photographic Experts Group) and SVG (Scalable Vector Graphics) images. The SVG images are referenced by the generated documentation, and the additional JPEG images can be used by an external DITA file processor that allows JPEG images to be selected when a browser does not support SVG images.
jpegonly: Generates only JPEG images.
svg: Generates only SVG files.

By default, the command generates only SVG files.

--include-all

Specifies to include all --include options.

--include-composite-operator-diagram

Specifies to include the composite operator graph diagrams. Without this option, these diagrams are excluded.

--include-excluded-artifacts

Specifies to include artifacts even if they are excluded by the @exclude SPLDOC annotation tag.

--include-function-set-header

Specifies to include C++ native function set headers. If you do not specify this option, the headers are not output.

--include-private-artifacts

Specifies to include all private artifacts. By default any non-public (private) composite operators, composite static types, and SPL functions are not included.

--include-source

Specifies to include the SPL source code in the documentation.

--keep-dita-files

Specifies that the DITA files that are used to generate the HTML documentation must not be deleted.

mixed-mode-arguments

If you use the -i or --directory options, any additional arguments are assumed to be mixed-mode arguments and are passed to the spl-make-toolkit command for indexing the toolkit. For more information about valid mixed mode arguments, see the spl-make-toolkit command. If you use the -t or --toolkit-path options, mixed mode arguments are not supported; the command fails.

--output-directory path

Specifies the directory where the documentation is output. The default value is the doc/spldoc directory. If you use the -i option, the path is relative to the toolkit directory. If you use the -t option, the path is relative to the current directory. If the output directory does not exist, the directory is created.

--suppress-primitive-operator-diagram

Specifies that the output does not include diagrams that show the properties of the primitive operators.

--suppress-reference-docs

Specifies that the output does not include reference documents for the operator and function models.

-t, --toolkit-path toolkit-path

Specifies one or more directory paths to toolkit root directories, which are separated by a colon (:). Each directory path can contain the root directory of a toolkit or a directory that contains one or more root directories.

Toolkits must already be indexed. If a toolkit is not already indexed, you can index it with the spl-make-toolkit command.

This option cannot be used with the -i, --directory, or mixed-mode-arguments options.

-v, --verbose-mode

Specifies to provide more detailed command output.

--warn-no-comments

Specifies to generate warning messages for SPL artifacts that do not have SPLDOC comments.

--warn-on-cross-link-error

Specifies to generate warning messages instead of error messages for broken links to SPL artifacts in toolkits or namespaces that are not in the documentation. You can use this option, for example, when there is a link to an artifact in another toolkit, but that toolkit is not included in the documentation.

-x, --output-format format

Specifies the format of the documentation. The following formats are valid:

ditaonly: Generates only DITA files.
xhtml: Generates HTML files.

By default, the command generates HTML files.

Examples

The following examples illustrate typical options that you might choose when you run spl-make-doc:

To generate documentation for a single toolkit in the current directory, run the command with the following parameters:
```
spl-make-doc -i .
```
The period after -i specifies the current directory.
You can direct the documentation output to a directory other than the default by using the --output-directory parameter. For example, by running the spl-make-doc command with the following output directory, you can view the generated toolkit documentation by opening the ~/myspldoc/html/index.html file
```
spl-make-doc -i . --output-directory ~/myspldoc 
```
To generate documentation that includes all of the information that is optional and is not included by default, run the command with the following parameters:
```
spl-make-doc -i toolkitRootDirectory --include-all 
```
You can generate documentation that includes only some of the information that is optional and is not included by default. For example, the following command includes the composite operator graph without including the other optional information:
```
spl-make-doc -i toolkitRootDirectory --include-composite-operator-diagram
```
To generate documentation for a mixed-mode SPL application that requires preprocessing parameters, specify the mixed-mode parameters on the spl-make-doc command, as follows:
```
spl-make-doc -i . [options] [mixed-mode-parameters]
```
For example, the following command passes the preprocessing argument of 3 to the toolkit MixedMode. The spl-make-doc command generates one or more .spl files from the .splmm files by using the mixed-mode parameter, and then generates the SPL documentation.
```
spl-make-doc -i MixedMode 3
```
To generate a single set of documentation for multiple toolkits, where the first toolkit is in a separate directory from the other toolkits, and the remaining toolkits share their parent directory.
```
spl-make-doc -t toolkitRootDirectory:directoryContainingToolkitRootDirectories
```