Ever since I discovered phpDocumentor I have been fascinated by the idea of automatic Documentation Generation. Especially for large projects where an in-depth understanding of the code is a requirement.
Unfortunately, the more I got to work with phpDocumentor the more issues surfaced with its performance, ease of use and above all: memory usage.
Over time I have encountered at least 1 project which could not be processed by phpDocumentor. This was unfortunate and thus I decided to try and contribute to the phpDocumentor project. After a pleasant introduction and solving a minor bug I attempted to solve, or at least decrease, the memory usage issues which were the main cause of my dissatisfaction.
Long story short: I gave up.
Although the application can work magic for some projects, I was unable to adapt the code base (which is reasonable old). The memory issues seemed to be partly due to the architecture of the application and the choices in the past. To change this would mean a rather large refactoring of the application.
Enter DocBlox
Right before or during the Dutch PHP Conference 2010 the issue had arisen again and this time I was determined on solving it. In the end I chose to build a new Documentation Generation Application (may I coin DGA?) for PHP for which I had the following spear points in mind:
- Execution duration had to be as short as possible.
- Memory usage should at all times be within an acceptable range (less than 100mb).
- Focus on assisting Continuous Integration.
- Compatible with the latest PHP versions.
- Compatible with the basic phpDocumentor CLI arguments.
- Aid the user with Ajax enabled search and more.
With these requirements written down in a small TODO file I started designing the new project (which at the time was still nameless).
After spending some hours designing, coding, prototyping, designing, coding and testing is now the time to reveal the fruits of my labour: DocBlox
State
Currently DocBlox is still in an pre-release state (version 0.7.1) but is well underway to version 1.0. Even though I have marked this version as being pre-release, it is fully capable of parsing your source code and creating static HTML pages (PDF support is planned for the near future).
Features
DocBlox sports many features which help you reading the documentation hidden in your source code. Please take a look at https://github.com/mvriel/Docblox/wiki/Features for an overview!
Conclusion and where to get it
DocBlox is a new, versatile Documentation Generation Application (DGA) which enables large and / or PHP 5.3 projects to generate their documentation. It is compatible with many of the features that you are used to in other DGA’s.
You can get the source files from GitHub at: https://github.com/mvriel/Docblox
Some documentation is also available at Github; but most is still under development. You can check the README, TODO and CHANGELOG in the project to see how to use the application and what is on the roadmap.
Try it and I hope you like it.
Either way, thank you and let me know!
Awesome! I’ve been very unsatisfied with the state of DGA’s in the PHP world. PHPDocumentor, Doxygen, etc have had major limitations. I look forward to testing Docblox with my hudson install.
Nice job, the community will suppot your project even more as soon as the project is integrated with phpundercontrol and jenkins
Thank you, it works great and really is blazingly fast. I was wondering, are there any more themes available? It would be awesome to have a php.net like theme or something, the now available themes are a bit unclear.
Keep up the good work!
@seth: I have not had the chance to test it with Hudson; though the basic command line arguments are equal to phpDocumentor. Please let me know how that fares!
@Dvdende: that would be a dream of mine; to have DocBlox available in phpUnderControl and Jenkins. Currently I am focusing my efforts on more features so that DocBlox will be fully compatible with phpDocumentor and the switch does not change anything for the user.
@Sjoerd: currently not. but the themes are XSLT transformations; thus if you’d like to create one you are free to do so 😉
I plan to support other theming options as well in the future (twig?) but other items have priority currently.
Great job! Ever since 5.3 was released, PHP API documentation has had a real void.
I tried Docblox out on a project of mine, and it did a nice job. I know you said it’s a preview release, but here are a few suggestions:
1. Not all of my class associations were linked correctly. I think it isn’t picking up my “use” statements in my classes. When you “use” something, you should be able to reference it in a docblock without having to give the full path. (e.g. “@param MyClass $c” vs “@param NamespacePart2MyClass $c”
2. Support {@inheritdoc}
3. The image that shows the class map didn’t pick up any of my class hierarchies except for my exception classes.
4. When finished, I think Docblox would be a perfect use case for being distributed as a Phar file. I’d suggest making it easy to install by distributing it with Pyrus.
Default theme UI:
1. Remove the Docblox logo from the default template. Instead use “Generate by Docblox” or some other equivalent text at the bottom of each documented page.
2. Use a two column layout instead of a three column layout.
3. Use a standard tree view. There doesn’t need to be a brief description of each class in the hierarchy. Maybe you could should that on hover with a title attribute?
4. Don’t center the search box. Left align.
@Dvdende: I don’t think you integrate Docblox with a CI server, you integrate Docblox with a build system like Phing and then run phing tasks from within your CI server. You could do that right now by just executing the script using the exec Phing task: http://phing.info/docs/guide/current/chapters/appendixes/AppendixB-CoreTasks.html#ExecTask
@Michael Great feedback! I really appreciate the comments that you have made. Allow me to elaborate on them:
1. The T_USE token is currently not supported by DocBlox; it is on the roadmap for inclusion but it poses some challenges as I need to process it after indexing all classes (since a class coming from a T_USE could exist in multiple namespaces.
It will be included, do not worry.
2. Inline tags are also still unsupported; I am currently using a component from Zend Framework to parse the docblocks and it does not recognize these. I am planning on building this support (and fixing some minor annoyances at the same time).
3. I’ll look into it; thank you.
4. I am researching what is necessary for it to be easily installable; whether that be PEAR’s own repository, my own Pyrus server or something else. If I were to use phar, it would not be the only option as phar is 5.3+ and I try to support 5.2.1+ for as long as possible.
Concerning the theme suggestions: although this theme is the second that I have created, it is by no means final and I might change composition entirely based on UX feedback. You are the first to provide such feedback and I will definitely keep your suggestion in mind during development! (Concrete: I might or might not change it soon; my first priority is on (new) bug-free features)
Hi,
I’m going to test this with jenkins..
Nice Work, i like it 🙂
A little Problem: The linebreak in the description is escaped as & lt ;br/& gt ;
Just out of curiosity, have you tried Doxygen? Any thoughts on that?
As for phpDocumenter, the project looks kind of dead (last release was 2008).
As we need something like ths at the company I am currently working for I might get on board in supporting you great effort! 😉
@Malte: I am curious what results you have? In the mean time I have altered DocBlox to play nice with Jenkins and even have one running using DocBlox as documentation generator (will try to do a blog post about that)
@Christian: that should be fixed by now. If you still encounter issues with that: please let me know on github (http://www.github.com/mvriel/docblox) with an example Docblock.
@Potherca: To be honest; I must admit that I have only briefly looked at Doxygen and based on what I saw, the feature list and feedback from several people in the community I decided not to work with it. Please let me know what you encounter (as you actually already had on Github ;)) and if you require any assistance.
There is an IRC channel on freenode called #docblox where I am quite regularly.
@mvriel: Do you plan to create a pear channel / package to be able to serve this up? It would be very beneficial to those of us that utilize PEAR for installing such packages.
You could easily do this through Pirum 🙂
@mike: actually, there is already a PEAR channel. I am now in the final stages of making sure that the invocation of DocBlox from an arbitrary location works. I expect to announce full support this evening.
If you’d like to know as soon as possible; there is a @DocBlox account on twitter where I regularly post updates on DocBlox’ progress.
I have chosen Docblox for my current project, and am in love! Would you be interested in working on an HTML interface design (a la PHP Documentor?). I don’t have tons of free time, but perhaps I could find some for this.