--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/README-eric7-doc.md Mon Jul 03 16:31:29 2023 +0200
@@ -0,0 +1,203 @@
+# README for the eric7-doc documentation generator
+
+eric7-doc is the documentation generator of the eric7 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).
+
+Documentation for packages (i.e. directories) must be in a file called
+`__init__.py`. 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.
+
+eric7-doc produces HTML files from the documentation found within the source
+files scanned. It understands the following command line 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 `eric7-doc` to get some usage information.
+
+# 1. 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
+ @type int
+ @return flag indicating success
+ @rtype bool
+ @exception ValueError list entry wasn't found
+ """
+
+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
+ # @type int
+ # @return flag indicating success
+ # @rtype bool
+ # @exception ValueError list entry wasn't found
+ ###
+
+# 2. Block Tags
+The block tags recognized by eric7-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. eric7-doc
+ distinguishes this form from the others by looking for a double-quote
+ (") as the first character. For example:
+
+ @see "eric7-doc readme file"
+
+: @see <a href="URL#value">label</a>
+ : Adds a link as defined by URL#value. eric7-doc distinguishes this form
+ from the others by looking for a less-than symbol (<) as the first
+ character. For example:
+
+ @see <a href="eric7.eric7-doc.html>eric7-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 eric7.eric7-doc#main eric7-doc main() function
+ see eric7.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
+
+# 3. Inline Tags
+The inline tags recogized by eric7-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.
