[Epydoc-devel] How to? epydoc --top=README

P

Phlip

Pythonistas:

I have a question to epydoc-devel, but it might be languishing:

http://sourceforge.net/mailarchive/[email protected]&forum_name=epydoc-devel

How do you populate the index.html output with your (insanely clever)
contents of your README file?

When I try the obvious notations, such as --top=README or --
top=README.html, I get:

Warning: Identifier 'README' looks suspicious; using it anyway.
Warning: Could not find top page 'README'; using module-tree.html
instead

And, yes, the README is included in the input list, and yes I get a
script-README-module.html

----8<------------------------------------------

The question for the rest of Python-Land: Should I be using a better
documentation extractor? (pydoc is too mundane so far.) Or should I be
using a better forum for epydoc users questions?
 
J

Jean-Michel Pichavant

Phlip said:
Okay, we have ten thousand classes to document. How to add them all to
index.rst?
Click to expand...
I remember trying using Sphinx for auto documented APIs, but it was not
suitable at that time. You can include API docs generated from the code,
but you still need to write the docs around.
If I'm correct, Sphinx is one of the best tool to document public APIs.
However to build internal documentation with everything from interfaces
to implementations, epydoc is still the best, it builds everything with
no additional writing, just press the button.


JM
 
P

Phlip

I remember trying using Sphinx for auto documented APIs, but it was not
suitable at that time. You can include API docs generated from the code,
but you still need to write the docs around.
If I'm correct,  Sphinx is one of the best tool to document public APIs..
However to build internal documentation with everything from interfaces
to implementations, epydoc is still the best, it builds everything with
no additional writing, just press the button.
Click to expand...

Ah, thanks. We are all about writing '''doc strings''', then ripping
them to form documentation that we DO intend someone to READ and USE!

Now the problem with epydoc is it uses a persnickety text markup
language that...

- throws a syntax error & reverts to <pre> when the wind blows
- demands all kinds of extra markup, such as @param
- uses >3 different kinds of escapes, @, L{}, & <html>
- has no developer tests to speak of

I'm all about cross-linking and transcluding, and I wanted to upgrade
epydoc to do it, so I need to make sure that all those issues are
going to be either worth our time to fix or work around, and I didn't
overlook some better system.
 
J

Jean-Michel Pichavant

Phlip said:
Ah, thanks. We are all about writing '''doc strings''', then ripping
them to form documentation that we DO intend someone to READ and USE!

Now the problem with epydoc is it uses a persnickety text markup
language that...

- throws a syntax error & reverts to <pre> when the wind blows
- demands all kinds of extra markup, such as @param
- uses >3 different kinds of escapes, @, L{}, & <html>
- has no developer tests to speak of

I'm all about cross-linking and transcluding, and I wanted to upgrade
epydoc to do it, so I need to make sure that all those issues are
going to be either worth our time to fix or work around, and I didn't
overlook some better system.
Click to expand...
epydoc supports reStructured text markups. AFAIK it's still the best doc
builder available for python code. Too bad it is not maintained since 2
years and the 3.0 release.
If there was any effort to provide however, I think it would be on
sphinx so it would allow building the complete doc from python code. As
written in the doc, it's currently half-automated.

JM
 
P

Phlip

epydoc supports reStructured text markups.

Oh, good. For a moment there, I thought I'd be stuck with a markup
language that was persnickety!
 
P

Phlip

Pythonistas:

I have a question to epydoc-devel, but it might be languishing:

http://sourceforge.net/mailarchive/forum.php?thread_name=l2n860c114f1....

How do you populate the index.html output with your (insanely clever)
contents of your README file?

When I try the obvious notations, such as --top=README or --
top=README.html, I get:

Warning: Identifier 'README' looks suspicious; using it anyway.
Warning: Could not find top page 'README'; using module-tree.html
instead

And, yes, the README is included in the input list, and yes I get a
script-README-module.html

----8<------------------------------------------

The question for the rest of Python-Land: Should I be using a better
documentation extractor? (pydoc is too mundane so far.) Or should I be
using a better forum for epydoc users questions?
Click to expand...

Regardless of the advocacy, does anyone have an actual answer for
this?
 

Members online

Total: 40 (members: 2, guests: 38)
Robots: 82

Forum statistics

Threads
473,770
Messages
2,569,585
Members
45,080
Latest member
mikkipirss

Latest Threads

Top