473,320 Members | 2,071 Online
Bytes | Software Development & Data Engineering Community
Post Job

Home Posts Topics Members FAQ

Join Bytes to post your question to a community of 473,320 software developers and data experts.

Automatic documentation options

I've been trying to use "happydoc" to document a source
tree that I'm working on. It does pretty much what I want,
except:

Version 2.1:
Creates a weird directory structure for the HTML pages
it generates -- they embed the full path to the working
copy of the sources, which, beyond just being ugly,
would be pretty annoying for a collaborative project
(each collaborator's copy would produce documentation
in separate directories, probably resulting in duplication).

Version 3-alpha:
Solves that problem, but very incomplete compared to
2.1, and apparently abandoned in 2003 (maybe because
of pydoc?). Various options aren't available, and, for
example it forces me to use "README.txt" instead of
just "README" if I want it to collect that information.

Neither version documents class attributes, which is somewhat
annoying, because they are part of my interface. But I can fix
this with the docstrings, of course.

Now I've considered using pydoc, but it seems to be very weak
in this kind of application (generating a tree of static HTML pages
to provide library documentation). On the plus side, I find its
overall layout prettier, and it does include attributes.

But it also includes a lot of garbage (such as symbols loaded
by "from pygame.locals import *"), doesn't apparently understand
the structured text docstrings, and finally, it chokes on some
modules because it can't find all of their imports (because I'm
trying to run it from the documentation directory). I don't
think happydoc has this problem, because it doesn't
attempt to import the module in order to generate documentation,
so it only documents what is actually defined in that module. It
also reads comment lines, which can be a plus.

Unlike happydoc, pydoc doesn't seem to have many command
line options for changing any of this behavior, so if you don't like
it, you seem to be stuck.

So while I use pydoc quite a lot for on-the-fly documentation,
I'm not so happy with it as a docset generator (or maybe I just
don't know how to get it to do what I want?).

What I really want to do is to have a set of (static) HTML documentation
pages that I write, that are deep-linked into an automatically
generated set of library documentation.

Any suggestions on getting pydoc, happydoc, or yet another
documentation generator to do this, would be greatly appreciated.

Cheers,
Terry
--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks http://www.anansispaceworks.com

Aug 21 '05 #1
0 1257

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

0
by: Rasmus Fogh | last post by:
Someone raised the question of automatic code generation a few weeks back. And yes, we (CCPN) are using automatic Python code generation in a major way. Basically we are making data models in...
5
by: Abhishek Srivastava | last post by:
Hello All, There is a particular feature which I want to have in visual studio .net suppose I create a class ClassA { private string name; private int age;
1
by: Michel Esber | last post by:
Hello, Linux RedHat AS4 running DB2 V8 FP11. I have followed the docs at http://tinyurl.com/qckrn and enabled automatic statistics collection. It has been 2 days since I updated my DB cfg and...
2
by: ray | last post by:
I have a client that doesn't want Access to automatically repair into a backup file if it crashes (and it crashes only on very rare occasions). My (sketchy) understanding is that this is a...
1
by: Raul | last post by:
This becoming crazy. I have a panelgroup inside with an option. If I change the font to the panelgroup it also changes it to the secondary controls. And I don't want him to make it. I...
4
by: beena | last post by:
All, I'm new to the concept of automatic storage... I'm looking at the database setup by a vendor. I see few tablespaces showing up with automatic storage - Yes. Tablespace ID ...
1
by: Rajen | last post by:
I've a automatic configuration proxy (http://xxx.xxx.xxx.xxx/xyz.pac) which I use in the Internet explorer Lan Settings to access the net. How do I read a webpage by specifying this proxy in my...
0
by: RG | last post by:
I have a stored procedure which is called by db2 "call ....." statement from ksh script. When running from AIX DB2 v. 9.1.3 environment, after a while the stored procedure starts to hang and...
2
by: Denny | last post by:
I'm going from VB.net. Is there a way to have VS automatically add braces to methods? Also in VB, you do not need to add () for a method or function that does not need parameters. Is there a way...
0
by: DolphinDB | last post by:
Tired of spending countless mintues downsampling your data? Look no further! In this article, you’ll learn how to efficiently downsample 6.48 billion high-frequency records to 61 million...
0
isladogs
by: isladogs | last post by:
The next Access Europe meeting will be on Wednesday 6 Mar 2024 starting at 18:00 UK time (6PM UTC) and finishing at about 19:15 (7.15PM). In this month's session, we are pleased to welcome back...
1
isladogs
by: isladogs | last post by:
The next Access Europe meeting will be on Wednesday 6 Mar 2024 starting at 18:00 UK time (6PM UTC) and finishing at about 19:15 (7.15PM). In this month's session, we are pleased to welcome back...
0
by: Vimpel783 | last post by:
Hello! Guys, I found this code on the Internet, but I need to modify it a little. It works well, the problem is this: Data is sent from only one cell, in this case B5, but it is necessary that data...
0
by: jfyes | last post by:
As a hardware engineer, after seeing that CEIWEI recently released a new tool for Modbus RTU Over TCP/UDP filtering and monitoring, I actively went to its official website to take a look. It turned...
1
by: Shællîpôpï 09 | last post by:
If u are using a keypad phone, how do u turn on JavaScript, to access features like WhatsApp, Facebook, Instagram....
0
by: af34tf | last post by:
Hi Guys, I have a domain whose name is BytesLimited.com, and I want to sell it. Does anyone know about platforms that allow me to list my domain in auction for free. Thank you
0
by: Faith0G | last post by:
I am starting a new it consulting business and it's been a while since I setup a new website. Is wordpress still the best web based software for hosting a 5 page website? The webpages will be...
0
isladogs
by: isladogs | last post by:
The next Access Europe User Group meeting will be on Wednesday 3 Apr 2024 starting at 18:00 UK time (6PM UTC+1) and finishing by 19:30 (7.30PM). In this session, we are pleased to welcome former...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.