- Timestamp:
- 09/08/10 14:51:38 (21 months ago)
- Location:
- trunk/reference
- Files:
-
- 2 modified
-
idldoc-reference.rst (modified) (2 diffs)
-
idldoc-tutorial.rst (modified) (12 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/reference/idldoc-reference.rst
r697 r699 7 7 8 8 9 Installation10 -------------------11 12 To install IDLdoc, simply unzip and place the IDLdoc `.sav` file, or the `src/` directory if you are installing the IDLdoc source distribution, in your IDL path.13 14 Do not separate the contents of the distribution; the code looks for files in locations relative to itself.15 16 17 9 `IDLDOC` routine keywords 18 10 ------------------------- … … 22 14 .. table:: Keywords for the `IDLDOC` routine 23 15 24 =================== ======================================================== 25 Keyword Description 26 =================== ======================================================== 27 `ASSISTANT` obsolete; no longer used 28 `BROWSE_ROUTINES` obsolete; no longer used 29 `CHARSET` set to the character set to be used for the output, 30 default is "utf-8" 31 `COMMENT_STYLE` output format for comments ("html", "rst", or "latex"); 32 default is "html" 33 `DEBUG` set to allow crashes with a stack trace instead of the 34 default simple message 35 `EMBED` embed CSS stylesheet instead of linking to it (useful 36 for documentation where individual pages must stand by 37 themselves) 38 `ERROR` set to a named variable to return the error state of the 39 IDLdoc call; 0 indicates no error, anything else is an 40 error 41 `FOOTER` filename of file to insert into the bottom of each page 42 of docs 43 `FORMAT_STYLE` style to use to parse file and routine comments ("idl", 44 "idldoc", "verbatim", or "rst"); default is "idldoc" 45 `HELP` set to print out the syntax of an IDLdoc call 46 `LOG_FILE` if present, send messages to this filename instead of 47 *stdout* 48 `MARKUP_STYLE` markup used in comments ("rst" or "verbatim"); default 49 is "verbatim" unless `FORMAT_STYLE` is set to "rst", in 50 which case, the default is "rst" 51 `N_WARNINGS` set to a named variable to return the number of warnings 52 for the IDLdoc run 53 `NONAVBAR` set to not display the navbar 54 `NOSOURCE` set to not put source code into output 55 `OUTPUT` directory to place output; if not present, output will 56 be placed in the `ROOT` directory 57 `OVERVIEW` filename of overview text and directory information 58 `PREFORMAT` obsolete; no longer used 59 `QUIET` if set, don't print info messages, only print warnings 60 and errors 61 `ROOT` root of directory hierarchy to document; this is the 62 only required keyword 63 `SILENT` if set, don't print any messages 64 `STATISTICS` set to generate complexity statistics for routines 65 `SUBTITLE` subtitle for docs 66 `TEMPLATE_PREFIX` prefix for template's names 67 `TEMPLATE_LOCATION` set to directory to find templates in 68 `TITLE` title of docs 69 `USER` set to generate user-level docs (private parameters, 70 files are not shown); the default is developer-level 71 docs showing files and parameters 72 `VERSION` set to print out the version of IDLdoc 73 =================== ======================================================== 16 ====================== ===================================================== 17 Keyword Description 18 ====================== ===================================================== 19 `ASSISTANT` obsolete; no longer used 20 `BROWSE_ROUTINES` obsolete; no longer used 21 `CHARSET` set to the character set to be used for the output, 22 default is "utf-8" 23 `COLOR_OUTPUTLOG` set to color output log messages, i.e., warning 24 messages are displayed in red; IDLdoc will attempt to 25 detect whether it is running from a terminal capable 26 of displaying color text, but this keyword can force 27 IDLdoc to attempt color display 28 `COMMENT_STYLE` output format for comments ("html", "rst", or 29 "latex"); default is "html" 30 `COMPLEXITY_CUTOFFS` McCabe complexity to exceed for a warning or flagged; 31 default is `[10, 20]` 32 `DEBUG` set to allow crashes with a stack trace instead of 33 the default simple message 34 `EMBED` embed CSS stylesheet instead of linking to it (useful 35 for documentation where individual pages must stand 36 by themselves) 37 `ERROR` set to a named variable to return the error state of 38 the IDLdoc call; 0 indicates no error, anything else 39 is an error 40 `FOOTER` filename of file to insert into the bottom of each 41 page of docs 42 `FORMAT_STYLE` style to use to parse file and routine comments 43 ("idl", "idldoc", "verbatim", or "rst"); default is 44 "idldoc" 45 `HELP` set to print out the syntax of an IDLdoc call 46 `LOG_FILE` if present, send messages to this filename instead of 47 *stdout* 48 `MARKUP_STYLE` markup used in comments ("rst" or "verbatim"); 49 default is "verbatim" unless `FORMAT_STYLE` is set to 50 "rst", in which case, the default is "rst" 51 `N_WARNINGS` set to a named variable to return the number of 52 warnings for the IDLdoc run 53 `NONAVBAR` set to not display the navbar 54 `NOSOURCE` set to not put source code into output 55 `OUTPUT` directory to place output; if not present, output 56 will be placed in the `ROOT` directory 57 `OVERVIEW` filename of overview text and directory information 58 `PREFORMAT` obsolete; no longer used 59 `QUIET` if set, don't print info messages, only print 60 warnings and errors 61 `ROOT` root of directory hierarchy to document; this is the 62 only required keyword 63 `SILENT` if set, don't print any messages 64 `ROUTINE_LINE_CUTOFFS` number of lines in a routine before warning or 65 flagged; default is `[75, 150]` 66 `SOURCE_LINK` by default, IDLdoc copies the source code into the 67 output; if this keyword is set to 1 (relative link) 68 or 2 (absolute link), then the output documentation 69 will point to the ROOT location of the original 70 source code 71 `STATISTICS` set to generate complexity statistics for routines 72 `SUBTITLE` subtitle for docs 73 `TEMPLATE_PREFIX` prefix for template's names 74 `TEMPLATE_LOCATION` set to directory to find templates in 75 `TITLE` title of docs 76 `USER` set to generate user-level docs (private parameters, 77 files are not shown); the default is developer-level 78 docs showing files and parameters 79 `VERSION` set to print out the version of IDLdoc 80 ====================== ===================================================== 74 81 75 82 -
trunk/reference/idldoc-tutorial.rst
r698 r699 12 12 IDLdoc generates nicely formatted API documentation directly from source code. If the documentation is close to the code it is much more likely to be kept up-to-date. As much as possible is generated directly from the source code itself. 13 13 14 Features?14 TODO: Features? 15 15 16 16 #. API documentation for both developers and users of the code base … … 28 28 29 29 This tutorial intends to get a new user up to speed in using IDLdoc in the simplest way using the newer, more modern style of IDLdoc commenting. Don't worry, though, IDLdoc still supports legacy commenting styles so you don't have to go changing existing documentation (unless you want to make use of some of the cool, new features!). Experienced users will probably learn some new things too, since documentation for IDLdoc has been spotty in the past. 30 31 32 Installation 33 ------------------- 34 35 To install IDLdoc, simply unzip and place the IDLdoc `.sav` file, or the `src/` directory if you are installing the IDLdoc source distribution, in your IDL path. 36 37 Do not separate the contents of the distribution; the code looks for files in locations relative to itself. 30 38 31 39 … … 53 61 This places the IDLdoc version information into the title/subtitle of the documentation. We'll talk about some of the other options in the following sections. 54 62 55 Note: By default, IDLdoc 3.0 copies source code into the output directory, so placing the output directory in your `!PATH` can cause IDL to choose the (possibly outdated) copy in the doc sover the correct source file. It is recommended to either place your docs outside your `!PATH` or use the `NOSOURCE` keyword.63 Note: By default, IDLdoc 3.0 copies source code into the output directory, so placing the output directory in your `!PATH` can cause IDL to choose the (possibly outdated) copy in the doc output directory over the correct source file. It is recommended to either place your docs outside your `!PATH` or use the `NOSOURCE` keyword. 56 64 57 65 … … 59 67 -------------- 60 68 61 difference between format and markup, `FORMAT_STYLE` and `MARKUP_STYLE` keywords; format styles = idldoc (the default), rst, idl, verbatim; markup styles = verbatim (the default, unless rst format style), rst (default for rst format style), preformatted69 TODO: difference between format and markup, `FORMAT_STYLE` and `MARKUP_STYLE` keywords; format styles = idldoc (the default), rst, idl, verbatim; markup styles = verbatim (the default, unless rst format style), rst (default for rst format style), preformatted 62 70 63 "rst" is the modern supported style for both format and markup in current versions of IDLdoc (although not the default); legacy format/markup is described in the reference manual.71 TODO: "rst" is the modern supported style for both format and markup in current versions of IDLdoc (although not the default); legacy format/markup is described in the reference manual. 64 72 65 73 … … 67 75 ~~~~~~~~~~~~~~~~~ 68 76 69 file vs routine comments77 TODO: file vs routine comments 70 78 71 common file tags: `Examples`, `Author`, `Copyright`, `History`79 TODO: common file tags: `Examples`, `Author`, `Copyright`, `History` 72 80 73 common routine tags: `Returns`, `Params`, `Keywords`, `Examples`, `Uses`, `Requires`, `Author`, `Copyright`, `History`81 TODO: common routine tags: `Returns`, `Params`, `Keywords`, `Examples`, `Uses`, `Requires`, `Author`, `Copyright`, `History` 74 82 75 83 Source code files documented in different styles can be placed in the same directory hierarchy. The default IDLdoc styles, or those provided by the `FORMAT_STYLE` and `MARKUP_STYLE` keywords, can be overridden for a single file by placing a special comment on the first line of the file:: … … 129 137 TODO: The comment markup style defines how text can be annotated. Once the format style has defined a place for "put comments here" for a particular item, the markup style describes the syntax of those comments. 130 138 131 links and inline code, rules for named links?139 TODO: links and inline code, rules for named links? 132 140 133 preformatted code blocks141 TODO: preformatted code blocks 134 142 135 image directive::143 TODO: image directive:: 136 144 137 145 .. image:: filename.png … … 139 147 File formats? 140 148 141 embed directive::149 TODO: embed directive:: 142 150 143 151 .. embed:: filename … … 145 153 File formats? 146 154 147 title of an `.idldoc` file, title directive::155 TODO: title of an `.idldoc` file, title directive:: 148 156 149 157 .. title:: This is the title of the file … … 151 159 Appears in navigation links on the left/title of the page 152 160 153 headers, =, -, or ~ anywhere, but most useful in `.idldoc` files161 TODO: headers, =, -, or ~ anywhere, but most useful in `.idldoc` files 154 162 155 163 … … 157 165 -------------- 158 166 159 user vs. developer documentation, `USER` keyword, private/hidden tags (and attributes)167 TODO: user vs. developer documentation, `USER` keyword, private/hidden tags (and attributes) 160 168 161 T he `FOOTER` keyword can specify a file to include at the bottom of each page of output.169 TODO: The `FOOTER` keyword can specify a file to include at the bottom of each page of output. 162 170 163 When producing HTML documentation, there are often two cases that need to be handled:171 TODO: When producing HTML documentation, there are often two cases that need to be handled: 164 172 165 173 #. documentation served on a web site and intended to be served as a full collection … … 168 176 In the later case, it is often useful to set the `EMBED` and `NONAVBAR` keywords. The `EMBED` keyword embeds the, rather large, CSS file into each HTML page. This is inefficient for a full documentation set on a web site because in that situation, each page can just refer to a common `.css` file. The `NONAVBAR` keyword simply omits the navigation bar at the top of the page which is not needed when only one HTML page is given but useful to navigate a full documentation set. 169 177 170 index_level=1178 TODO: index_level=1 171 179 172 source code options180 TODO: source code options 173 181 174 /statistics and cutoffs 182 TODO: If the `STATISTICS` keywords is set, IDLdoc will compute certain measures of the code's complexity like the number of lines in a routine or the cyclomatic complexity. `COMPLEXITY_CUTOFFS`, `ROUTINE_LINE_CUTOFFS` 175 183 176 184 … … 178 186 ---------- 179 187 180 T he `project site <http://idldoc.idldev.com>`_ for IDLdoc contains more information about IDLdoc including the ticket system where bugs can be reported and new features requested. The mailing list, downloads of all versions along with their release notes, etc.188 TODO: The `project site <http://idldoc.idldev.com>`_ for IDLdoc contains more information about IDLdoc including the ticket system where bugs can be reported and new features requested. The mailing list, downloads of all versions along with their release notes, etc.
