New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generating online HTML from PHP Doc for Magento 2 #1011

Closed
alankent opened this Issue Jan 30, 2015 · 5 comments

Comments

Projects
None yet
9 participants
@alankent
Copy link

alankent commented 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.

@Flyingmana

This comment has been minimized.

Copy link
Contributor

Flyingmana commented Feb 1, 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”.

👍

@daim2k5

This comment has been minimized.

Copy link
Member

daim2k5 commented Feb 7, 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

@wqcoder

This comment has been minimized.

Copy link

wqcoder commented Apr 2, 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

@piotrekkaminski

This comment has been minimized.

Copy link
Contributor

piotrekkaminski commented Aug 29, 2016

Thank you for your submission.

We recently made some changes to the way we process GitHub submissions to more quickly identify and respond to core code issues.

Feature Requests and Improvements should now be submitted to the new Magento 2 Feature Requests and Improvements forum (see details here).

We are closing this GitHub ticket and have moved your request to the new forum.

@tibkov

This comment has been minimized.

Copy link

tibkov commented Sep 2, 2016

Hi! For the time being you can checkout my "magento2-api-doc" repo.

It holds the whole class library documentation (generated from source code) for Magento CE (Community Edition) 2.1.0 GA release.

Magento 2.1.0 was downloaded with composer, and the "ROOT/vendor/magento" folder has been processed for API documentation by the "Sami" API doc generator.

magento-team pushed a commit that referenced this issue Apr 9, 2017

Merge pull request #1011 from magento-frontend/MAGETWO-59587
Story
- MAGETWO-59587 Debugging and profiling tools for UI Components and Javascript modules
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment