[Zope-dev] New Help System in 2.2

[Jimmie Houchin]

I too agree the new help system looks nice.

I was considering at one point jumping up and writing a documentation
system for Python/Zope. Unfortunately my notes, not many, are at work.
But some things I had in mind were based on something like JavaDoc. I am
not a Java expert and have not really used JavaDoc much but have seen
some of its documentation.

I was thinking it would be nice to have a parser which could extract
documentation from source to create external documentation files which
could be generated into multiple formats, html, xml, etc. I would have
needed to create a documentation format which could be used in source
but extracted. I was not going to use docstrings as they are intended
for a different purpose and are compiled into the bytecode.

I was thinking that the parser could run over a module and extract
functions, methods, variables and properties, etc. and create a stub
framework on a form. A documenter could then edit documentation for any
or all of the methods, save and it would be inserted appropriately into
source.

I thought it would also be nice if the documentation tree would also
parallel the source tree and have a corresponding colorized html
rendering of the module for browsing. This way one could jump from
documentation to source at will.

I was basically making idea notes. I was going to look at the current
doc generating and py2html tools available first. Then Starship went
down and I couldn't access them. :(

I also wanted to see what the DC team was doing.

I think it would be nice to see some ideas and processes for what and
how Amos and Michel are doing with the documentation and how the
community can help.

Just some thoughts.

Jimmie Houchin


Jason Spisak wrote:
> 
> Shane Hathaway writes:
> 
> > Jason Spisak wrote:
> > > I was just browsing the help system and can I just say it is terrfic.  The
> > > .py files especially.  Not that python isn't that easy to read, but having
> > > the ZQR type stuff handy online is a huge win.  Is that stuff updated from
> > > the source on the fly?
> >
> > Almost.  It's actually written in separate files that mirror the
> > structure of the real source.  And I'd like to bring up the point that
> > I wonder why it is written that way.  Wouldn't it make more sense to
> > self-document the source?
> >
> > If the issue is that some methods shouldn't be callable from a URL,
> > there are better solutions to that problem (this is written to DC
> > mainly):
> 
> Is this the reason that it's not pulling the docs from the source?
> That's not a good idea.  With all the effort that Michel put in to work
> around not documenting in the source, he could have fixed it so that it
> pulled the docs from the source on the fly without effecting the URL
> access.
> 
> > 1) Enahnce the permissions system to include "Accessible via HTTP",
> > "Accessible via FTP", etc.
> > 2) Use an underscore as the first character of a docstring to indicate
> > a non-URL-callable method.
> >
> 
> I just looked at it and that seems like doing work twice.  Why not just
> document your source?
> 
> Wonderingly,
> 
> Jason Spisak
> CIO
> HireTechs.com
> 6151 West Century Boulevard
> Suite 900
> Los Angeles, CA 90045
> P. 310.665.3444
> F. 310.665.3544
> 
> Under US Code Title 47, Sec.227(b)(1)(C), Sec.227(a)(2)(B) This email
> address may not be added to any commercial mail list with out my
> permission.  Violation of my privacy with advertising or SPAM will
> result in a suit for a MINIMUM of $500 damages/incident, $1500 for
> repeats.
> 
> _______________________________________________
> Zope-Dev maillist  -  Zope-Dev@zope.org
> http://lists.zope.org/mailman/listinfo/zope-dev
> **  No cross posts or HTML encoding!  **
> (Related lists -
>  http://lists.zope.org/mailman/listinfo/zope-announce
>  http://lists.zope.org/mailman/listinfo/zope )