--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/README-eric6-doc.txt Sat Aug 09 18:16:12 2014 +0200
@@ -0,0 +1,189 @@
+README for the eric6-doc documentation generator
+
+ 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.
+
+ Description
+ -----------
+ 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
+ =end
+
+ Block Tags
+ ----------
+ The 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.
+
+ @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.
+
+ @raise exception description
+ This tag is an alias for the @exception tag.
+
+ @return description
+ This tag is used to describe a functions or methods return value. It can
+ include one or more lines of descriptive text. For example:
+
+ @return list of description strings
+
+ @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.
+
+ Inline Tags
+ -----------
+ 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.
