467,161 Members | 906 Online
Bytes | Developer Community
Ask Question

Home New Posts Topics Members FAQ

Post your question to a community of 467,161 developers. It's quick & easy.

Printing Docstrings Without Importing

I have a large project that is getting complex, and I would like to
print the docstrings without importing the modules. The only Python
utility I could find references is apparently defunct and hasn't been
updated in 4 years.

I don't care how spartan the output is - it could look exactly like
python's internal docstrings, for all I care. It would be a nice added
bonus if it printed to HTML, but not if it greatly increased the
interface complexity. But I don't want to have to import the module to
run it! I want to just have a function that I pass a list of filenames
to.

Does anyone know of such a utility?

Jul 30 '05 #1
  • viewed: 2581
Share:
6 Replies
On 30 Jul 2005 11:08:29 -0700, "Kamilche" <kl*******@comcast.net> wrote:
I have a large project that is getting complex, and I would like to
print the docstrings without importing the modules. The only Python
utility I could find references is apparently defunct and hasn't been
updated in 4 years.

I don't care how spartan the output is - it could look exactly like
python's internal docstrings, for all I care. It would be a nice added
bonus if it printed to HTML, but not if it greatly increased the
interface complexity. But I don't want to have to import the module to
run it! I want to just have a function that I pass a list of filenames
to.

Does anyone know of such a utility?

No, but here's one I just created (not tested very much):

----< docstr2html.py >--------------------------------------------
# docstr2html.py
"""
Prints html to display docstrings of modules specified on command line,
with optional globbing and html page title default override.

Usage: [python] docstr2html.py [-title "some title"] (file_pattern)+

Note: If redirecting stdout, some windows versions require [python] to be explicit.
"""
import glob, time, compiler

# copied from cgi module:
def escape(s, quote=None):
"""Replace special characters '&', '<' and '>' by SGML entities."""
s = s.replace("&", "&amp;") # Must be done first!
s = s.replace("<", "&lt;")
s = s.replace(">", "&gt;")
if quote:
s = s.replace('"', "&quot;")
return s

def htmlhdr(title=None):
if title is None: title = 'doc strings as of %s'%time.ctime()
print '<html><head><title>%s</title></head><body>' %escape(title)

def htmltrlr():
print '</body></html>'

def module_file_docstr2html(modulesourcepath):
print '<br>'
print '<table border="2">'
print ' <tr bgcolor="#99FFFF"><th>%s</th></tr>' % escape(modulesourcepath)
try:
print ' <tr bgcolor="#99FF99"><td><pre>%s</pre></td></tr>' % escape(compiler.parseFile(modulesourcepath).doc)
except Exception, e:
print ' <tr bgcolor="#FFFFFF"><td><font color="#FF0000"><b>Error encountered:<br>%s</b></font></td></tr>' % escape(
'Exception %s: %s' % (e.__class__.__name__, e))
print '</table>'
if __name__ == '__main__':
import sys, os
args = sys.argv[1:]
if not args: raise SystemExit(__doc__)
if args[0] == '-title': args.pop(0); title = args.pop(0)
else: title = None
htmlhdr(title)
for fspec in args:
for path in glob.glob(fspec):
module_file_docstr2html(os.path.abspath(path))
htmltrlr()
------------------------------------------------------------------

Running it (first to get the help response, which is just the doc string ;-)

[20:04] C:\pywk\ut>python docstr2html.py

Prints html to display docstrings of modules specified on command line,
with optional globbing and html page title default override.

Usage: [python] docstr2html.py [-title "some title"] (file_pattern)+

Note: If redirecting stdout, some windows versions require [python] to be explicit.
Then generating the html:

[20:04] C:\pywk\ut>python docstr2html.py docstr2html.py
<html><head><title>doc strings as of Sun Jul 31 20:04:55 2005</title></head><body>
<br>
<table border="2">
<tr bgcolor="#99FFFF"><th>C:\pywk\ut\docstr2html.py</th></tr>
<tr bgcolor="#99FF99"><td><pre>
Prints html to display docstrings of modules specified on command line,
with optional globbing and html page title default override.

Usage: [python] docstr2html.py [-title "some title"] (file_pattern)+

Note: If redirecting stdout, some windows versions require [python] to be explicit.
</pre></td></tr>
</table>
</body></html>

You can use file specs like someplace\*.py (wild cards) and it should do all the files
and put it all in tables in the html output. Note that is uses all file specs as patterns,
and ignores without complaint any that don't match anything.

Regards,
Bengt Richter
Aug 1 '05 #2
This seems to scratch several people's itches.

Care to develop/maintain it ?

Regards,

Fuzzball
http://www.voidspace.org.uk/python

Aug 1 '05 #3
On 1 Aug 2005 06:50:23 -0700, "Fuzzyman" <fu******@gmail.com> wrote:
This seems to scratch several people's itches.

Care to develop/maintain it ?

Are you talking to me? ;-)

(My news server is having some problem. I saw my post on google groups
but my normal news client isn't seeing it.)

Assuming you are talking to me, there's a bug, naturally, in trying to
escape None as a doc string. It was twenty minutes of hacking and a half hour
of trying to choose html colors, so there's not that much there ;-)
But what did you have in mind? Javascript menu rollovers for popup docs of
functions and classes and methods etc? Full help info access? Optional pdf output?

That would take more than another hour, but I did fix the mentioned bug and put
a table of clickable module names at the top with the file date stamps and paths
so you can navigate down to the spcific module docstring output quickly if you have
a lot of them. Of course, I think I'd put styling in the header rather than hack
more raw html if I were to go another round.

I'll post the latest once I can see my postings in context with my own newsreader again.

Regards,
Bengt Richter
Aug 2 '05 #4
Fuzzyman wrote:
This seems to scratch several people's itches.

As I understand it it is something like generating "pythondoc" like javadoc?
Should be pretty easy to develop something a bit more polished than
Bengt's solution (or based on it of course) with maybe similar to
javadoc framesets for a navigational list etc.

But usn't there something like that from the docutils project (I must
admit I should have googled for it but have not have the time yet).
I was looking for something to but found only epydoc yet with yet
another of its own markup, docutils being something like a standard for
python (at least that's what I thought) would be really nice for it.
chris

sorry if i totally misunderstood the question...
Aug 2 '05 #5

Bengt Richter wrote:
On 1 Aug 2005 06:50:23 -0700, "Fuzzyman" <fu******@gmail.com> wrote:
This seems to scratch several people's itches.

Care to develop/maintain it ?
Are you talking to me? ;-)

(My news server is having some problem. I saw my post on google groups
but my normal news client isn't seeing it.)

Assuming you are talking to me, there's a bug, naturally, in trying to
escape None as a doc string. It was twenty minutes of hacking and a half hour
of trying to choose html colors, so there's not that much there ;-)
But what did you have in mind? Javascript menu rollovers for popup docs of
functions and classes and methods etc? Full help info access? Optional pdf output?

That would take more than another hour, but I did fix the mentioned bug and put
a table of clickable module names at the top with the file date stamps and paths
so you can navigate down to the spcific module docstring output quickly if you have
a lot of them. Of course, I think I'd put styling in the header rather than hack
more raw html if I were to go another round.

I'll post the latest once I can see my postings in context with my own newsreader again.


Hello Brengt,

Sorry - I know it was a very terse reply. The state of automatic API
documentation generating tools is not very good in Python. Epydoc is
the best - but *seems* to be unmaintained. Many people find they can't
use it, because it imports code. Your approach of compiling the code
and introspecting the objects seems like the best alternative.

Some people argue against automatic API documentation *anyway* - but if
you write your docstrings intending them to be useful then it can save
a lot of work. However for a medium sized project, something like
Epydoc that shows the relationship between objects and links the doc
pages appropriately, can be very useful.

This is obviously a lot more work than just generating output for a
single modules.

Anyway - it's a subject that comes up regularly, and I haven't looked
into all the issues. There was some discussion on doc-sig about it a
while back.

All the best,
Fuzzy
http://www.voidspace.org.uk/python
Regards,
Bengt Richter


Aug 3 '05 #6
On 1 Aug 2005 06:50:23 -0700, Fuzzyman <fu******@gmail.com> wrote:
This seems to scratch several people's itches.

Has anyone tried this doxygen filter: http://i31www.ira.uka.de/~baas/pydoxy/

I really like doxygen but am not sure if this is worth the trouble.

jw
Aug 3 '05 #7

This discussion thread is closed

Replies have been disabled for this discussion.

Similar topics

1 post views Thread by lawrence | last post: by
1 post views Thread by Thomas Aanensen | last post: by
reply views Thread by Michael Gorski | last post: by
3 posts views Thread by Yammy Hung | last post: by
6 posts views Thread by Eric Lilja | last post: by
By using this site, you agree to our Privacy Policy and Terms of Use.