docs/README-eric6-doc.rst

Fri, 19 Apr 2019 17:48:40 +0200

author
Detlev Offenbach <detlev@die-offenbachs.de>
date
Fri, 19 Apr 2019 17:48:40 +0200
changeset 6956
dfd3b53be436
parent 6942
2602857055c5
permissions
-rw-r--r--

install: change minimum version of QScintilla to 2.9.0.

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

eric ide

mercurial