Setup apigen to generate documentation

Lately I'm working on some extensions to improve my productivity and also add value to my project.
In the process I tried to implement unit test cases for my project and test them using PHPUnit.
One can find information on that on my post here

Now I'm trying to get some automation to make documentation for my project.
Well in general cases it will be mundane task for each successful build.
People who have seen my last post might think that I'm going to blog about phpDocumentor2 but things are different this time.
I have tried more than couple of tools to generate documentation for my project like

1. yiidocsgenerator
2. phpDocumentor
3. phpDocumentor2 (works for basic implementations)
4. apigen (working for me)

You might want to know why I didn't used above tools to get my documentation done
Before that I need to tell you that our project was a mess in terms of standards so no documenting tool is ready to give perfect output. Our mess includes not managing namespaces correctly for user, admin, vendors end.

1. yiidocsgenerator - Gives errors related to multiple declarations of same class in different places. Gives problem if there is a class which extends a base class and it couldn't get it at parsing time.
2. phpDocumentor - Old UI. More info is thrown out at random places. Not intuitive to read documentation. It gives a feeling that we are reading code and not documentation.
3. phpDocumentor2 - Good UI. For basic documenting it works but when we use configuration file then we might land into problems regarding parser, transformer, target directory.
4. apigen - Works flawlessly and has decent UI to get going.

Leaving apart my failures with other documenting tools I will post my success story with apigen here

One can always look at official documentation

Steps to get documentation done

1. Setup/Installation
2. Basic testing of command
3. Generalizing using config file
4. Testing command using config file

Setup/Installation

This command tells that it needs to resolve any dependencies it faces while installing below package
So we don't have the work of setting up all dependeny packages and their channels.

pear config-set auto_discover 1

Install apigen package for documentation

pear install pear.apigen.org/apigen

Basic testing of command

This is a simple execution to prove that this can document our project

apigen.bat --source C:\Users\sampathv.IE\Documents\Projects\<your project>\protected\components --destination C:\Docs\<your project>\apigen\Doc

Check the destination for index.html. See if the documentation is fine. 

Note: Here I'm documenting only components of my project because it is test and it has less files to parse.

Issue: When I executed only for components, documentation was successful but when I tried whole protected folder then there is an issue related to insufficient memory.
The error was asking me to increase my memory allocated to PHP for processing large amount of files.
Solution: So while researching I came to know that I need to change memory related values in php.ini config file. Initially it was 128M for my installation for which I changed to 512M.
For more information regarding how and where to edit please see these links
http://www.hostucan.com/webmaster-tutorials/increase-php-memory-limit
https://groups.google.com/forum/#!forum/apigen

 

 Generalizing process with config file

We can setup our config file using this official documentation and sample config file

When I used information from both links I faced certain problems like

Issue : I faced certain problems regarding skipDocPath parameter too long (more than 260 characters) because I added more than 15 directories to omit while generating documentation.
Well I could able to solve the issue by reducing the overall directories but there is another problem.
The documentor doesn't understand the skipDocPath parameter and it does document all files in specified project path which is not what you want at times.
Solution : Well I'm still looking into this issue. I think the problem is with relative paths and I don't understand how to give those things in windows environment. Everywhere the documentation is given for only linux paths and no documentation for windows.

After a lot of trials and tinkering with NEON Parser I could able to build some config file for my own project and you can find it here

Note : This is the first time I'm dealing with Git so if any users not able to view the file please comment and I will try to provide it by other means. Please change necessary locations in config.neon to your environment.

Testing command using config file

apigen.bat --config .\config.neon

After the command completes open up index.html page and check if that is what you intended.

Note : I executed the command from the directory where config.neon exists. Make sure you too do that.