Mercurial Repositories > eric / file comparison
comparison: docs/README-eric6-doc.rst
docs/README-eric6-doc.rst
- changeset 6942
- 2602857055c5
- parent 4267
- 94496d77156b
equal
deleted
inserted
replaced
| 6941:f99d60d6b59b | 6942:2602857055c5 |
|---|---|
| 1 ================================================ | |
| 2 README for the eric6-doc documentation generator | |
| 3 ================================================ | |
| 4 | |
| 5 eric6-doc is the documentation generator of the eric6 IDE. Python source | |
| 6 code documentation may be included as ordinary Python doc-strings or as | |
| 7 documentation comments. For Quixote Template files (PTL) only documentation | |
| 8 comments are available due to the inner workings of Quixote. Documentation | |
| 9 comments start with the string ###, followed by the contents and ended by | |
| 10 ###. Every line of the documentation comments contents must start with a # | |
| 11 (see example below). | |
| 12 | |
| 13 For Ruby files, the documentation string must be started with "=begin edoc" | |
| 14 and must be ended with "=end". The documentation string for classes, modules | |
| 15 and functions/methods must follow their defininition. | |
| 16 | |
| 17 Documentation for packages (i.e. directories) must be in a file called | |
| 18 __init__.py or __init__.rb. If a package directory doesn't contain a file | |
| 19 like these, documentation for files in this directory is suppressed. | |
| 20 | |
| 21 The documentation consist of two parts. The first part is the description of | |
| 22 the module, class, function or method. The second part, separated from the | |
| 23 first by a blank line, consists of one or more tags. These are described below. | |
| 24 | |
| 25 eric6-doc produces HTML files from the documentation found within the source | |
| 26 files scaned. It understands the following commandline parameters next to | |
| 27 others. | |
| 28 | |
| 29 -o directory | |
| 30 Generate files in the named directory. | |
| 31 | |
| 32 -R, -r | |
| 33 Perform a recursive search for Python files. | |
| 34 | |
| 35 -x directory | |
| 36 Specify a directory basename to be excluded. This option may be repeated | |
| 37 multiple times. | |
| 38 | |
| 39 -i | |
| 40 Don't generate index files. | |
| 41 | |
| 42 Just type "eric6-doc" to get some usage information. | |
| 43 | |
| 44 1. Description | |
| 45 -------------- | |
| 46 The descriptions are HTML fragments and may contain most standard HTML. The | |
| 47 description text is included in the output wrapped in P tags, but unchanged | |
| 48 otherwise. Paragraphs have to be separated by a blank line. In order to | |
| 49 generate a blank line in the output enter a line that contains a single dot | |
| 50 (.). Reserved HTML entities (<, > and &) and the at-sign (@) at the beginning | |
| 51 of a line, if that line doesn't contain a tag (see below), must be properly | |
| 52 escaped. "<" should be written as "<", ">" as ">", "&" as "&" and | |
| 53 "@" should be escaped as "@@". | |
| 54 | |
| 55 The documentation string or documentation comment may contain block tags | |
| 56 and inline tags. Inline tags are denoted by curly braces and can be placed | |
| 57 anywhere in the main description or in the description part of block tags. | |
| 58 Block tags can only be placed in the tag section that follows the main | |
| 59 description. Block tags are indicated by an at-sign (@) at the beginning of | |
| 60 the line. The text before the first tag is the description of a module, class, | |
| 61 method or function. | |
| 62 | |
| 63 Python Docstring:: | |
| 64 | |
| 65 """ | |
| 66 This is sentence one, which gets included as a short description. | |
| 67 All additional sentences are included into the full description. | |
| 68 | |
| 69 @param param1 first parameter | |
| 70 @exception ValueError list entry wasn't found | |
| 71 @return flag indicating success | |
| 72 """ | |
| 73 | |
| 74 Python/Quixote Documentation comment:: | |
| 75 | |
| 76 ### | |
| 77 # This is line one, which gets included as a short description. | |
| 78 # All additional lines are included into the full description. | |
| 79 # | |
| 80 # @param param1 first parameter | |
| 81 # @exception ValueError list entry wasn't found | |
| 82 # @return flag indicating success | |
| 83 ### | |
| 84 | |
| 85 Ruby Docstring:: | |
| 86 | |
| 87 =begin edoc | |
| 88 This is line one, which gets included as a short description. | |
| 89 All additional lines are included into the full description. | |
| 90 | |
| 91 @param param1 first parameter | |
| 92 @exception ValueError list entry wasn't found | |
| 93 @return flag indicating success | |
| 94 =end | |
| 95 | |
| 96 2. Block Tags | |
| 97 ------------- | |
| 98 The block tags recogized by eric6-doc are: | |
| 99 | |
| 100 @@ | |
| 101 | |
| 102 This isn't really a tag. This is used to escape an at sign at the beginning | |
| 103 of a line. Everything after the first @ is copied verbatim to the output. | |
| 104 | |
| 105 @author author | |
| 106 | |
| 107 This tag is used to name the author of the code. For example:: | |
| 108 | |
| 109 @author Detlev Offenbach <detlev@die-offenbachs.de> | |
| 110 | |
| 111 @deprecated description | |
| 112 | |
| 113 This tag is used to mark a function or method as deprecated. It is always | |
| 114 followed by one or more lines of descriptive text. | |
| 115 | |
| 116 @event eventname description | |
| 117 | |
| 118 This tag is used to describe the events (PyQt) a class may emit. It is | |
| 119 always followed by the event name and one or more lines of descriptive | |
| 120 text. For example:: | |
| 121 | |
| 122 @event closeEvent Emitted when an editor window is closed. | |
| 123 | |
| 124 @exception exception description | |
| 125 | |
| 126 These tags are used to describe the exceptions a function or method may | |
| 127 raise. It is always followed by the exception name and one or more lines | |
| 128 of descriptive text. For example:: | |
| 129 | |
| 130 @exception ValueError The searched value is not contained in the list. | |
| 131 | |
| 132 @ireturn description | |
| 133 | |
| 134 This tag is an alias for the @return tag. | |
| 135 | |
| 136 @keyparam name description | |
| 137 | |
| 138 This tag is like the @param tag, but should be used for parameters, that | |
| 139 should always be given as keyword parameters. It is always followed by | |
| 140 the argument name and one or more lines of descriptive text. For example:: | |
| 141 | |
| 142 @keyparam extension Optional extension of the source file. | |
| 143 | |
| 144 @param name description | |
| 145 | |
| 146 This tag is used to describe a function or method argument. It is always | |
| 147 followed by the argument name and one or more lines of descriptive text. | |
| 148 For example:: | |
| 149 | |
| 150 @param filename name of the source file | |
| 151 | |
| 152 @ptype name parameter-type | |
| 153 | |
| 154 This tag is used to describe the type of a function or method argument. | |
| 155 It is always followed by the argument name and type. The argument has | |
| 156 to be defined already with @param or @keyparam. For example:: | |
| 157 | |
| 158 @ptype filename str | |
| 159 | |
| 160 @raise exception description | |
| 161 | |
| 162 This tag is an alias for the @exception tag. | |
| 163 | |
| 164 @return description | |
| 165 | |
| 166 This tag is used to describe a function or method return value. It can | |
| 167 include one or more lines of descriptive text. For example:: | |
| 168 | |
| 169 @return list of file names | |
| 170 | |
| 171 @rtype type | |
| 172 | |
| 173 This tag is used to describe a function or method return type. It should | |
| 174 follow an @return tag. For | |
| 175 example:: | |
| 176 | |
| 177 @rtype list of str | |
| 178 | |
| 179 @see reference | |
| 180 | |
| 181 This tag is used to include a reference in the documentation. It comes in | |
| 182 three different forms. | |
| 183 | |
| 184 @see "string" | |
| 185 | |
| 186 Adds a text entry of string. No link is generated. eric6-doc | |
| 187 distinguishes this form from the others by looking for a double-quote | |
| 188 (") as the first character. For example: | |
| 189 | |
| 190 @see "eric6-doc readme file" | |
| 191 | |
| 192 @see <a href="URL#value">label</a> | |
| 193 | |
| 194 Adds a link as defined by URL#value. eric6-doc distinguishes this form | |
| 195 from the others by looking for a less-than symbol (<) as the first | |
| 196 character. For example:: | |
| 197 | |
| 198 @see <a href="eric6.eric6-doc.html>eric6-doc documentation generator</a> | |
| 199 | |
| 200 @see package.module#member label | |
| 201 | |
| 202 Adds a link to "member" in "module" in "package". package can be a | |
| 203 package path, where the package names are separated by a dot character | |
| 204 (.). The "package.module#member" part must not be split over several | |
| 205 lines and must name a valid target within the documentation directory. | |
| 206 For example:: | |
| 207 | |
| 208 @see eric6.eric6-doc#main eric6-doc main() function | |
| 209 @see eric6.DocumentationTools.ModuleDocumentor#ModuleDocument.__genModuleSection ModuleDocument.__genModuleSection | |
| 210 | |
| 211 @signal signalname description | |
| 212 | |
| 213 This tag is used to describe the signals (PyQt) a class may emit. It is | |
| 214 always followed by the signal name and one or more lines of descriptive | |
| 215 text. For example:: | |
| 216 | |
| 217 @signal lastEditorClosed Emitted after the last editor window was closed. | |
| 218 | |
| 219 @throws exception description | |
| 220 | |
| 221 This tag is an alias for the @exception tag. | |
| 222 | |
| 223 @type parameter-type | |
| 224 | |
| 225 This tag is used to give the type of the parameter just described. | |
| 226 It must be preceded by a @param or @keyparam tag. For example:: | |
| 227 | |
| 228 @param filename name of the source file | |
| 229 @type str | |
| 230 | |
| 231 3. Inline Tags | |
| 232 -------------- | |
| 233 The inline tags recogized by eric6-doc are: | |
| 234 | |
| 235 {@link package.module#member label} | |
| 236 | |
| 237 Inserts an in-line link with visible text label that points to the documentation | |
| 238 given in the reference. This tag works he same way as the @see block tag of this | |
| 239 form. |
