eric6-doc is the documentation generator of the eric6 IDE. Python source code documentation may be included as ordinary Python doc-strings or as documentation comments. For Quixote Template files (PTL) only documentation comments are available due to the inner workings of Quixote. Documentation comments start with the string ###, followed by the contents and ended by ###. Every line of the documentation comments contents must start with a # (see example below).
For Ruby files, the documentation string must be started with "=begin edoc" and must be ended with "=end". The documentation string for classes, modules and functions/methods must follow their defininition.
Documentation for packages (i.e. directories) must be in a file called __init__.py or __init__.rb. If a package directory doesn't contain a file like these, documentation for files in this directory is suppressed.
The documentation consist of two parts. The first part is the description of the module, class, function or method. The second part, separated from the first by a blank line, consists of one or more tags. These are described below.
eric6-doc produces HTML files from the documentation found within the source files scaned. It understands the following commandline parameters next to others.
- -o directory
Generate files in the named directory.
- -R, -r
Perform a recursive search for Python files.
- -x directory
Specify a directory basename to be excluded. This option may be repeated multiple times.
- -i
Don't generate index files.
Just type "eric6-doc" to get some usage information.
The descriptions are HTML fragments and may contain most standard HTML. The description text is included in the output wrapped in P tags, but unchanged otherwise. Paragraphs have to be separated by a blank line. In order to generate a blank line in the output enter a line that contains a single dot (.). Reserved HTML entities (<, > and &) and the at-sign (@) at the beginning of a line, if that line doesn't contain a tag (see below), must be properly escaped. "<" should be written as "<", ">" as ">", "&" as "&" and "@" should be escaped as "@@".
The documentation string or documentation comment may contain block tags and inline tags. Inline tags are denoted by curly braces and can be placed anywhere in the main description or in the description part of block tags. Block tags can only be placed in the tag section that follows the main description. Block tags are indicated by an at-sign (@) at the beginning of the line. The text before the first tag is the description of a module, class, method or function.
Python Docstring:
"""
This is sentence one, which gets included as a short description.
All additional sentences are included into the full description.
@param param1 first parameter
@exception ValueError list entry wasn't found
@return flag indicating success
"""Python/Quixote Documentation comment:
###
# This is line one, which gets included as a short description.
# All additional lines are included into the full description.
#
# @param param1 first parameter
# @exception ValueError list entry wasn't found
# @return flag indicating success
###Ruby Docstring:
=begin edoc
This is line one, which gets included as a short description.
All additional lines are included into the full description.
@param param1 first parameter
@exception ValueError list entry wasn't found
@return flag indicating success
=endThe block tags recogized by eric6-doc are:
@@
This isn't really a tag. This is used to escape an at sign at the beginning of a line. Everything after the first @ is copied verbatim to the output.
@author author
This tag is used to name the author of the code. For example:
@author Detlev Offenbach <detlev@die-offenbachs.de>
@deprecated description
This tag is used to mark a function or method as deprecated. It is always followed by one or more lines of descriptive text.
@event eventname description
This tag is used to describe the events (PyQt) a class may emit. It is always followed by the event name and one or more lines of descriptive text. For example:
@event closeEvent Emitted when an editor window is closed.
@exception exception description
These tags are used to describe the exceptions a function or method may raise. It is always followed by the exception name and one or more lines of descriptive text. For example:
@exception ValueError The searched value is not contained in the list.
@ireturn description
This tag is an alias for the @return tag.
@keyparam name description
This tag is like the @param tag, but should be used for parameters, that should always be given as keyword parameters. It is always followed by the argument name and one or more lines of descriptive text. For example:
@keyparam extension Optional extension of the source file.
@param name description
This tag is used to describe a function or method argument. It is always followed by the argument name and one or more lines of descriptive text. For example:
@param filename name of the source file
@ptype name parameter-type
This tag is used to describe the type of a function or method argument. It is always followed by the argument name and type. The argument has to be defined already with @param or @keyparam. For example:
@ptype filename str
@raise exception description
This tag is an alias for the @exception tag.
@return description
This tag is used to describe a function or method return value. It can include one or more lines of descriptive text. For example:
@return list of file names
@rtype type
This tag is used to describe a function or method return type. It should follow an @return tag. For example:
@rtype list of str
@see reference
This tag is used to include a reference in the documentation. It comes in three different forms.
@see "string"
Adds a text entry of string. No link is generated. eric6-doc distinguishes this form from the others by looking for a double-quote (") as the first character. For example:
@see "eric6-doc readme file"
@see <a href="URL#value">label</a>
Adds a link as defined by URL#value. eric6-doc distinguishes this form from the others by looking for a less-than symbol (<) as the first character. For example:
@see <a href="eric6.eric6-doc.html>eric6-doc documentation generator</a>@see package.module#member label
Adds a link to "member" in "module" in "package". package can be a package path, where the package names are separated by a dot character (.). The "package.module#member" part must not be split over several lines and must name a valid target within the documentation directory. For example:
@see eric6.eric6-doc#main eric6-doc main() function @see eric6.DocumentationTools.ModuleDocumentor#ModuleDocument.__genModuleSection ModuleDocument.__genModuleSection
@signal signalname description
This tag is used to describe the signals (PyQt) a class may emit. It is always followed by the signal name and one or more lines of descriptive text. For example:
@signal lastEditorClosed Emitted after the last editor window was closed.
@throws exception description
This tag is an alias for the @exception tag.
@type parameter-type
This tag is used to give the type of the parameter just described. It must be preceded by a @param or @keyparam tag. For example:
@param filename name of the source file @type str
The inline tags recogized by eric6-doc are:
{@link package.module#member label}
Inserts an in-line link with visible text label that points to the documentation given in the reference. This tag works he same way as the @see block tag of this form.