1 /*
2 * Copyright (c) 2008 Texas Instruments and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 * Texas Instruments - initial implementation
10 *
11 * */
12 package xdc.tools.cdoc;
13
14 /*!
15 * ======== xdc.tools.cdoc.Main ========
16 * RTSC documentation generator
17 *
18 * cdoc is a package documentation generation utility. It builds a
19 * directory of browsable HTML documentation using the meta-
20 * information stored in RTSC packages.
21 *
22 * This utility is invoked via the XDCtools `xs` command. In the
23 * examples below we assume that the alias `cdoc` is defined as
24 * follows:
25 * @p(code) 26 * $(XDCROOT)/xs xdc.tools.cdoc
27 * @p 28 * where $(XDCROOT) is the installation directory of the XDCtools toolset.
29 *
30 * @a(Examples) 31 * In the examples below we assume that the alias `cdoc` is defined as
32 * `$(XDCROOT)/xs xdc.tools.cdoc`, where `$(XDCROOT)` is the installation
33 * directory of the XDCtools toolset.
34 *
35 * 1. To generate documentation for the package in the current working
36 * directory:
37 * @p(code) 38 * cdoc
39 * @p 40 * Since no package is specified and no output directory is specified,
41 * documentation is generated for the package in the current working
42 * directory and the output is placed in the package's `./package/cdoc`
43 * sub-directory.
44 *
45 * 2. To generate documentation with the title "My Packages" for all
46 * packages installed in the `myPackages` repository:
47 * @p(code) 48 * cdoc -title "My Packages" -Pr myPackages
49 * @p 50 * Since no output directory was specified and documentation will be for
51 * more than one package, the generated files are placed in the directory
52 * `./cdoc`.
53 *
54 * 3. To generate documentation for the package located in `./ti/bios` and
55 * put results in the directory `./html`.
56 * @p(code) 57 * cdoc -od:html -P ti/bios
58 * @p 59 *
60 * @a(Note) 61 * `cdoc` processes the XML files that are generated *after* a package
62 * is built (actually after the `.interfaces` goal is built). One must first
63 * build a package before generating its documentation. If you change a
64 * `.xdc` file and re-run `cdoc` without rebuilding the package, the change
65 * in the `.xdc` file will not show up in the generated docs.
66 *
67 * When interatively updating a package's .xdc files and examining the
68 * generated documentation, it is useful to define a command alias that
69 * first "compiles" the package's .xdc files and then runs the cdoc tool.
70 * For example, if your shell is Korn shell compatible, the following
71 * command alias ensures that any changes in .xdc files will show up in the
72 * generated documents:
73 * @p(code) 74 * function cdoc {
75 * $XDCROOT/xdc .interfaces
76 * $XDCROOT/xs xdc.tools.cdoc $*
77 * }
78 * @p 79 */
80
81 metaonlymodule Main inherits xdc.tools.ICmd {
82 overrideconfig String usage[] = [
83 '[-od:dir] [-title text] [--start package] [--indexonly] [--doxytags file] [--doxybase dir] [-h] [-n] [-b] [-s] [-P pkg-dir...|-Pr repo-dir...|-A]'
84 ];
85
86 instance:
87
88 /*!
89 * Place the generated files in the named directory.
90 */
91 @CommandOption("-od")
92 config String outdir = null;
93
94 /*!
95 * Generated HTML pages will show the string in the page title
96 */
97 @CommandOption("-title")
98 config String title = null;
99
100 /*!
101 * Set start page to specified package
102 *
103 * The opening page is, by default, the documentation for the
104 * alphabetically first package processed. This option allows
105 * you to explicitly specify the package used.
106 *
107 * If "" is specified, the start page will be blank.
108 *
109 * If the package specified is not processed, no warning or error
110 * results; it is assumed that when the documentation is used the
111 * specified package documentation will exist.
112 */
113 @CommandOption("--start")
114 config String start = null;
115
116 /*!
117 * Include .xdc file sources
118 *
119 * In the generated documentation for each .xdc file, link
120 * to a pretty-printed view of the .xdc file source text.
121 */
122 @CommandOption("s")
123 config Bool sopt = false;
124
125 /*!
126 * The subsequent directories are package directories.
127 *
128 * Generates documentation for each of the specified packages.
129 */
130 @CommandOption("P")
131 config Bool popt = false;
132
133 /*!
134 * The subsequent directories are repositories of packages.
135 *
136 * Generates documentation for all packages rooted in each of
137 * the specified repositories.
138 */
139 @CommandOption("-Pr")
140 config Bool ropt = false;
141
142 /*!
143 * Generate documentation for all packages on the package path.
144 */
145 @CommandOption("A")
146 config Bool aopt = false;
147
148 /*!
149 * Generate a single "big" output
150 */
151 @CommandOption("b")
152 config Bool bopt = false;
153
154 /*!
155 * Generate html pages only, not table of contents or index
156 */
157 @CommandOption("h")
158 config Bool hopt = false;
159
160 /*!
161 * Generate nodoc'd docs
162 */
163 @CommandOption("n")
164 config Bool nopt = false;
165
166 /*!
167 * Quiet mode
168 */
169 @CommandOption("--quiet")
170 config Bool qopt = false;
171
172 /*!
173 * Generate index and table of contents only
174 */
175 @CommandOption("--indexonly")
176 config Bool iopt = false;
177
178 /*!
179 * Process doxygen links, using this argument
180 * as the tag file
181 */
182 @CommandOption("--doxytags")
183 config String doxytags = null;
184
185 /*!
186 * The directory containing doxygen html files
187 */
188 @CommandOption("--doxybase")
189 config String doxybase = null;
190
191 /*!
192 * Use specified style sheet
193 */
194 @CommandOption("--style")
195 config String style = null;
196 /*!
197 *
198 * Language to document. Deprecated.
199 */
200 @CommandOption("l")
201 config String language = null;
202
203 /*!
204 * Don't include dependent packages. Deprecated.
205 *
206 */
207 @CommandOption("L")
208 config Bool lopt = false;
209
210 }
211
212
213 /*
214 * @(#) xdc.tools.cdoc; 1, 0, 0, 0,239; 7-14-2011 17:22:51; /db/ztree/library/trees/xdc/xdc-x16x/src/packages/
215 */
216