Laser Docgen

Expandable documentation generator for PHP applications.

Authors:

• Tomáš Vojík vojik@wboy.cz

Intro (motivation):

Documentation is a much-needed part of programming. Although I always struggled to find time to write some meaningful texts about the projects I was currently working on, I at least dedicated a time to write some comments in the code and generate an automatic API documentation for it using Doxygen (I have tried different solutions such as PHPdocumentor).

It was OK. However, it never looked as good as I would hope and the setup for each app was either a copy-paste of the config file, or a slightly longer setup through the Doxygen app. I really liked that it can read the code, parse it and spit out some useful information as the descriptions and even class and collaboration diagrams. I even used the possibility to define Markdown files that will be parsed and included as new pages that can have some other information.

But I wanted more...

I set out a path to create a tool for myself (and possibly others) to use to generate most of the necessary documentation for PHP projects. It should be easy to use and extendable by third-party plugins (for example a specific PHP framework support to generate more useful information).

The second reason to build such a project is that I like to build stuff myself. It may sound silly to some, but I am the kind of programmer who rather than learning some open-source framework to build an app, I would build my own, just for the joy of creating something myself. That doesn't necessarily mean I build every project on a completely custom codebase.

Plan:

1. Basic parser using mostly the PHP's reflection API to create some kind of structural representation of all the application's components.
2. Using the structural information extracted from the code to generate simple output in different formats (at least HTML).
3. Second-pass analyzer to detect dependencies, function calls, framework specific configurations (such as custom attributes), etc.
4. Generating graphs from analyzed data (probably dot)
5. Possibility to create a "wiki" - using markdown files
6. Optimizations

Some key points to keep in mind

• Output of each step should somehow be cachable => generate a data structure that can be parsed and updated if source files changed (= each file will have other files as dependencies)
• All templates should be over-writable and the overall design should be customizable (latte templates)
• All configuration should be stored in one file (neon)
• Each step should be expandable by creating classes that process the information like a chain.
  • Every step will go through the initialization faze and then pass through multiple analyzers (the classes that expand the functionality)
  • Every analyzer should only update the working data structure representing the code information
  • Allowed plugins should be installable by composer and should only need to be added to the configuration NEON file
  • Maybe some DI could be used to allow more complex functions
• The documentation for this project must be generated by this project as a test

Future good to have features

Most of these should be probably created as plugins.

• PhpUnit integration = coverage report (HTML) generation + test results
• My Laser framework integration
• Docker implementation API (run from docker container)
• Different doc themes