package xdc.tools.cdoc
index URL

RTSC documentation generator

cdoc is a package documentation generation utility. It builds a directory of browsable HTML documentation using the meta- information stored in RTSC packages. [ more ... ]
XDCspec declarations sourced in xdc/tools/cdoc/package.xdc
package xdc.tools.cdoc [1, 0, 0, 0] {
 
    module Example;
    // XDOC markup language examples for modules and interfaces
    module Main;
    // Command implementation
    module Markup;
    // XDCspec doc markup language examples
}
USAGE
xs xdc.tools.cdoc [--help]
    [-od:dir] [-title text] [--start package] [--indexonly] [--doxytags file] [--doxybase dir] [-h] [-n] [-b] [-s] [-P pkg-dir...|-Pr repo-dir...|-A]
OPTIONS
-od
Place the generated files in the named directory
-title
Generated HTML pages will show the string in the page title
--start
Set start page to specified package

The opening page is, by default, the documentation for the alphabetically first package processed. This option allows you to explicitly specify the package used.

If "" is specified, the start page will be blank.

If the package specified is not processed, no warning or error results; it is assumed that when the documentation is used the specified package documentation will exist.

-s
Include .xdc file sources

In the generated documentation for each .xdc file, link to a pretty-printed view of the .xdc file source text.

-P
The subsequent directories are package directories

Generates documentation for each of the specified packages.

-Pr
The subsequent directories are repositories of packages

Generates documentation for all packages rooted in each of the specified repositories.

-A
Generate documentation for all packages on the package path
-b
Generate a single "big" output
-h
Generate html pages only, not table of contents or index
-n
Generate nodoc'd docs
--quiet
Quiet mode
--indexonly
Generate index and table of contents only
--doxytags
Process doxygen links, using this argument as the tag file
--doxybase
The directory containing doxygen html files
--style
Use specified style sheet
-l
Language to document. Deprecated
-L
Don't include dependent packages. Deprecated
DETAILS
cdoc is a package documentation generation utility. It builds a directory of browsable HTML documentation using the meta- information stored in RTSC packages.
This utility is invoked via the XDCtools xs command. In the examples below we assume that the alias cdoc is defined as follows:
      $(XDCROOT)/xs xdc.tools.cdoc
where $(XDCROOT) is the installation directory of the XDCtools toolset.
EXAMPLES
In the examples below we assume that the alias cdoc is defined as $(XDCROOT)/xs xdc.tools.cdoc, where $(XDCROOT) is the installation directory of the XDCtools toolset.
1. To generate documentation for the package in the current working directory:
      cdoc
Since no package is specified and no output directory is specified, documentation is generated for the package in the current working directory and the output is placed in the package's ./package/cdoc sub-directory.
2. To generate documentation with the title "My Packages" for all packages installed in the myPackages repository:
      cdoc -title "My Packages" -Pr myPackages
Since no output directory was specified and documentation will be for more than one package, the generated files are placed in the directory ./cdoc.
3. To generate documentation for the package located in ./ti/bios and put results in the directory ./html.
      cdoc -od:html -P ti/bios
NOTE
cdoc processes the XML files that are generated *after* a package is built (actually after the .interfaces goal is built). One must first build a package before generating its documentation. If you change a .xdc file and re-run cdoc without rebuilding the package, the change in the .xdc file will not show up in the generated docs.
When interatively updating a package's .xdc files and examining the generated documentation, it is useful to define a command alias that first "compiles" the package's .xdc files and then runs the cdoc tool. For example, if your shell is Korn shell compatible, the following command alias ensures that any changes in .xdc files will show up in the generated documents:
      function cdoc {
          $XDCROOT/xdc .interfaces
          $XDCROOT/xs xdc.tools.cdoc $*
      }
generated on Tue, 24 Aug 2010 15:39:20 GMT