cancel
Showing results for 
Search instead for 
Did you mean: 

Generating online HTML from PHP Doc for Magento 2

0 Kudos

Generating online HTML from PHP Doc for Magento 2

Feature request from alankent, posted on GitHub Jan 30, 2015

The complete suite of Magento developer documentation will consist of content from multiple sources. There are guides that the documentation writing team are developing (such as at http://devdocs.magento.com), more traditional online documentation generated from PHP Doc comments, and potentially other automatically generated documentation on REST/SOAP APIs and similar.

This issue is an invitation for the community to help with the PHP Doc aspect of documentation generation. There are several aspects to this work:

  • Try some different tools to see which are best able to support Magento. This relates to usability of output, speed and robustness of the tool, etc.
  • One proposal is to not generate documentation for all classes, but instead restrict the published documentation to only those classes and methods that the Magento team recommends being used. Such classes and methods could be annotated by “@api”. As such, it is desirable for the tool to be able to use @api as a flag of what to include in the generated output. This may involve modifying an existing tool as there may be no PHP Doc generation tools today that support this functionality.
  • Support for official Magento branding is also important. The core team can apply this branding (most likely following the same style and themes as the current documentation site). The objective is to take into account this requirement when selecting which tool to use.
  • Incorporation of documentation generation into the current documentation publishing on GitHub is desirable, but not mandatory.
  • An interesting future question is whether content developed by tech writers and PHP generated documentation can be merged. For example, having sample code linked to from the PHP Doc, or having links from guides to PHP Doc (without hard coding URLs to a specific web site). It is desirable to generate a single set of documentation that included both PHP Doc and guides.

In general, the goal is to get something up relatively quickly and deliver a useful short term result, restricted to PHP Doc. To set expectations, it may be this tool is temporary until replaced by a more encompassing solution for all documentation.

The goal is to lower the barrier to people exploring the Magento 2 code base today. Once the PHP Doc documentation is published, a desirable side effect is to then encourage greater contribution to improve the quality of the PHP Doc comments within the code base.

3 Comments
Not applicable

Comment from Flyingmana, posted on GitHub Feb 01, 2015

One proposal is to not generate documentation for all classes, but instead restrict the published documentation to only those classes and methods that the Magento team recommends being used. Such classes and methods could be annotated by “@api”.

:+1:

Not applicable

Comment from daim2k5, posted on GitHub Feb 07, 2015

I tried the last night to generate docs with sami (https://github.com/FriendsOfPHP/Sami). The Project support to filter the output via tags. Also you can style the hole documentation via Twig. BUT :-( if i use the filter SymfonyFilter i get errors and nothing is generated. The default filter works. Here my config file if someone else can resolve the problem (https://gist.github.com/daim2k5/f963c98db70a5731a87b).

Error was PHP Fatal error: Call to a member function getName() on a non-object in /mage2docgenerator/vendor/sami/sami/Sami/Console/Command/Command.php on line 152

Not applicable

Comment from wqcoder, posted on GitHub Apr 02, 2016

Hi, I tried to generate docs with phpDocumentor yesterday. D:\pear>phpdoc run -d "E:\www\magento22\lib\internal\Magento\Framework" -t "D:\phpDoc"

phpDocumentor version 2.8.5 windows7 Intel(R)Xeon(R)CPU E3-1231 v3 @3.40Hz RAM8GB D:\pear>php -v PHP 5.6.16 (cli) (built: Nov 25 2015 18:51:26) Copyright (c) 1997-2015 The PHP Group Zend Engine v2.6.0, Copyright (c) 1998-2015 Zend Technologies

It started from yesterday about 12:30, and this morning (about 7:00)when I went to check it has finished. But I got an error: [phpDocumentor\GraphViz\Exception] An error occurred while creating the graph; GraphViz returned: Error: trouble in init_rank

The phpdoc file is 8.63G, and have no chart of course.

GraphViz fails on ZF2 #1350