1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
|
HappyDoc Change History
Version 2.1 --
The primary reason for this release is to resolve the infamous *-d
bug*.
- **New Features**
- #514237 - The PluginLoader no longer requires a '.py'
extension on plugins. This should allow plugins to be written
in any language for which Python can load a module, and as
long as the file is named with the right convention they will
be picked up and loaded. (The source of this change request
was the maintainers of the PLD Linux Distribution.)
- **Bug Fixes**
- Resolved defect #513850, where output was written to the wrong
place when the -d option was used.
**NOTE** *The solution to this problem resulted in changes to
the file names being used for output. It is recommended that
a new directory be used to generate documentation for existing
code, rather than trying to write over the top of existing
files.*
- Resolved defect #510447, a problem with escaping special
characters in HTML output. Text enclosed in single quotes
is now not escaped in output so that HTML text can be
passed directly to the output file.
- Fixed a problem with Windows installation using 'setup.py'.
- **Other Changes**
- Minor tweaks to the build and test tools.
Version 2.0.1 --
- **New Features**
- Added limited support for CGI programs by expanding the docset
processing to look for files ending in '.cgi' as well as
'.py'.
- **Bug Fixes**
- Resolved defect #505456 and 498204, a problem with
'happydocwin.py' that prevented it from working properly on
Win32 systems.
- Resolved defect #501240 so that path handling under Win32
systems works properly and HappyDoc can generate output.
- Resolved defect #505188 so that using the '-o' option will
properly send output to stdout.
- **Other Changes**
- Added more unit tests for formatters, especially
'fileformatterbase.py' and 'formatter_HTMLFile.py'.
- Updated the StructuredTextNG docstring converter so that if an
exception is generated during parsing of the ST, we fall back
to ClassicStructuredText. The two syntaxes appear to be
incompatible, and this should protect backwards compatibility
for most users.
Version 2.0 --
- **New Features**
- Rearranged much of the code base to create 'happydoclib'
package. This package protects the namespace for HappyDoc
related code, and makes it easier to reuse HappyDoc components
in other projects.
- Package descriptions can now come from the docstring of the
'__init__.py' module, instead of always having to be in a README
file.
- **Bug Fixes**
- Resolved bug #478659 so that import statements with comments
following on the same line are picked up.
- Fixed a problem with the HTMLTable formatter that caused pages
to look odd in browsers which don't handle width attributes the
same way as Netscape.
- Upgraded to newer version of StructuredText package from Zope
CVS, resolving several rendering issues for the HTML formatter.
- **Other Changes**
- Changed command line argument handling to use '-' character in
names in addtition to underscore. That is, defining an
optionHandler_long_opt will allow the app to accept '--long-opt'
or '--long_opt'. The help text uses the '-' form, but both
are allowed on the command line for backwards compatability.
- Updated test cases to streamline regression testing.
- Rearranged some of the documentation from the root
'README.txt' into sub-packages.
Version 1.6 --
- **New Features**
- Implemented a variety of modifications to support Python 2.0
syntax updates.
- Implemented plug-in system for docstring converters to allow
module authors to write documentation using different markup
styles. External files are recognized by their extension.
The global default setting for docstrings can be passed on
the command line, or a file-specific setting can be embedded
in the input file (see below).
- Updated the default markup syntax to StructuredTextNG,
replacing the original StructuredText. Most users will not
notice any difference.
If the old StructuredText rules are desired, add a line to the
first comment block in the module with these contents::
# HappyDoc:docStringFormat="ClassicStructuredText"
- Added parser argument handling to match that of docsets and
formatters.
- Implemented a system to allow file-specific parser control
variables to be embedded in the input source files.
- Made the parser function an attribute of HappyDoc application
instance ('parser_function') so subclasses can override it.
- **Many contributed patches**
- Patch #403039 from Rob W.W. Hooft (hooft) to allow better
support for Python 2.x 'import' statement syntax changes.
- Patch #403790 from an unknown contributor to allow the base
URL for documentation of Python standard libraries to be
passed as a command line argument to HappyDoc.
- Patch #413416 from Rob W.W. Hooft (hooft) to eliminate invalid
links to private classes which are not described.
- Patch #445846 from Jrg Henrichs (jhenrichs) to elminate
"decoration" lines in comment documentation. Now comment
lines consisting solely of the characters '#', '-', and '='
(possibly combined with whitespace) are ignored when
extracting documentation from comments in a source file.
- Added output formatter and docset for creating UML diagrams in
Dia format. Thanks to Jrg Henrichs (jhenrichs) for the patches!
- **Several resolved bugs**
- Resolved defect #434946 so that files with DOS line endings
are handled properly.
- Resolved defect #442811, reported by Jason R. Mastaler
(jasonrm), in which the use of the old 'regex' module by the
StructuredText parser generated deprecation warnings.
- Resolved defect #429308 from an unknown user in which less
than and greater than symbols in preformatted (example)
sections of text were rendered incorrectly.
- **Other Changes**
- Cosmetic changes to the way unit tests are run.
- Fixed a problem with identifying "system modules" under
versions of Python other than 1.5.
- Sort the table of contents by the module name, not the file
name. These can be different, and sorting this way mixes
packages and modules together so that it is easier to find
the desired documentation.
Version 1.5 --
- Changed handling of parser.ParserError exceptions so they are
converted to SyntaxErrors. This allows HappyDoc to show the
file and line which caused the problem. Files with parse
errors will be skipped with an error message.
- Made a few Windows-related changes to the README file.
- Corrected defect 428844 so that documentation in comments is
associated with the appropriate object. The symptom of the
corrected defect was if a single module had 2 classes with
methods of the same name, and both were documented using
comments, HappyDoc associated the last comment found with both
methods.
Version 1.4.1 --
- If no input files are specified, a help message and error
message are displayed.
- Added happydocwin.py as a command line script for Windows.
- Added formatter option to allow user to override the Python
libdoc directory.
- Changed attribution note at bottom of HTML pages to be in a
smaller font.
Version 1.4 --
- Handle Packages separately from Modules. This behavior is
optional and consists mostly of creating intermediate level
TOC pages and not showing subdirectories of a Package on the
Package's parent TOC page.
- Changed default title to include instructions about how to
change the title
- Show exceptions in plugins when there is a problem loading a
module
- Added a command line argument to support ignoring specific
subdirectories.
- Fixed problem with ignoring directories by correcting name
comparison logic.
- Change "link":URL style references which were HTML
quoted back to StructuredText so that hyperlinks can be embedded
within docstrings. (reported by Mihalopoulos Evangelos,
mihalop@yahoo.com)
- Changed base class arrangement for docset so the basic interface
is documented as part of the docset base class.
- Moved some formatter functions into the docset, since they match
that API better and more properly belong there.
- Fixed bug 131751, problem with string dereference in parseinfo.py
- Set the DOCTYPE in hdformatter_htmlfile.py. (Thanks to
Shannon -jj Behrens, jjinux@yahoo.com for the patch.)
- Fixed problem with references to extra files when using output
prefixes.
- Changed test harness to use the HappyDoc class directly instead
of calling out to a separate program.
- Output a oneliner for referenced pre-formatted documents.
- Modified parseinfo.py to improve speed
- Expanded information extracted about exceptions thrown by
functions
- Simplified the regressino test to make it faster by removing
Zope docs from the default regression test suite
Version 1.3 --
- Fixed problem with relative URL references in HTML output.
Version 1.2 --
- ( packaging errors )
Version 1.1 --
- Enhanced boolean command line switch handling to support
values like 'yes', 'no', 'on', 'off', 'true', and 'false'.
- Added an initial DocBook formatter implementation from Balazs
Scheidler (bazsi@balabit.hu).
Version 1.0 --
- This version was not actually released.
- Per-directory README.txt detection. (Useful for Zope
products and Python packages.)
- Support LICENSE.txt, CHANGES.txt, ANNOUNCE.txt and other
StructuredText files referenced from README.txt. Support
external files which do not have .txt extension.
- Now installs using distutils.
- Include code related to Patch 103054 to fix problems with
tables in HTML and to make the HTML output smaller by reducing
extra whitespace.
- Cleaned up some progress reporting output.
- Added option to docset to set a prefix to every file or
directory created as output. This is important for creating
output with safe names in case module names end up being
parsed to something which does not make a valid filename. It
can also be useful when storing output in a web application
server such as Zope, where some names might be reserved.
- Added docset and formatter parameter info to the output.
- Formatter option to disable html quoting of docstring text.
Version 0.9.3 --
- Fixed the single file docset so that HTML and text mode works.
Version 0.9.2 --
- Fixed a problem with the 'import' statement handler. Also
changed HTML formatter output for 'import' statements to include
keywords in bold.
Version 0.9.1 --
- Minor packaging changes.
Version 0.9 --
- **Patch 101758** - (From mikem42) Added a new command line
argument '--no_comments' to tell the parser to ignore comments
when looking for documentation text.
- **Patch 103017** - (From hooft) Fixed '--no_private_names'
so that names beginning with two '_' are displayed even when
private names are not.
- **Bug126855** - (From hooft) Improvements to expression
handling for argument defaults.
- **Bug126187** - (From hooft) Fixed up the way import
statements are handled so that information is not lost.
- **Bug114517** - Corrected a problem with extracting the one
line summary of some docstrings.
- Renamed the 'formatter' directory and contents to avoid
clashing with the standard Python module formatter.py.
- Now supports installation via distutils.
Version 0.8 --
- **Patch 101602** - Closing class output files in multi-file
docsets. This should remove the "too many open files" errors
that several users reported on some platforms.
- Passing "'-'" to the '-p' option now disables the package
description file handling.
- Updated the location of the source documentation files on
Zope.org.
- **Bug115451** fixed so that only the correct comments are
output.
- Added new option --no_private_names which hides names
beginning with '_', thus resolving feature request 114877.
- **Bug114872** fixed so that using 'raise' with no arguments
is ignored.
Version 0.7.1 --
- **Fix 113738** - Keeping up with all of the open file handles in
order to know the relative path to the "first" root file
causes some systems to run out of open file handles. This
change fixes the problem by only remembering the first file
opened.
Version 0.7 --
- **Fix** formatter or docset getting unrecognized named parameters.
- **Fix** change detection with regression tests.
- Moved the test code into a special subdirectory to clean up the
root area of the app.
- **Fix** 'mkdir()' method of 'HappyDoc' to support win32
systems. The fix is based on a patch submitted by Jesper
Hertel (JH@CDDK.DK).
- **Fix** Bug Reported by Jesper Hertel: Default arguments of
negative numbers break.
For example::
def func(x=-1):
pass
- **Fix 113954** HTML encode function parameter values (and all
'writeCode' content for HTML formatter).
- Changed exception list in HTML formatter so that it is output
as code.
- Added some new methods to the text formatter to support
changes in how the exception list is now written.
Version 0.6 -- First public release
- Added regression test checks to Makefile. This makes it easy to
run a complete regression test and verify that the results are
correct.
- Added checking of actual output files, not just stdout, to
regression test rules in Makefile.
- Changed HTMLTable formatter so that it accepts an argument to
disable the timestamp feature. This is mostly useful for the
regression testing, but might also be desirable for some output
circumstances. The default is to leave the feature enabled.
- Changed test framework to allow an output directory to be
specified on the command line.
- Changed test framework to make creation of tests easier to
scale.
- Verified support passing arguments to formatters from the
command line.
Version 0.5 -- Moved code to SourceForge.
- Minor changes to functionality
- Rearranged Makefile and some other files to make them
SourceForge-friendly.
Version 0.4 -- Import, testing, and formatter changes.
- Handles imported names in the 'from X import Y' style import
statements. Makes them links where possible.
- Improved unit test framework (requires
"PyUnit":http://pyunit.sourceforge.net ).
- Fixed some problems with the formatter_textfile.py module which
caused it to generate spurrious content.
Version 0.3 -- Allow lists to have multiple columns.
Version 0.2.1 -- Fixed a problem with references between modules and
back to the root level toc file in the HTML Table formatter. Also
changed happydoc.py to use the CVS variable 'Name' to determine its
version.
Version 0.2 -- Created dynamic plugin loader class to manage docset
and formatter pluggins. See pluginloader.py.
Version 0.1.1 -- Minor improvements on 0.1, mostly in the
'htmltable' formatter.
Version 0.1 -- Initial private release given to a few people to beta
test.
|
