Beefy Boxes and Bandwidth Generously Provided by pair Networks Bob
Just another Perl shrine
 
PerlMonks  

documentation generator? web-enabled perldoc?

by geektron (Curate)
on Aug 06, 2004 at 21:37 UTC ( #380734=perlquestion: print w/ replies, xml ) Need Help??
geektron has asked for the wisdom of the Perl Monks concerning the following question:

i've been tasked with creating a documentation base for our (currently *undocumented* -- not even good comments or self-documenting code ) primary application. an easy thing to do (once i have a full handle on the code in all its intricacies and weaving around and ... ) and a good way to really know the guts of the application.

thing is, the PHB wants to have a 'searchable, web-enabled' documentation repository ( think something *like* cvsweb or doxygen )

for those that haven't seen doxygen, i found it when reading through the drupal CMS site. it's some form of documentation generator (at the very least, it generates HTML docs like javadoc).

i don't remember seeing anything like, say, doxygen or javadoc for perl. if there's such a thing out there, i'd love to use it and not re-invent a wheel. even for the 'learning experiene' on this one -- documenting the code should be my primary concern, not reinventing an HTML page generation app.

if there *isn't* something like these out there, i do think i'll see about getting on the doxygen team to make the doodad work with perl.

so, do the rest of you think there's an equivalent out there? or am i gonna jump into an open-source programming team?

Comment on documentation generator? web-enabled perldoc?
Re: documentation generator? web-enabled perldoc?
by sgifford (Prior) on Aug 06, 2004 at 21:46 UTC
    The standard for Perl is POD, Plain Old Documentation. See the perlpod manpage that came with Perl. You can use pod2html to turn it into HTML, or various other pod2x programs to turn it into something else.
      yes, i'm aware that the standard is POD. there is more to documentation, or *can* be more to documentation, than POD.

        Perhaps you can describe what features POD is missing that you need, for those of us who aren't familiar with doxygen and friends?

Re: documentation generator? web-enabled perldoc?
by kvale (Monsignor) on Aug 06, 2004 at 21:50 UTC
    I am not familiar with doxygen or javadoc, but Pod is easy enough to convert to HTML.

    My guess it that doxygen or javadoc do some sort of static source code analysis as well? Such a thing is hard to do well in perl, as variables and methods can be created dynamically at runtime using eval. The perl profiler has the ability to display the function call tree after a run, which may provide a start in developing a hierarchical search structure.

    Update: fixed a typo.

    -Mark

Re: documentation generator? web-enabled perldoc?
by saberworks (Curate) on Aug 06, 2004 at 22:50 UTC
    I asked a similar question in the chatterbox when I took on a large project, and I was also dismayed at the responses.

    I think what we are looking for is a nice, standard way to document functions, modules, classes, and files. I'm not talking about the quality of documentation on most perl modules in CPAN (at least most of the ones I've used so far). I'm talking about an "allowed" argument list for each function, the return value, what it's used for, etc. You can surely document those in POD, but if you come up with a standard way of doing it (like, specifying that the first argument should be an integer, the second an array reference, and the third a string), you can use a source code analyzer or something to print pretty HTML docs similar to PHPDOC or JAVADOC.

    Of course as mentioned above, perl allows you to create functions that don't actually exist anywhere in source code, so you have to find some way to document those as well.

    I actually didn't find a good solution, so I'm just writing it all in POD with plain text and nice formatting.
Re: documentation generator? web-enabled perldoc?
by Anonymous Monk on Aug 07, 2004 at 04:09 UTC

    Rather than modifying doxygen, (if POD doesn't work for you) and idea could be to work from RDoc (Ruby Doc). You can find it at http://rdoc.sourceforge.net/ I only suggest it over doxygen since it is for a more dynamic lanaguage (like perl). Either way it is going to be a great dela of work.

Re: documentation generator? web-enabled perldoc?
by toma (Vicar) on Aug 07, 2004 at 04:11 UTC
    Check out Pod::Webserver. It scans the perl installation and runs a web server which serves pod formatted as HTML.

    I also use a simple script to create a syntax-highlighted source code listings and an index page. It uses gvim to make syntax-highlighted listings in HTML. I wrote a little script to create these highlighted listings in a batch mode. The script also makes an index page. It runs so slowly that when the first file being processed was large, I was fooled into thinking it was broken!

    There are several ongoing projects that are relevant. TheDamian is working on something a bit like JavaDoc. It parses specially formatted comments and turns them into documentation. I don't have the details handy, but I can post a few notes later if there is interest.

    There is at least one perl refactoring tool in the works, but it is still in the research phase. To work properly it must parse perl itself, which is properly understood as a very hard problem. I have seen this tool handle subs and packages and draw depedency diagrams. This was demonstrated (in part) by MikeZone at a Sonoma.pm Mongers meeting.

    It should work perfectly the first time! - toma
      POD::Webserver is closer to what i need to have as an end result.

      in the words of the PHB: "It must be searchable". i keep trying to get him to calm down, that we need content before content can be searchable.

      I'd like to see what TheDamian is working on. maybe i should ping him and see if there's interest in collaboration. working on anything withy him would be an invaluable learning experience (and cheaper than hallucinogenic drugs!)

Perl::Doc
by adamk (Chaplain) on Aug 07, 2004 at 06:26 UTC
    OK, so it doesn't exist yet, but on of the stated goals of the PPI module (the perl document parser) is to be able to provide source code analysis tools.

    If anyone is interested in the subject, and helping to write Perl::Doc, I would love to hear from them. PPI is finally starting to stabilise, so now would probably be a good time to kick off Perl::Doc. There may also be some alignment with CPANXR the CPAN cross reference.
      well, i just might be interested. i need to be doing something similar, so i'll read up on the goals, and get with you (or the author if it's not you). i've always wanted to contribute to CPAN, to give something back, but every time i thought i found a need more searching of CPAN showed me that someone already did it!
Re: documentation generator? web-enabled perldoc?
by PodMaster (Abbot) on Aug 07, 2004 at 08:47 UTC
    doxygen parses sourcecode to determine constants, function signatures, etc.. function signature won't work for perl (as i'm sure you realize).

    doxygen includes hyperlinked syntaxt hilighted sourcecode in its output, and there is no reason you couldn't do that with perl other than its of little use most of the time (and parsing perl is hard).

    doxygen links all function references to the function documentation, and there's no reason a pod translator couldn't do that (in fact Pod::Html tries to resolve those when possible).

    Anyway, here is something other than just pod:

    Anyway, perl's only issue with pod (besides the fact that L<blah blah|http://some.url/> isn't legal yet), is that there aren't many tools (like doxygen) to generate pod from raw source (as much is possible) for module writers (module users shouldn't need to deal with such tools).

    BTW - I like pod :)

    MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"
    I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).
    ** The third rule of perl club is a statement of fact: pod is sexy.

      yes, i think we all know how you feel about POD. ;-)

      i've thought of something like POD on steroids. pod2html is a nice start for web-enabling the whole thing, and some kind of (ack!) custom parser could generate the meta-data to shove info into a database and "make it searchable" (so could something like htdig, but i worry about false positive and things like that just from a full-text search ).

      i like POD, but POD does have its limitations. one of the main limitiations being that any 'cross-references' (like function Foo::bar called by package Bar::baz ) has to be done by hand. for an undocumented application that's sliced way too thin ... that's going to be a nightmare.

      ( the app author seriously has modules like:
      Application::Mailer::Mailer::SendMail
      which does NOTHING but accept a stringified MIME::Lite message ( from  $obj->as_string() ), open a SENDMAIL pipe, and print to that pipe. i don't know about everyone else, but that's a bit too sliced for my taste.

Re: documentation generator? web-enabled perldoc?
by Arrowhead (Monk) on Aug 07, 2004 at 19:49 UTC

    I wrote a filter for doxygen so it could be used on perl code with suitable comments.

    See http://smop.org/computing/perl/doxygen.html

    It really helps if you know C++ when using it, because the comments you have to place in front of your code are basically a translation from perl to C++ function prototypes.

    Take a look at the generated demo docs, at the source perl code and decide whether it's sufficiently "better" for you than POD.

    For most perl code, I think POD wins, but DoxyGen::Filter could be useful if you program in a heavy OO, java-like style.

Re: documentation generator? web-enabled perldoc?
by graff (Chancellor) on Aug 08, 2004 at 02:46 UTC
    I don't know if this will help, but someone posted a question about analyzing a complicated (undocumented) set of inter-related perl files, and I was compelled to try my hand at it. The result is here: Tabulate sub defs, sub calls in Perl code.

    You just give it a list of perl source code file names, and it gives you a fairly tidy listing of sub definitions by source file, and where various subs are called (which might be a good-enough starting point for standardized documentation). HTH.

pdoc - kind of like doxygen
by PodMaster (Abbot) on Aug 15, 2004 at 11:21 UTC
    I was just browsing kwiki.org, and ran accross pdoc. The html (colorscheme) it generates is butt ugly, but it does do the auto-cross-linking/source-including feature you want. Check it out:

    UPDATE: Here's a patch for pdoc-1.0.tar.gz which will stop perlmod2www.pl from dying in the emiddle of its run.

    --- Pdoc/Html/Renderers/PerlModule.pm 2004-08-15 04:47:10.359375000 + -0700 +++ pdoc-1.0/Pdoc/Html/Renderers/PerlModule.pm 2002-03-15 09:42:54. +000000000 -0800 @@ -792,7 +792,7 @@ print $fpt '<TR><TD>&nbsp;+&nbsp;<B>', $sub, '</B></T +D>'; # Got associated POD too? - if (eval{$subObj->get('pod')}) { + if ($subObj->get('pod')) { print $fpt '<TD><A HREF="#_begpod', $begPod, '">D +escription</A></TD>'; $begPod++; } else { @@ -831,7 +831,7 @@ '<TD>'; # If doc - if (eval{$sub->get('pod')}) { + if ($sub->get('pod')) { print $fpt '<A HREF="#POD', $podPos, '">Description</ +A>'; $podPos++; } else { @@ -903,7 +903,7 @@ # Write POD related to routines in BEGIN statement foreach my $sub (@{$entry->get('subroutines')}) { my $subObj = $begins->fetch('PerlSub',$sub); - my $pod = eval {$subObj->get('pod')}; + my $pod = $subObj->get('pod'); $begCode++; next if (! $pod); @@ -954,7 +954,7 @@ # Write routines doc foreach my $entry (@sorted) { my $sub = $subroutines->fetch('PerlSub', $entry); - my $pod = eval{$sub->get('pod')}; + my $pod = $sub->get('pod'); $subPos++; next if (! $pod); @@ -1053,9 +1053,9 @@ print $fpt '<TABLE BORDER="0" WIDTH="100%" CELLSPACING="0 +">', "\n", '<TR BGCOLOR="', $_config->{'subcode'}, '"><TD WIDTH="200"><A NAME="CODE', $subPos, '"></A>', - '<B>',eval{$sub->name()}||'noname', '</B></TD> +'; + '<B>', $sub->name(), '</B></TD>'; - my $pod = eval{$sub->get('pod')}; + my $pod = $sub->get('pod'); if ($pod) { print $fpt '<TD><A HREF="#POD', $podPos, '">descripti +on</A></TD>'; $podPos++; @@ -1077,7 +1077,7 @@ print $fpt '</TR></TABLE>', "\n"; # Subroutine content - print $fpt eval{$sub->converted()}, "<BR>\n"; + print $fpt $sub->converted(), "<BR>\n"; $subPos++; }

    MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"
    I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).
    ** The third rule of perl club is a statement of fact: pod is sexy.

      Hi, The latest version of Pdoc is actually available on the SourceForge CVS repository: http://sourceforge.net/cvs/?group_id=42096 Checkout the pdoc-live module and use the pdoc-live/scripts/perlmod2www.pl script. Example of application: http://doc.bioperl.org/releases/bioperl-1.5.2/ I need to find some time to update the web site and the SF project. Hopefully soon... Cheers, Raphael
Re: documentation generator? web-enabled perldoc?
by jaa (Friar) on Jun 03, 2009 at 07:19 UTC

    A perennial question... auto-generated documentation for Perl that enables exploration of the structure of an application, rather than the simple documentation of a single module...

    I am toying with http://www.naturaldocs.org which seems to work well for Perl... and its "keyword : token" comments look nice in many languages . It's also packaged for Debian stable(lenny) hoorah!

    We also need Javascript, PHP etc - the PHP support is minimal, but the generator is written in Perl...

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://380734]
Approved by sgifford
Front-paged by saberworks
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (6)
As of 2014-04-16 11:00 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    April first is:







    Results (424 votes), past polls