epydoc-devel — Discussions about epydoc development

Re: [Epydoc-devel] Docstring parsing shortcomings

[Hans M. <me...@in...>]

Hi!

(Resending, first try went to Edward only.)

> On May 10, 2007, at 2:57 PM, Daniele Varrazzo wrote:
> > Edward, what is the rationale behind the "selfparam" in the function
> > signature parsing? It seems to me that dropping it would produce
> > better results in most cases (even for a bound method expressed whose
> > signature in the docstring is expressed as
> >
> >    inst.func(a, b)
> >
> > reporting "func(a, b)" seems kinda more correct than "func(inst, a,
> > b)", even if the self argument is missing)

Let me repeat myself here: There is a use for having the name in the docs, 
namely that you can *reference* the name in the docs.  I.e. 

"""myFoo.append(obj)

This method appends obj to the end of myFoo."""

is slightly clearer than 

"""append(obj)

This method appends obj to the end of this Foo object."""

Actually, this looks like a weak argument since I chose such a simple example, 
wait a moment... look at this:

            """someFace.holeCount() -> int
            
            Returns the number of holes.  This is equal to
            len(list(someFace.holeContours())), but faster."""

OK, I could rephrase it as 

            """Returns the number of holes.  someFace.holeCount() is equal to
            len(list(someFace.holeContours())), but faster."""

if you don't want to introduce the "objName." prefix in the epydoc output, 
which I could understand because it could look a little bit inconsistent 
(however, I would only expect that in the detailed docs anyways).

> I took the lead here from the python builtins:
>      >>> print list.append.__doc__
>
>      L.append(object) -- append object to end
>
> It made most sense to me to render the docs for this as "append(L,
> object)" to be consistent with how non-builtin object methods are
> represented.

I was about to write that I don't understand this, but now that I wrote the 
above, I can understand you.  (This does not have anything to do with builtin 
vs. non-builtin though, does it?)

> I'm not strongly attached to the decision, though, if 
> there's support for changing this.  But I'd like the generated docs
> for the builtin objects to still make sense.

As I said, I would prefer simply having the "L.append(object)" signature in 
the detailed HTML (not the class overview).  list.append.__doc__ is a bad 
example though, since it does not even reference 'L' in the rest of the 
docstring; I would expect sth. along
  "L.append(object) -- append object to L's end"

> >> d) It would be great it epydoc could extract signatures for
> >> boost::python
> >> exported functions, too [...]
> >
> > I don't know much about boost::python bindings. Shooting random
> > parameters
> > to an unknown signature doesn't seem fair to me :)

Same here.. ;-)

> Perhaps boost and/or sip could be encouraged to include some
> introspectable value that can be used to find the signature?  Either
> by automatically including a signature at the beginning of the
> __doc__ attribute, or by adding a new attribute to the object?  If
> they did that, I'd be happy to add support to epydoc for reading it.

Actually, I remember having read that the upcoming boost 1.34.0 has such a 
feature, that is why I asked a student to try that out, but he told me that 
it hadn't.  Still, a quick search brings up this:
   http://lists.boost.org/Archives/boost/2007/04/120397.php
..which tells us that "Boost.Python now automatically appends C++ signatures 
to docstrings.".  (Note that "C++ signatures" include full C++ type specs 
before the argument names, and may not even contain the names if they were 
not specified..)

I will try that out myself now and report back.

-- 
Ciao, /  /
     /--/
    /  / ANS

Re: [Epydoc-devel] Docstring parsing shortcomings

[Edward L. <ed...@gr...>]

On May 10, 2007, at 2:57 PM, Daniele Varrazzo wrote:
> Edward, what is the rationale behind the "selfparam" in the function
> signature parsing? It seems to me that dropping it would produce  
> better
> results in most cases (even for a bound method expressed whose  
> signature in
> the docstring is expressed as
>
>    inst.func(a, b)
>
> reporting "func(a, b)" seems kinda more correct than "func(inst, a,  
> b)",
> even if the self argument is missing)

I took the lead here from the python builtins:

     >>> print list.append.__doc__
     L.append(object) -- append object to end

It made most sense to me to render the docs for this as "append(L,  
object)" to be consistent with how non-builtin object methods are  
represented.  I'm not strongly attached to the decision, though, if  
there's support for changing this.  But I'd like the generated docs  
for the builtin objects to still make sense.

>> d) It would be great it epydoc could extract signatures for  
>> boost::python
>> exported functions, too [...]
>
> I don't know much about boost::python bindings. Shooting random  
> parameters
> to an unknown signature doesn't seem fair to me :) sip generated  
> bindings
> share a similar characteristic (actually sip doesn't generate any  
> docstring
> at all, i don't know about boost). If you point me at an OS project  
> built
> with boost i may play a bit with such functions.

Perhaps boost and/or sip could be encouraged to include some  
introspectable value that can be used to find the signature?  Either  
by automatically including a signature at the beginning of the  
__doc__ attribute, or by adding a new attribute to the object?  If  
they did that, I'd be happy to add support to epydoc for reading it.

-Edward

Re: [Epydoc-devel] Docstring parsing shortcomings

[Daniele V. <pi...@de...>]

Hello Hans,

> Today, I tried epydoc (3.0beta1) on one of my projects, and found several
> things that I miss / find strange:
>
> a) When parsing a signature that is in the first line of a function's
> docstring, epydoc fails to recognize signatures with default arguments (cf.
> test5 in the attached test file).  I later noticed that I could strip them
> from the docstrings since epydoc will extract the default values from the
> function signature nevertheless, but I still see this as a shortcoming.

there was a bug indeed in the signature parsing: the regexpr used was fooled
by the spaces around the '=' symbol (actually by the one before: the one after
was correctly recognized). This wasn't widely tested because the function
signature is conventionally expressed without spaces around the '=' symbol -
see PEP 8; nevertheless i have enforced the signature parsing in the trunk
rev1589.

Also notice that the PEP 275 discourages to duplicate the function signature
in the docstring for pure Python modules: it can be retrieved by
introspection.

> b) When documenting a method, I like to write an object name in front of the
> signature in order to be able to reference the object by name in the
> documentation.  E.g. "someFoo.testMeth2(a, b)" in the attached file.
> Interestingly, epydoc *does* parse the object name, but it does not display
> it properly but introduce a new parameter of that name.  That looks like a
> bug to me, even if you could argue that it is the name of the object passed
> as "self" / first argument.  However, IMO the signature documents the
> *usage*
> of a function and there you would not call "Foo.testMeth2(someFoo, a, b)"
> but
> someFoo.testMeth2(a, b).  Comparing the documentations of testMeth1 and
> testMeth2 is also irritating, since both take the same number of arguments,
> but it looks different.

This is something the author has deliberately decided to do. Anyway it bit
me too once: this "feature" also kicks in when documenting a module
function. IIRC the psycopg signature for the "connect()" function was
expressed as "psycopg.connect()" and it appeared as "connect(psycopg)". I
was maintaining psycopg documentation, not epydoc yet, so i preferred to
change the function signature.

Edward, what is the rationale behind the "selfparam" in the function
signature parsing? It seems to me that dropping it would produce better
results in most cases (even for a bound method expressed whose signature in
the docstring is expressed as

   inst.func(a, b)

reporting "func(a, b)" seems kinda more correct than "func(inst, a, b)",
even if the self argument is missing)

> c) (enhancement proposal) Finally, I would like to be able to specify
> several
> signatures for the same function.  Sometimes, it is possible to call a
> function with different types of objects / different keyword arguments /
> ...,
> and I would like to document two different kinds of use cases.  (Yes, this
> is
> a little bit like function overloading, not really pythonic and not very
> important to me either.)

mmm... this is definitely to be documented in the docstring body. Python
doesn't support methods overloading: i don't think Epydoc should document a
function "as it were implemented in C++".

> d) It would be great it epydoc could extract signatures for boost::python
> exported functions, too (I am using boost 1.33.1 here, but I was told that
> 1.34.0 makes no difference here). Alas, I don't know how that is possible -
> the only way I know of displaying the signature / getting the info is to
> actually *call* the functions (argh!) with a dummy argument and parse the
> resulting error message. :-(  One can define a dummy class and rely on the
> fact that no function will ever do something with e.g. 42 arguments of that
> type, but that procedure looks really brittle to me, although we use that
> for
> tab-completion in an interactive python shell (but there, only single
> functions are called on demand, so this is less dangerous).

I don't know much about boost::python bindings. Shooting random parameters
to an unknown signature doesn't seem fair to me :) sip generated bindings
share a similar characteristic (actually sip doesn't generate any docstring
at all, i don't know about boost). If you point me at an OS project built
with boost i may play a bit with such functions.

> Otherwise, epydoc really looks impressive to me (rst support, nice
> output, ...)! :-)

Thank you ;)

Ciao ciao

-- 
Daniele Varrazzo - Develer S.r.l.
http://www.develer.com

[Epydoc-devel] Docstring parsing shortcomings

[Hans M. <me...@in...>]

Hi!

Today, I tried epydoc (3.0beta1) on one of my projects, and found several 
things that I miss / find strange:

a) When parsing a signature that is in the first line of a function's 
docstring, epydoc fails to recognize signatures with default arguments (cf. 
test5 in the attached test file).  I later noticed that I could strip them 
from the docstrings since epydoc will extract the default values from the 
function signature nevertheless, but I still see this as a shortcoming.

b) When documenting a method, I like to write an object name in front of the 
signature in order to be able to reference the object by name in the 
documentation.  E.g. "someFoo.testMeth2(a, b)" in the attached file.  
Interestingly, epydoc *does* parse the object name, but it does not display 
it properly but introduce a new parameter of that name.  That looks like a 
bug to me, even if you could argue that it is the name of the object passed 
as "self" / first argument.  However, IMO the signature documents the *usage* 
of a function and there you would not call "Foo.testMeth2(someFoo, a, b)" but 
someFoo.testMeth2(a, b).  Comparing the documentations of testMeth1 and 
testMeth2 is also irritating, since both take the same number of arguments, 
but it looks different.

c) (enhancement proposal) Finally, I would like to be able to specify several 
signatures for the same function.  Sometimes, it is possible to call a 
function with different types of objects / different keyword arguments / ..., 
and I would like to document two different kinds of use cases.  (Yes, this is 
a little bit like function overloading, not really pythonic and not very 
important to me either.)

d) It would be great it epydoc could extract signatures for boost::python 
exported functions, too (I am using boost 1.33.1 here, but I was told that 
1.34.0 makes no difference here). Alas, I don't know how that is possible - 
the only way I know of displaying the signature / getting the info is to 
actually *call* the functions (argh!) with a dummy argument and parse the 
resulting error message. :-(  One can define a dummy class and rely on the 
fact that no function will ever do something with e.g. 42 arguments of that 
type, but that procedure looks really brittle to me, although we use that for 
tab-completion in an interactive python shell (but there, only single 
functions are called on demand, so this is less dangerous).

Otherwise, epydoc really looks impressive to me (rst support, nice 
output, ...)! :-)

-- 
Ciao, /  /
     /--/
    /  / ANS

[Epydoc-devel] LaTeX markup

[Jonathan G. <gu...@ni...>]

Hello Ed Loper, et al.,

long time listener, first time caller...


We've been using epydoc on our FiPy project for a couple of years and  
are very happy with it. The one area where we thought there was room  
for improvement was in separating the content from the LaTeX markup  
(I recall similar desire re: HTML/CSS expressed at PyCon'04). We got  
this working well enough for our own needs about two years ago, but  
never cleaned it up enough to pass back. My reward for that lethargy,  
is that I got to merge the changes from 2.1 to 3.0 instead of letting  
Ed do it 8^). I've now managed to pull things together so that  
they're generally usable and brought them up to date with r1588 from  
the epydoc svn repository.

I've posted links to our changed files and some examples of output to  
https://www.matforge.org/fipy/wiki/EpydocLaTeX

There are still some issues I'm working on (there are some  
discrepancies in indexing, for instance), but I'd like to know if  
this is of any interest to the epydoc developers.

If these changes are accepted, then if nobody else is looking at it,  
I'm willing to tackle the inherited methods issue next (our manual is  
just way, way too long with all the inherited methods repeated all  
over the place), and then maybe try to get dot support working.

- Jon

Re: [Epydoc-devel] documentation for a c extension

[Paul P. <pog...@gm...>]

Edward Loper wrote:
> Paul Pogonyshev wrote:
> > I cannot find how to specify arguments a C extension function takes.
> > I can describe arguments with "@oaram name: ..." but function still
> > "accepts" ... in the docs.
> 
> You should write a signature as the first line of the docstring, like 
> Python's own builtins do.

That works, thanks.  Can it be found in Epydoc documentation somewhere?

Paul

Re: [Epydoc-devel] documentation for a c extension

[Edward L. <ed...@gr...>]

Paul Pogonyshev wrote:
> Hi,
> 
> Sorry if not the right place...
> 
> I cannot find how to specify arguments a C extension function takes.
> I can describe arguments with "@oaram name: ..." but function still
> "accepts" ... in the docs.

You should write a signature as the first line of the docstring, like 
Python's own builtins do.  E.g.:

   file(name[, mode[, buffering]]) -> file object

or:

   L.append(object) -- append object to end

epydoc will automatically parse the first line, and if it appears to be 
a signature, it will extract the args from it.  epydoc understands a 
variety of notation, including [optional] parameters, etc.  The value 
after the "--" or "->" will be treated as the @returntype field.

-Edward

[Epydoc-devel] documentation for a c extension

[Paul P. <pog...@gm...>]

Hi,

Sorry if not the right place...

I cannot find how to specify arguments a C extension function takes.
I can describe arguments with "@oaram name: ..." but function still
"accepts" ... in the docs.

Paul

Re: [Epydoc-devel] AttributeError: _Sentinel instance has no attribute '__getitem__'

[Daniele V. <pi...@de...>]

> On 3/29/07, Daniele Varrazzo <pi...@de...> wrote:
>> This bug has been already reported in the tracker, but i wasn't able to
>> reproduce it yet.
>>
>> Is the package you are documenting available on the web or is a private
>> project?
>
> It's a private project (for the moment at least - if only because the
> documentation is so poor!).
>
>> What is the command line you are using?
>
> epydoc --debug --output auto-doc/  npyscreen/
>
> (npyscreen is the name of the package)
>
>
>> > Warning: Module npyscreen.ActionForm is shadowed by a variable with the
>> >          same name.
>>
>> Correct me: in your package there is a module named "ActionForm.py"
>> containing a class named "ActionForm"? I suspect that this kind of errors
>> (and so issues like #1682525) are caused by a name clash like this, but i
>> don't have a test case yet (the people who reported the issue above gave
>> me
>> one, but i have to setup a VM to test it and i haven't had the time to do
>> that yet).
>
> Yes, there is.  I assume that the error is being caused by the fact that the
> __init__.py file for the package does things like the following to
> expose an API:
>
> from ActionForm import ActionForm

Great, i'll focus on this issue and try to crash Epydoc like this :)

>> To work around the bug you may try to --introspect-only or --parse-only.
>> Please, report success/failures of doing this.
>
> --introspect-only fails with the same error

Ok, this further narrows where to look for troubles.

> --parse-only works perfectly, and doesn't give the warnings above.
> Instead I get the output I've printed below (minor warnings).

Those warnings are only about bad Epytext docstring. By default Epydoc
expects doctrings formatted in the Epytext markup language, which is widely
documented in the manual. You may also choose different markups;
specifically, if you want Epydoc to assume no markup, use the
--docformat=plaintext command line switch.

Thank you very much for the report: i will try to fix the bug and release a
beta2 version soon (many bugs have been reported and most of them have been
fixed since the beta1 was released).

-- 
Daniele Varrazzo - Develer S.r.l.
http://www.develer.com

[Epydoc-devel] AttributeError: _Sentinel instance has no attribute '__getitem__'

[Nicholas C. <nic...@gm...>]

On 3/29/07, Daniele Varrazzo <pi...@de...> wrote:
> This bug has been already reported in the tracker, but i wasn't able to
> reproduce it yet.
>
> Is the package you are documenting available on the web or is a private
> project?

It's a private project (for the moment at least - if only because the
documentation is so poor!).

> What is the command line you are using?

epydoc --debug --output auto-doc/  npyscreen/

(npyscreen is the name of the package)


> > Warning: Module npyscreen.ActionForm is shadowed by a variable with the
> >          same name.
>
> Correct me: in your package there is a module named "ActionForm.py"
> containing a class named "ActionForm"? I suspect that this kind of errors
> (and so issues like #1682525) are caused by a name clash like this, but i
> don't have a test case yet (the people who reported the issue above gave me
> one, but i have to setup a VM to test it and i haven't had the time to do
> that yet).

Yes, there is.  I assume that the error is being caused by the fact that the
__init__.py file for the package does things like the following to
expose an API:

from ActionForm import ActionForm

> To work around the bug you may try to --introspect-only or --parse-only.
> Please, report success/failures of doing this.

--introspect-only fails with the same error

--parse-only works perfectly, and doesn't give the warnings above.
Instead I get the output I've printed below (minor warnings).

Best wishes,

Nicholas


epydoc --parse-only --debug --output auto-doc/  npyscreen/
Warning: 6 markup errors were found while processing docstrings.  Use
the verbose switch (-v)
         to display markup errors.
stav092:~/projects/spook/mnpyscreen nicholas$ epydoc -v --parse-only
--debug --output auto-doc/  npyscreen/
+----------------------------------------------------------------------------------------------
| File /Users/nicholas/projects/spook/mnpyscreen/npyscreen/NPSAppManaged.py,
line 11, in
| npyscreen.NPSAppManaged.NPSAppManaged
|   Warning: Line 13: Lists must be indented.
|
+----------------------------------------------------------------------------------------------
| File /Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/textwrap.py,
line 33, in
| textwrap.TextWrapper
|   Warning: Lines 41, 42, 44, 45, 47, 48, 50, 51, 54, 55, 59, 60, 63,
64: Improper paragraph
|            indentation.
|
+----------------------------------------------------------------------------------------------
| File /Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/textwrap.py,
line 147,
| in textwrap.TextWrapper._fix_sentence_endings
|   Warning: Lines 149, 152: Improper paragraph indentation.
|
+----------------------------------------------------------------------------------------------
| File /Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/textwrap.py,
line 165,
| in textwrap.TextWrapper._handle_long_word
|   Warning: Line 166: Improper paragraph indentation.
|
+----------------------------------------------------------------------------------------------
| File /Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/textwrap.py,
line 115,
| in textwrap.TextWrapper._munge_whitespace
|   Warning: Lines 117, 121: Improper paragraph indentation.
|
+----------------------------------------------------------------------------------------------
| File /Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/textwrap.py,
line 132,
| in textwrap.TextWrapper._split
|   Warning: Lines 137, 139: Improper paragraph indentation.
|

[Epydoc-devel] AttributeError: _Sentinel instance has no attribute '__getitem__'

[Nicholas C. <nic...@gm...>]

Hi.  I'm using the latest epidoc beta, and it keeps failing with the
following error (I've included the warnings, in case they signify for
this issue).  If this is a known issue, is there anything I can do in
my code as a work-around?

Best wishes,

N.



Warning: Module npyscreen.ActionForm is shadowed by a variable with the
         same name.
Warning: Module npyscreen.NewMenu is shadowed by a variable with the same
         name.
Warning: Module npyscreen.Popup is shadowed by a variable with the same
         name.
Warning: Module npyscreen.FormWithMenus is shadowed by a variable with the
         same name.
Warning: Module npyscreen.NPSApp is shadowed by a variable with the same
         name.
Warning: Module npyscreen.NPSAppManaged is shadowed by a variable with the
         same name.
Warning: npyscreen.Menu shadows itself
Warning: npyscreen.Form shadows itself
Traceback (most recent call last):  Progress:                          00:02
  File "/Library/Frameworks/Python.framework/Versions/Current/bin/epydoc",
line 13, in <module>            Writing HTML docs: epydoc.js
    cli()
  File "/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/site-packages/epydoc/cli.py",
line 946, in cli
    main(options, names)
  File "/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/site-packages/epydoc/cli.py",
line 764, in main
    write_html(docindex, options)
  File "/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/site-packages/epydoc/cli.py",
line 804, in write_html
    html_writer.write(options.target)
  File "/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/site-packages/epydoc/docwriter/html.py",
line 553, in write
    indices = {'ident': self.build_identifier_index(),
  File "/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/site-packages/epydoc/docwriter/html.py",
line 2817, in build_identifier_index
    name = plaintext_to_html(doc.canonical_name[-1])
AttributeError: _Sentinel instance has no attribute '__getitem__'

[Epydoc-devel] Ann: Chm package for epydoc

[<jU...@ar...>]

I would like to announce the release of a Chm compiler
package for epydoc. This package generates project files
for epydoc Html output and handles compiling (if desired).

The package contains a commandline script "gen_epydoc.py"
to quick dump a directory containing epydoc Html output to a Chm.

Notes:

The package is an alpha and not heavily tested. Would be nice to get
some feedback. Especially if it works on linux (and maybe Mac, if it is
possible to run microsofts compiler on Mac), cos I have currenly no means
to test on these oses.

You will see many, many warnings when compiling. This is because
microsofts compiler expects Html files as input and currently XHtml is fed.


Prerequesites:

Microsofts Html Help Workshop should be installed (windows). Wine and
Html Help Workshop on linux. And, off course, epydoc.


Install:
Put the package somewhere on your python path and run
"gen_chm_docs.py"
to dump the documentation for the package to the "doc" subdir.


Where to get it:

Either from the subversion repository:
svn export 
https://frogpie.svn.sourceforge.net/svnroot/frogpie/trunk/sandbox/chm 
/wherever

Or as zip from here:
http://home.arcor.de/jurner/chm-0.1a.zip


Regards, Jürgen

[Epydoc-devel] value representation: parsed vs. introspected

[Paul P. <pog...@gm...>]

Edward Loper wrote (in the SF bug tracker):
> The behavior Daniele described is actually the intended behavior: epydoc
> currently uses a heuristic scoring function to decide on the trade-off
> between when to use the parsed vs introspected repr.  See
> epydoc.markup.pyval_repr for more info on it, but basically the score gets
> -5 for things like <this at 0x123>, but gets +1 for each item it processes
> in a pretty-printed way.  So for something like:
> 
> [1, 'x', 2, 3, 4, 5, <this at 0x123>]
> 
> epydoc will use the introspected repr even though it has an "ugly" value. 
> 
> 
> Perhaps this scoring function needs to be adjusted?  If you think so,
> bring it up on epy...@li...

Well, without much thinking, I'd suggest that if parsed and repr()
representations are equal, then don't award +1 bonus.  And maybe add
special cases for strings, like "/' dichotomy etc.

No idea if that is difficult to implement.

Paul

Re: [Epydoc-devel] chm files

[<jU...@ar...>]

Daniele Varrazzo schrieb:
>> Daniele Varrazzo schrieb:
>>     
>>>> Can i have a sample of how the hhc, hhk, hhp file should appear? You may
>>>> use
>>>> the tracker item above to post the files, to keep all the chm stuff
>>>> together
>>>> (i marked the item as to be done for 3.1 release; now i'm mostly focused
>>>> on
>>>> functional testing for the 3.0 release).
>>>>
>>>>
>>>>         
>> There seems no way to attatch files in tracker comments, so I dumped some
>> samples and links for further reading into the comment box of the tracker.
>>     
>
> Thank you for the exaustive description: it will be very useful to put
> together the chm support.
>
>   

...took a bit closer look at epydoc now and ran a test compile.

Everything works fine, micros compiler is complaining
about the xml decls in the html files, but does the job.

Generating a Chm from epydoc seems to be no more
than running a parser over the generated html output
to bring the (dotted) names epydoc throws out into
hirarchical form ++ a bit of this and a bit of that.
Should be no problem to get some reasonable output in a few
days without even toutching the internals of epydoc.

In case you are interested, see: chm_doc.py

http://frogpie.svn.sourceforge.net/svnroot/frogpie/trunk/sandbox/chm


BTW: epydoc looks great as Chm. Congrats....


Jürgen

Re: [Epydoc-devel] chm files

[<jU...@ar...>]

Daniele Varrazzo schrieb:
>> Daniele Varrazzo schrieb:
>>     
>>>> Can i have a sample of how the hhc, hhk, hhp file should appear? You may
>>>> use
>>>> the tracker item above to post the files, to keep all the chm stuff
>>>> together
>>>> (i marked the item as to be done for 3.1 release; now i'm mostly focused
>>>> on
>>>> functional testing for the 3.0 release).
>>>>
>>>>
>>>>         
>> There seems no way to attatch files in tracker comments, so I dumped some
>> samples and links for further reading into the comment box of the tracker.
>>     
>
> Thank you for the exaustive description: it will be very useful to put
> together the chm support.
>
>   

I am currently fiddeling along on a Chm generator. If you like you may
take a look...

http://frogpie.svn.sourceforge.net/svnroot/frogpie/trunk/sandbox/chm


Jürgen

Re: [Epydoc-devel] chm files

[Daniele V. <pi...@de...>]

> Daniele Varrazzo schrieb:
>>> Can i have a sample of how the hhc, hhk, hhp file should appear? You may
>>> use
>>> the tracker item above to post the files, to keep all the chm stuff
>>> together
>>> (i marked the item as to be done for 3.1 release; now i'm mostly focused
>>> on
>>> functional testing for the 3.0 release).
>>>
>>>
>
> There seems no way to attatch files in tracker comments, so I dumped some
> samples and links for further reading into the comment box of the tracker.

Thank you for the exaustive description: it will be very useful to put
together the chm support.

-- 
Daniele Varrazzo - Develer S.r.l.
http://www.develer.com

[Epydoc-devel] Epydoc 3.0 beta release

[Edward L. <ed...@gr...>]

Epydoc 3.0 beta is now available for download from SourceForge.
Epydoc is a tool for generating API documentation for Python modules,
based on their docstrings.

   - The epydoc homepage.
     <http://epydoc.sourceforge.net/>

   - Download epydoc 3.0 beta.
     <http://sourceforge.net/project/platformdownload.php? 
group_id=32455>

For some examples of the documentation generated by epydoc, see:

   - The API documentation for epydoc.
     <http://epydoc.sourceforge.net/api/>

   - The API documentation for the Python 2.5 standard library.
     <http://epydoc.sourceforge.net/stdlib/>

   - The API documentation for NLTK, the natural language toolkit.
     <http://nltk.sourceforge.net/lite/doc/api/>

The most significant change since Epydoc 2.1 has to do with the way
that epydoc extracts documentation information about python modules.
In previous versions, epydoc extracted information about each module
by importing it, and using introspection to examine its contents.  The
new version of epydoc still supports introspection, but is also
capable of extracting information about python modules by parsing
their source code.  Furthermore, the new version of epydoc can combine
these two sources of information (introspection & parsing).  This is
important because each source has its own advantages and disadvantages
with respect to the other.  For information about the new features in
epydoc 3.0, see the "What's New" page:

     <http://epydoc.sourceforge.net/whatsnew.html>

If you find any bugs, or have suggestions for improving epydoc, please
report them on sourceforge:

   - Bugs: <http://tinyurl.com/odvfw>
   - Features: <http://tinyurl.com/p2rl8>

Or send email to <epy...@li...>.

Re: [Epydoc-devel] chm files

[<jU...@ar...>]

Daniele Varrazzo schrieb:
>> Can i have a sample of how the hhc, hhk, hhp file should appear? You may use
>> the tracker item above to post the files, to keep all the chm stuff together
>> (i marked the item as to be done for 3.1 release; now i'm mostly focused on 
>> functional testing for the 3.0 release).
>>
>>     

There seems no way to attatch files in tracker comments, so I dumped some
samples and links for further reading into the comment box of the tracker.

Jürgen

Re: [Epydoc-devel] chm files

[<jU...@ar...>]

Daniele Varrazzo schrieb:
>  
>  >
>  > Yes, I thought of something like simply parsing over the html output from
> epydoc, bringing the htmls into adequate form (removing frames
> ....).
>
> The .chm writer would omit to write frames-related stuff, as the html writer
>
> does with the --no-frames option (as should have done, actually... fixed in 
> r1550). I wouldn't perform a post-processing of epydoc pages: instead i'd 
> subclass the current HTMLWriter to directly let it create the required
> files.
> What other difference should be taken into account to create html files to be
> chm-compiled? Remember that much customization can be performed using an 
> appropriate css stylesheet.
>   

That's a clean option, if if not too difficult to implement. Difference 
sould be only to get
rid of the browse frames 'cos all browsing is handled by the chm window.


>  > I already have a some modules at hand. One to generate all the required
> files for micros html workshop compiler (needs rework, ugly code!) and
> one for
>  > parsing and bringing into shape html files. All not heavily tested,
> though working.
>
> Can i have a sample of how the hhc, hhk, hhp file should appear? You may use
> the tracker item above to post the files, to keep all the chm stuff together
> (i marked the item as to be done for 3.1 release; now i'm mostly focused on 
> functional testing for the 3.0 release).
>   

I'll prepair some samle files and post them as soon as I find the time.

> A question: can the index and table of content contain actually different 
> indexes? We can generate the class index and the modules indexes, and we can
> generate an identifiers and a term definitions tables of contents: it would be
> nice if all could fit into the compiled help without having to mix classes 
> with modules and terms with identifiers. It's not a great issue anyway,
> mostly   curious...
>   

No, I don't think this possible. HelpWorkshop supports plugging together
multiple chms but the index is generated as one from all chms.
But one can freely name keywords as they appear in the index or if it
comes to that, provide some meta keywords.


>  > Think I could throw this together in a few weeks to a working alpha. But
> the thing I can not do is test it on linux. AFAIK, Wine supports micros
> compiler
>  > and it would be nice to support this.
>
> I've never run it on Wine (actually, i've never run it at all :) but it 
> doesn't seem an issue to run the compiler once you have the project [1]. We 
> should add a --chm-compiler option to tell epydoc the command line to run;
> the
> files generation could be performed even if the compiler were not available or
> couldn't run on the current platform anyway.
>
>   

No problem to generate the required files without actually compiling.
Commandline ....you actually feed the compiler  an *.ini file like 
project file with
all required data. Things like:

- where is the index file
- where is the contents file
- title of the window
- buttons to show
- a dozen more.....

so a single chm option might be a bit uncomfortable. But I have to take 
a closer look at it.



> [1]
> http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconprjcmp7.asp
>
>  > And ....of course, I'd welcome any help or advice on implementation
> details.
>
> Just for a pointer, the indexes are created in the epydoc.docwriters.html.py
>
> module, in the HTMLWriter.write() method. I think the informations required to
> create chm indexes are the same gathered here: i guess it's a matter of 
> creating pages with different format and names for the indexes to be passed
> to
> the compiler. The class should be refactored so that a ChmWriter could be 
> easily subclassed from it, but apart from changing the implementation of the
> indexes pages writing, i think there not much stuff to be done.
>
> Probably the list of files to be included in the project should be created 
> reading back from the disk every file which has been written in the output 
> directory: this way also images (which may be more difficult to track: think
> about images generated by docutils directives such as the math formulas we are
> everybody expecting...) may be included in the chm project.
>   

Images (and css and javascripts) are handled by micros compiler. As long as
they are linked correctly they are automatically included in the 
project. So that's
easier aswell to handle on an already dumped tree ++ you have to know 
wheter
a folder contains subitems or not. So there is a some lookahead necessary.


It all boils down to two methods

def has_intersting_subitems(item):
    # yes, give it a folder icon
    # no, give it a file icon

def get_index_page(items):
    # locate the item to be displayed when clicking on a folder in the tree


to get a contents tree like this:

<chm>
    <item name="root" local='root.html' icon="folder">
        <item name="page1" local="root/page1.html"/>
        <item name="page2" local="root/page2.html"/>
    </item>
</chm>

other names in the contents file ...Html not Xml, but it should give the 
idea.

But I don't know what epydoc offers to handle this. Or if it there is need
to process intime rather than processing an already dumped tree.



> Finally, adding a --chm action to the command line and the hook for the chm 
> compiler should be done in the cli.py module.
>
> Regards,
>
>   

Jürgen

[Epydoc-devel] Added indexed terms in reStructuredText

[Daniele V. <pi...@de...>]

Hello,

i added support for indexed terms in reStructuredText. in epytext they are 
created using the X{...} markup, but nothing similar was available in reST
markup.

The role added is ``term``, so if you want to add "subject" to the terms index
you have to write :term:`subject` or `subject`:term:

Any comment about the choice of "term" as role name or about the
implementation (r1551) is welcome.

-- 
Daniele Varrazzo - Develer S.r.l.
http://www.develer.com

Re: [Epydoc-devel] chm files

[Daniele V. <pi...@de...>]

Jürgen Urner ha scritto:
 > Daniele Varrazzo schrieb:
 >> Jürgen Urner ha scritto:
 >>
 >>> Hello,
 >>>
 >>> ...didn't know epydoc is under active developement again.
 >>>
 >>> I just would like to ask if someone is already working on on some
 >>>
 >> mechanism to generate microsoft *.chm files from epydoc output.
 >>
 >>> If not, maybe someone here is interested in joining forces to add this
 >>>
 >> feature
 >>
 >>> to epydoc?
 >>>
 >>> Jürgen
 >>>
 >>>
 >> Hello,
 >>
 >> i think .chm output would be a nice feature, and i think easy enough to
put together.
 >>
 >> My experience is very limited, but it seems chm are just a bunch of html
files together with an index, a ToC and a project file: Epydoc should
produce only a few files more than what the html writer already does.
The
 >> HTML generator already builds identifiers and terms indexes, so it's
probably just a matter of reformatting them to get them right for the
.chm: the informations required are already there.
 >>
 >> There is a open feature request for chm files (SF #938921) where Robin
Dunn posted a script to generate support files to compile a CHM version
of
 >> Python docs: if i had to start with a .chm writer i would start from there.
 >>
 >> I'd work for it after the 3.0 has been completed; any help you may give
would be appreciated and would help us to quickly have chm support in
the
 >> 3.1 alpha development line.
 >>
 >> Thank you very much,
 >>
 >>
 >
 > Yes, I thought of something like simply parsing over the html output from
epydoc, bringing the htmls into adequate form (removing frames
....).

The .chm writer would omit to write frames-related stuff, as the html writer

does with the --no-frames option (as should have done, actually... fixed in 
r1550). I wouldn't perform a post-processing of epydoc pages: instead i'd 
subclass the current HTMLWriter to directly let it create the required
files.
What other difference should be taken into account to create html files to be
chm-compiled? Remember that much customization can be performed using an 
appropriate css stylesheet.

 > I already have a some modules at hand. One to generate all the required
files for micros html workshop compiler (needs rework, ugly code!) and
one for
 > parsing and bringing into shape html files. All not heavily tested,
though working.

Can i have a sample of how the hhc, hhk, hhp file should appear? You may use
the tracker item above to post the files, to keep all the chm stuff together
(i marked the item as to be done for 3.1 release; now i'm mostly focused on 
functional testing for the 3.0 release).

A question: can the index and table of content contain actually different 
indexes? We can generate the class index and the modules indexes, and we can
generate an identifiers and a term definitions tables of contents: it would be
nice if all could fit into the compiled help without having to mix classes 
with modules and terms with identifiers. It's not a great issue anyway,
mostly   curious...

 > Think I could throw this together in a few weeks to a working alpha. But
the thing I can not do is test it on linux. AFAIK, Wine supports micros
compiler
 > and it would be nice to support this.

I've never run it on Wine (actually, i've never run it at all :) but it 
doesn't seem an issue to run the compiler once you have the project [1]. We 
should add a --chm-compiler option to tell epydoc the command line to run;
the
files generation could be performed even if the compiler were not available or
couldn't run on the current platform anyway.

[1]
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconprjcmp7.asp

 > And ....of course, I'd welcome any help or advice on implementation
details.

Just for a pointer, the indexes are created in the epydoc.docwriters.html.py

module, in the HTMLWriter.write() method. I think the informations required to
create chm indexes are the same gathered here: i guess it's a matter of 
creating pages with different format and names for the indexes to be passed
to
the compiler. The class should be refactored so that a ChmWriter could be 
easily subclassed from it, but apart from changing the implementation of the
indexes pages writing, i think there not much stuff to be done.

Probably the list of files to be included in the project should be created 
reading back from the disk every file which has been written in the output 
directory: this way also images (which may be more difficult to track: think
about images generated by docutils directives such as the math formulas we are
everybody expecting...) may be included in the chm project.

Finally, adding a --chm action to the command line and the hook for the chm 
compiler should be done in the cli.py module.

Regards,

-- 
Daniele Varrazzo - Develer S.r.l.
http://www.develer.com

Re: [Epydoc-devel] chm files

[<jU...@ar...>]

Daniele Varrazzo schrieb:
> Jürgen Urner ha scritto:
>   
>> Hello,
>>
>> ...didn't know epydoc is under active developement again.
>>
>> I just would like to ask if someone is already working on on some
>>     
> mechanism to generate microsoft *.chm files from epydoc output.
>   
>> If not, maybe someone here is interested in joining forces to add this 
>>     
> feature
>   
>> to epydoc?
>>
>> Jürgen
>>
>>     
>
> Hello,
>
> i think .chm output would be a nice feature, and i think easy enough to
> put together.
>
> My experience is very limited, but it seems chm are just a bunch of html
> files together with an index, a ToC and a project file: Epydoc should 
> produce only a few files more than what the html writer already does.  The
> HTML generator already builds identifiers and terms indexes, so it's
> probably just a matter of reformatting them to get them right for the
> .chm: the informations required are already there.
>
> There is a open feature request for chm files (SF #938921) where Robin
> Dunn posted a script to generate support files to compile a CHM version of
> Python docs: if i had to start with a .chm writer i would start from
> there.
>
> I'd work for it after the 3.0 has been completed; any help you may give
> would be appreciated and would help us to quickly have chm support in the
> 3.1 alpha development line.
>
> Thank you very much,
>
>   

Yes, I thought of something like simply parsing over the html output
from epydoc, bringing the htmls into adequate form (removing frames ....).

I already have a some modules at hand. One to generate all the required
files for micros html workshop compiler (needs rework, ugly code!) and 
one for
parsing and bringing into shape html files. All not heavily tested, 
though working.

Think I could throw this together in a few weeks to a working alpha.
But the thing I can not do is test it on linux. AFAIK, Wine supports 
micros compiler
and it would be nice to support this.

And ....of course, I'd welcome any help or advice on implementation details.

Thanks for feedback, Jurgen

Re: [Epydoc-devel] chm files

[Daniele V. <pi...@de...>]

Jürgen Urner ha scritto:
> Hello,
>
> ...didn't know epydoc is under active developement again.
>
> I just would like to ask if someone is already working on on some
mechanism to generate microsoft *.chm files from epydoc output.
>
> If not, maybe someone here is interested in joining forces to add this 
feature
> to epydoc?
>
> Jürgen
>

Hello,

i think .chm output would be a nice feature, and i think easy enough to
put together.

My experience is very limited, but it seems chm are just a bunch of html
files together with an index, a ToC and a project file: Epydoc should 
produce only a few files more than what the html writer already does.  The
HTML generator already builds identifiers and terms indexes, so it's
probably just a matter of reformatting them to get them right for the
.chm: the informations required are already there.

There is a open feature request for chm files (SF #938921) where Robin
Dunn posted a script to generate support files to compile a CHM version of
Python docs: if i had to start with a .chm writer i would start from
there.

I'd work for it after the 3.0 has been completed; any help you may give
would be appreciated and would help us to quickly have chm support in the
3.1 alpha development line.

Thank you very much,

-- 
Daniele Varrazzo - Develer S.r.l.
http://www.develer.com

[Epydoc-devel] chm files

[<jU...@ar...>]

Hello,

...didn't know epydoc is under active developement again.

I just would like to ask if someone is already working on on some
mechanism to generate microsoft *.chm files from epydoc output.

If not, maybe someone here is interested in joining forces to add this 
feature
to epydoc?

Jürgen



 

[Epydoc-devel] Displaying unicode string values

[Edward L. <ed...@gr...>]

Currently, in the HTML output, unicode string values are displayed =20
using a format similar to repr.  I.e., if you define a variable:

   x =3D u'D=E9faut'

then its value will be rendered in the output docs as:

   u'D\xe9faut'

Similarly for parameter default values.  But there's been a request =20
to change this to display the string literal using unicode [1].  I'm =20
ambivalent about which way I prefer, so I wanted to see if anyone =20
else had opinions on the matter.  Advantages of the current escaped =20
repr (u'D\xe9faut'):

   - Not all browsers can display all unicode characters; but all =20
browsers
     can display ascii.  E.g., rendering u'D=E9faut' in a text-based =20
browser
     like links just reduces it to "u'Default'", which is a different =20=

Python
     value.

   - Certain unicode characters can look very similar to ascii =20
characters or
     other unicode characters; there's less chance of misunderstanding a
     value if it's in ascii and unicode chars are escaped.

Advantages of the unescaped repr:

   - Easier to read.

Thoughts?
-Edward

[1] https://sourceforge.net/tracker/index.php?=20
func=3Ddetail&aid=3D1663578&group_id=3D32455&atid=3D405618