Posted on

ApiGen versus phpDoc

So last night I went down the path of connecting phpDocumentor2 (phpDoc) to my code so I can find key elements in the classes and objects without having to search through the code editor. That works fine, but it is often faster for me to have an index of the classes, methods, and properties in a browser window. Even better, by publishing on the public CSA site I know can use Google to search my own docs. That is a nice bonus.

This morning, while researching custom templates, I came across a competing tool that threatened derailment of my phpDoc efforts. I came across comments that phpDoc was inferior, not updated, and had poor documentation. The project had been ignored for a few years. Turns out that much of that has been addressed since the phpDoc efforts have continued once again, though there are still plenty of gaps in the documentation of the phpDocumentor2 tool kit. After a brief run with ApiGen, I am back on the phpDoc trail.

Official Website

I was a bit apprehensive about ApiGen from the start. Why? The official website for ApiGen seems less polished than the phpDoc site. If they can’t make a great first impression on their website, what are the chances they can create decent HTML docs from my code comments? Turns out I liked the generated HTML better than their website. While phpDoc does have holes in their website presentation as far as features sets, command line options, etc. It is easier to find what I am looking for and seems to have much more documentation online than ApiGen. Maybe ApiGen has more documentation, but if it is not easy to find that doesn’t make me more efficient.

Winner: phpDoc

Installation

The installation of both products was about the same.   Use pear to setup a remote archive, and run pear to install the product.    However there was one or two fewer steps in installing phpDoc over ApiGen.   The big difference, however, was the facilitators required by ApiGen versus phpDoc.  phpDoc required far fewer libraries and add-on packs than ApiGen and produces better results.    phpDoc is either utilizing more of my CentOS 6 default PHP libraries or it just needs less in the “other frameworks” department to accomplish a similar goal.

Winner: phpDoc

NetBeans Integration

As for the NetBeans integration, they are both fairly similar.  Neither option functions very differently from the other.   They both need a target output directory set.  However, for some reason ApiGen requires you to locate the full path to the executable.  phpDoc just automatically worked.  Slight advantage: phpDoc.

Winner: phpDoc

Generated Site : Weight

This is one place where I think ApiGen wins out.  The overall “weight” of the produced site for the code documentation has less stuff to push around to and from the public server.  That also means that the stuff the pages have to load when people are viewing the site is less.   However I think there is a trade off on quality and possibly mobile-aware presentation.   Based on sheer “bits and bytes” to get the page online, ApiGen is lighter.

Winner: ApiGen

Generated Site : Quality

While I do like the search feature of ApiGen, I quickly discovered it is not a general “search any word” type of search we all are accustomed to on any site.  It is more of a “type a few characters and find a class name” search.  At least out of the box that is how it seems to be configured.   So while the search feature seemed like a plus, it really isn’t that useful to me.     Overall the look and feel plus ease of navigation of the phpDoc generate site works better for me.

Winner: phpDoc

Summary

Overall, I found phpDoc to be the best option at this point.   ApiGen isn’t bad, but today phpDoc edges out ApiGen in the areas that matter most to me.

You can compare the results of my simple Tagalong test here:

Tagalong Code Docs from ApiGen

Tagalong Code Docs from phpDoc

Posted on

Making GitHub Wiki Docs From PHP Source

I’ve been using NetBeans to write my PHP-based WordPress plugins and have found that well crafted PHPDoc comments make a notable difference in the efficiency of my coding.   I’ve written a post-or-two about that and find the auto-fill features to be very helpful.    I have also noticed that much of the WordPress core also follows PHPDoc conventions, so using PHPDoc is a good way to comment your WordPress plugin code IMO.

The other tools I use frequently are GitHub with SmartGit.   While git had a steeper learning curve than subversion, I much prefer the lighter “differential data” standard of git as well as the distributed repository concept.   Both just “feel” smarter.   The next logical step from tracking code commits and issues with GitHub was finding a home for my code documentation.     I really didn’t want to manually great web pages from the PHDoc raw HTML.  I also didn’t want to write a plugin to read PHPDoc to get the content into my website, so I went on a quest to find the tools needed to publish my PHP comments right on the GitHub wiki pages.    After a long search I finally found the pieces of the puzzle I needed to go from PHP comments to GitHub wiki pages with limited effort.  The process is outlined below.

Clone Your GitHub Wiki Pages

  • Go to your GitHub project and look for the Wiki tab. If you do not have it, especially for an older project, you may need to enable “pages” in the repo settings at GitHub.
  • Under the Wiki tab is a sub-tab for “Git Access”. It has the WIKI repo URL, which will automatically be attached to the parent project under the wiki tab.
  • Clone this to a new directory on your dev box.
  • (BTW, this step is optional, this is just how I opted to do this, keep the docs OUT of my main code repo).

Setup/Build The PHPDocMD Tool

$docmdDir = dirname(<strong>FILE</strong>);
set_include_path(get_include_path().PATH_SEPARATOR.$docmdDir.'/../src/Twig/lib');
// Potential composer autoloader paths $paths = array( $docmdDir . '/../src/PHPDocMD/Parser.php', $docmdDir . '/../src/PHPDocMD/Generator.php', $docmdDir . '/../src/Twig/lib/Twig/Autoloader.php', );
foreach($paths as $path) { if (file_exists($path)) { include $path; print "including $path\n"; } }
Twig_Autoloader::register();
// Everts crappy option parser.

These code edits are necessary because the tool is not refined yet. It was clearly setup for the developer’s system which has Twig installed and a vendor autoloader file that is not in the git repo. Not a big deal, easy enough to get around if you follow the steps here.

BTW, that last comment is his, not mine. I left if there so you know where to stop the edit.

Use PhpDoc & PHPDocMD

You may want to symlink that phpdocmd to your /usr/bin directory so you don’t have to type the full path every time, but now you just need a few steps to create GitHub Wiki compatible doc files:

# phpdoc -t . -d .

That creates the structure.xml file needed to generate the MD files.

Then run this command:

# phpdocmd ./structure.xml <path to your github WIKI project>

Now your GitHub Wiki Docs project should be full of MD files that reflect your code PHPDocs. Just push your GitHub Wiki files back to the GitHub server.

Posted on

Word 2007 Blank Pages Between Chapters

While working on a documentation project for a client we ran into a unique problem.  According to good technical writing practices, you always want chapters to start on an odd page.  This puts new chapters on the right-hand page of a bound book.  You also want to ensure that any preceding blank page is not 100% blank, most standards dictate at least a footer with a page number and possibly a header with the title of the prior chapter (old school methods were to put a “This page intentionally left blank.” message on the preceding blank page, which is one of my favorite all time ironies).  After digging around for hours (OK, maybe 10 minutes) I found the solution to this blank page problem.

It turns out that when you are forcing pages to start on an odd page # for things like a chapter to always appear on the right side of a bound book, you end up with blank pages preceding some of those pages.  That is just how Word works.  If your previous chapter ends on an odd page, it automatically inserts the blank so that the new chapter starts on the odd page as well.   However, it is clearly documented that Word does not put ANYTHING on that page, not even headers or footers.  There is not setting that says “carry headers/footers over to blank pages”.

The official Microsoft solution… use the hard page break, CTRL-ENTER just before the odd-page-break whenever you want to force Word to insert the header/footer on the blank page.

http://support.microsoft.com/kb/264905

The problem with that solution?  If your document changes the CTRL-ENTER will force a new page ALWAYS.  If your existing work is updated and the prior chapter now pushes up from ending on an odd page to ending on an even page, guess what?   You get TWO BLANK PAGES… one with a footer (the forced blank page) that is now an odd page # with a footer, and an even page with NOTHING… the exact problem you were trying to solve the first go-around.

Bottom line, to get technical documentation standard page footers AND chapters starting on the right-hand page, you will constantly need to scan & manually revise the page breaks in the document every time you update the content, especially if you lengthen any chapter.

Wonderful.  Thanks Microsoft, thank you very much.  Why even provide “odd page break”?  Might as well keep things simple and force 100% manual management of pages with CTRL-ENTER throughout.   Grrrrr… sometimes working with these high tech tools can be so aggravating.     20+ years of MS-Word development and they still don’t have an elegant solution for this common problem.  It was even documented as far back as 2000 and Microsoft had enough inquiries to have written TWO knowledgebase articles about it back then.

Posted on

Easy Documentation for Git, MySQL, PHP, et cetera

This is what I do on my box to quickly find documentation, which you guys may find helpful.  Especially those of you on Linux—although you could do this on Windows too.

Most package managers make available ‘-doc’ packages, like php-doc, mysql-doc, and so on.  Install these for all the major software you use.

Next, install ‘screen’.

Now put this is your Bash config:

# Displays various types of documentation.

function doc() {
    case "$1" in
    'llvm')
        screen -t 'LLVM Documentation' w3m /usr/share/doc/llvm-doc/html/index.html ;;
    'erlang')
        screen -t 'Erlang Documentation' firefox /usr/share/doc/erlang-doc-html/html/doc/index.html ;;
    'python')
        screen -t 'Python Documentation' w3m /usr/share/doc/python3-doc/html/index.html ;;
    'php')
        screen -t 'PHP Documentation' w3m /usr/share/doc/php-doc/html/index.html ;;
    'ghc')
        firefox /usr/share/doc/ghc6-doc/index.html & ;;
    'postgresql')
        screen -t 'PostgreSQL Documentation' w3m /usr/share/doc/postgresql-doc-8.4/html/index.html ;;
    'mysql')
        screen -t 'MySQL Documentation' w3m /usr/share/doc/mysql-doc-5.0/refman-5.0-en.html-chapter/index.html ;;
    'apache')
        screen -t 'Apache Documentation' w3m /usr/share/doc/apache2-doc/manual/index.html ;;
    'j')
        screen -t 'J Documentation' w3m ~/Software/j602/help/index.htm ;;
    'lua')
        screen -t 'Lua Documentation' w3m /usr/share/doc/lua5.1-doc/doc/index.html ;;
    'git')
        screen -t 'Git Documentation' w3m /usr/local/share/doc/git-doc/index.html ;;
    'lighttpd')
        screen -t 'Lighttpd Documentation' w3m /usr/share/doc/lighttpd-doc/ ;;
    'plt-scheme')
        screen -t 'PLT Scheme Documentation' w3m /usr/share/plt/doc/index.html ;;
    'gambit')
        screen -t 'Gambit Documentation' w3m /usr/share/doc/gambit-doc/html/index.html ;;
    'tintin++')
        screen -t 'TinTin++ Documentation' zless /usr/share/doc/tintin++/tintin19.txt.gz ;;
    'sqlite')
        screen -t 'SQLite Documentation' w3m /usr/share/doc/sqlite3-doc/index.html ;;
    'django')
        screen -t 'Django Documentation' w3m /usr/share/doc/python-django-doc/html/index.html ;;
    'sbcl')
        screen -t 'SBCL Documentation' w3m /usr/share/doc/sbcl-doc/html/index.html ;;
    'boost')
        screen -t 'Boost Documentation' w3m /usr/share/doc/libboost-doc/HTML/index.htm ;;
    'smalltalk')
        screen -t 'GNU Smalltalk Documentation' info Smalltalk  ;;
    'haskell-tutorial')
        screen -t 'Haskell 98 Tutorial' w3m /usr/share/doc/haskell98-tutorial/html/index.html ;;
    'haskell-report')
        screen -t 'Haskell 98 Report' w3m /usr/share/doc/haskell98-report/html/index.html ;;
    'java')
        firefox "/home/eric/Documents/Books/Programming/Java SDK/index.html" & ;;
    esac
}

Replace ‘w3m’ with the browser you want to use.  And make sure the paths are correct.  If you’re on a Debian-based box, that’s where those doc packages will end up.

Now whenever you’re at the terminal you can simply run stuff like

$ doc git
$ doc postgresql

to browse through the official docs.

For Git in particular you will have to build the HTML docs.  In the Git source directory:

$ make html
$ sudo make install-html

There ya go, easy way to look up docs quickly.