phpDocumentor: Auto generate Emoncms docs

Emoncms
1

I am currently running some tests using Gulp and apiDoc to create in-line documentation.
This will of course help developers get a faster grasp on the project as a whole, and easier to create new or extend existing modules.
Since I have not used documentation generators before, I am not sure if this is correct tool for the job.
Ideally I would want the following documented:

  • Module modal class object (aka {module}_model.php)
  • Module Javascript objects that make calls to backend(please advise on correct terminology for this)
  • +optional: Module controller if possible

Below is a example of what I have generated so far, but mixing the php class objects with API related documentation seems odd.

apidocemoncms.jpg1919×981 78.2 KB

Could someone advise on the correct approach to do to properly document all the module class and API’s?

2

Looks like phpDocumentor much more suitable! Looks much better, but now all the functions need to be properly commented.
Community interested?

apidocemoncms2.jpg1665×991 78.8 KB

3

Nice! This looks cool. Sorry for slow reply. Yes we would be interested. How does it integrate with the source code? Have you got an example e.g. Your github emoncms fork? Obviously the challenge will be to keep it updated from the code itself, does it get auto generated directly from the source? If so this is awesome :grinning:

What do you think @TrystanLea?

4

It integrates directly into the source files, only requires a small commented area to describe the function, so its clean and easy. Will require some effort to analyze all the functions and write in the required comments so that documentation can be generated properly. But even without the detailed comments, you still get a good overview of available functions. I will need to go dig this out the projects folder, since I stopped working on Emoncms. Ill send you instructions on how to set it up, unfortunately my branch is a mess and not mergable with your current versions.

5

Great, look forward to seeing an example .

Could you start a new branch from a fresh copy of master branch? The easiest way to discuss and eventually merge the required changes will be with a PR to the master Emoncms core master branch.

Thanks :thumbsup:

6

Hi Glen.

Have a look at this branch here: GitHub - XaroRSA/EmonCMS_ApiDOC

Lots of room for improvement, but should be good enough for a demo (This all assumes you have composer ready, otherwise check out Introduction - Composer )
Basically, install phpdoc using the the composer file inside the project, or make/modify your existing one.
Instructions from phpdoc site:

Add a dependency to phpdocumentor/phpdocumentor to the require-dev section of your project’s composer.json configuration file, and update your application.

The following code is an example of a minimal composer.json file:

{
“require-dev”: {
“phpdocumentor/phpdocumentor”: “2.*”
}
}

Check the readme for details, let me know if you get stuck, and what you think once its running.

Cheers

7

Got it installed using Composer, first time using composer, quite impressed. I would like to look at using Composer for all Emoncms dependances, see work in progress docker setup.

I have copied over your phpdoc.dist.xml but phpdoc does not seem to detecting up the .xml it up. Am I in the right directory? There is a vendor/bin folder which is empty.

$ ~/Downloads/www/emoncms/vendor/phpdocumentor/phpdocumentor/bin$ ls 
phpdoc  phpdoc.bat  phpdoc.dist.xml  phpdoc.php  utils

$ ~/Downloads/www/emoncms/vendor/phpdocumentor/phpdocumentor/bin$ ./phpdoc
Collecting files .. OK
Initializing parser .. OK
Parsing files
                                                                                   
  [Exception]                                                                      
  No parsable files were found, did you specify any using the -f or -d parameter?
8

Are you running a Mac or Linux? I only tested on windows.
From that directory ($ ~/Downloads/www/emoncms/vendor/phpdocumentor/phpdocumentor/bin), you would need to modify the config file so that it can find the php files.
Open the phpdoc.dist.xml, and change the paths to ‘~/Downloads/www/emoncms/docs/output’ and ‘~/Downloads/www/emoncms/Modules/**/’ or however its set on your OS.

9

I’m running on Linux ubuntu. Got it, I moved phpdoc.dist.xml to the root emoncms folder and changed the paths
For anyone else wanting to give this a go this is how I installed php docs:

1. Install composer

$ cd /var/wwww/emoncms
$ php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
$ php -r "if (hash_file('SHA384', 'composer-setup.php') === 'e115a8dc7871f15d853148a7fbac7da27d6c0030b848d9b3dc09e2a0388afed865e6a3d6b3c0fad45c48e2b5fc1196ae') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
$ php composer-setup.php
$ php -r "unlink('composer-setup.php');"

2. Install phpdocs using composer

Add composer.json into emoncms folder:

{
    "require-dev": {
        "phpdocumentor/phpdocumentor": "2.*"
    }
}

Then run

$ php composer.phar install

3. Run php docs on Modules folder

phpdoc.dist.xml add to the root emoncms folder with paths

<?xml version="1.0" encoding="UTF-8" ?>
<phpdoc>
    <parser>
        <target>docs/output</target>
    </parser>
    <transformer>
        <target>docs/output</target>
    </transformer>
    <files>
        <directory>Modules/**/</directory>
    </files>
</phpdoc>

Run $ vendor/phpdocumentor/phpdocumentor/bin/phpdoc

Documentation got generated intou docs/output :slight_smile:

Is it standard practice not to commit vendor/* to the project repository but rather let the users install phpdocs and its dependencies using Composer? Since phpdocs and it’s dependencies are quite extensive! I don’t want to bloat the repository.

I will get the docs hosted on our test server so the emoncms devs can evaluate their usefulness before proceeding.

Update: Emoncms module docs as generated by phpdocs can be viewed here

10

Absolutely. Same for node/npm package management. Only the ‘initilization’ file gets commited. Users should then just run a ‘install’ command to get all requried dependancies.

11

Got it, sounds good. Just like Ruby Bundler

12

Emoncms module docs as generated by phpdocs can be viewed here

Selection_068.png1538×886 79.2 KB

What do you think @TrystanLea, @nchaveiro ? Shall I commit the docs and the composer file to install phpdocs to a new branch on the repo so we can evaluate further?

As @XaroRSA mentioned:

The example posted above is without any commenting just a raw list of all the available functions. Even thought there are not developer comments I can see this being very useful for someone getting their head around how a module works.