Developer documentation fails to build

[ibennetch]

Our developer docs fail to build:

# /home/builder/scripts/develdocs/vendor/bin/apigen generate --debug  --todo --source libraries/ --destination  /home/builder/scripts/develdocs/output/phpmyadmin

Fatal error: Cannot use 'Object' as class name as it is reserved in /home/builder/scripts/develdocs/vendor/latte/latte/src/Latte/Object.php on line 14
ErrorException: Cannot use 'Object' as class name as it is reserved in /home/builder/scripts/develdocs/vendor/latte/latte/src/Latte/Object.php:14
Stack trace:
#0 [internal function]: Tracy\Debugger::shutdownHandler()
#1 {main}
Unable to log error: Logging directory is not specified.

Looks like a problem with ApiGen: ApiGen/ApiGen#1039

We're on version 4, which is no longer supported. The poster's solution there was to upgrade to the current version 5, (which is still technically in pre-release form).

However, if I try with current dev-master, it fails with a memory error:

vendor/bin/apigen generate  /var/www/pma-dev/fork/libraries/ --destination output
Parsing reflections (this may take a while)...
mmap() failed: [12] Cannot allocate memory
Segmentation fault

I've allocated 8000M and still get errors. Another user had trouble but seems to have resolved it with a memory limit of 512M.

[nijel]

APIGen 5.0 doesn't scale for us (and many other projects), see ApiGen/ApiGen#1015. There is PR to partially address this ApiGen/ApiGen#1038, however the project is looking for new maintainer ApiGen/ApiGen#1020, so it's unsure whether the issue will ever be addressed.

Maybe it's time to look for other docs generator, see cakephp/cakephp-api-docs#99 for similar discussion.

[ibennetch]

I've done a brief test of several of the options and here are my findings along with notes from the referenced tickets:

• phpDocumentor2: I couldn't get it to generate any output, didn't investigate further
• SAMI: Easy to install and use. According to a poser in the cakephp thread, it has these shortcomings:
  • When you open an interface it doesn't show you what classes implement it.
  • It can't show the source code.
• php-apidoc: Seems to be a very manual process; if I understand the documentation correctly you have to manually add classes to the configuration file for them to be included.

I can upload the sample output from SAMI if people would like to take a look.

[ibennetch]

I've temporarily disabled the script in the crontab since this isn't working anyway.

[williamdes]

Sami seems to be a nice solution : https://github.com/FriendsOfPHP/Sami
Twig uses Sami : https://twig.symfony.com/api/2.x/index.html

I have successfully built the docs of phpMyAdmin with Sami, it looks good (IMO).

@ibennetch Any update to bringing back develdocs ?

[nijel]

@williamdes Can you adjust https://github.com/phpmyadmin/scripts/blob/master/develdocs/build.sh to build docs using sami? Once it works, it will get pushed to develdocs.phpmyadmin.net.

[ibennetch]

The update is basically that when I tested Sami it was the best of the three I tried, but no one else commented about whether the two shortcomings I mentioned were a problem or something that can be worked around, so I didn't take any further action.

As Michal said, you're welcome to submit the pull request as anything is better than what we have now.

[williamdes]

Pull request submitted: #13