Php : Easy Documentation Generator

Background

We all been there, and probably me first. When creating codes, the documentation consist most of the time by the comments in the codes ... *sic*

For small projects by couple of hundreds lines this is ok but when your project start to hits some 10 thousand lines, this is becoming an issue. There are multiple of initiative on the market to help generating proper documentation (phpDocumentor, phpDox, ....). But they are all massive and not intuitive. I decided to create something ultra simple providing a php source file containing all your function, and an output file that will generating markdown syntax. Ideal for GitHub.

Basic Idea

I've started to write the documentation of my Php frameworks (both for Rubrik and Nutanix) about 3 years ago ... and this is not evolving that much. If you do not have a proper documentation, people won't even look at your project and you will be in the blue of Internet. I spent so much time creating those libraries that would be sad if nobody actually use them.

So, instead of spending my night updating and maintaining the documentation, I decided to create a simple code that can do it for me. YES !

Honestly, this is not a big deal, parsing a text file, detecting some keywords and put it on a nice layout, this is something anyone can do, you just need to think about it.

So far, I only plan to support Php as source language.

Markdown

Since this project is DevOps related, I decided to stick to the MD syntax. MD stands for Markdown, this is very common on GitHub to create rich text files. It has all we need : titles, preformatted text, syntax highlighting .... 

There is a Markdown reference on GitHub that explains all the possibilities, and there are a lot. Actually more than I need for now. More information about Markdown here.

So, I decided to start with what I already created as a starting point and this is where I came.

How to use it ?

First, you need to get the code, it is on my dedicated repo on GitHub. Opposed to other solutions in the market, my code does not requires to add special markups in the original php file, the original file remain untouched

Next, you need to configure some basic variable inside the code : 

// File that contains your code to analyze

$inputFile="library.php";

Library.php in this case is the php source that for which you want to generate the documentation. This files must contains functions.

// File where to write the generated documentation $outputFile="README.md";

I believe it is obvious that $outputFile is the target file for the generated documentation.

// If needed you can add the author of the code, it will be added in the author section below

$author="Frederic Lhoest - *@flhoest*";

You can add a author footer to the documentation. As you can see Markdown syntax is allowed.

// Define the document title

$documentTitle="Rubrik API Framework (written in Php)";

Any good documentation got a title !

// Add logo on the header section (one or more if required, configured in a array as URL)

$addLogo=TRUE;

$logoArray=array("http://rubrik.com/wp-content/uploads/2014/10/logo-large-gray.png");

You have the ability to add one or more logo (as a reference URL). If you need more than one, just add another entry in the array. The logo will be displayed below the main document title.

// Define project introduction

$addIntro=TRUE;

$documentIntro="This project's goal is to provide anyone who needs to script automation, a collection of functions that call Rubrik's APIs.";

Optionaly, you can add an intro in your documentation. I will fall into the "Background" section of the documentation just below the logos.

Here is a sample run on one of my library : 

$ php docGen.php
Preparing functions documentation for library.php...

Check generated document here : README.md 

A total of 92 functions has been pre-documented 

The generated file is best viewed using MD file parser like https://dillinger.io/ or directly on GitHub

End.

If you want to read the .MD file locally on your machine, if you are on macOS I recommend MacDown. If you are on Windows, you can use Haroopad.

What next ?

Do not think that this is that magical. You still need to do some work. Actually the biggest part of the documentation is the layout and the reference to each and every functions. You still have to do something : change the ENTER TEXT HERE in the text and add the correct meaning of each functions and sample execution, so the reader can have a good understanding of what it going on. This code is  generating a template that can then be adjusted with the right content (and the right tool).

When this last step is completed, you are free to distribute or share on GitHub ;)

I hope this help. I think it will save me some nights !