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
Hook documentation generator - add links to classes and methods in the developer guides and auto generated docs #4244
Comments
FYI: Links from classes/methods to hooks: multiple days for #4242 + half a day or so for this feature |
Let's use existing standard {@link } notation http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlinelink.pkg.html |
IMHO this is the last key missing feature of developer.piwik.org |
For links in PHPDoc I am thinking about supporting the following type of inline links:
If the link to the class or method or whatever is public and has API tag, I will replace the link with an actual link. If not, I will probably only mark the name of the class, property, ... as "code" (wrap it in backticks). |
currently supported is https://github.com/piwik/developer-documentation/blob/master/README.md#supported-inline-tags-in-comments . Can you think of more? Is anything else needed? There are still some (5-10) "broken/missing" links to some guides. I don't want to set them yet as the links might change... Can you fix the links? Just search for "(#)" or "](#". "and the links should all work"... the "should" work. Tested with some broken links checker and clicked manually through some pages but hard to say they all work for sure! Open:
|
I am now logging to STDOUT which links are not resolved. A summary is available here: http://pastebin.com/Bj1jDEkQ The links are not resolved if the target class is not API or if there are links to protected methods which are not marked as API. Basically all Constants were not resolved as well (not in the list) as we can only link to constants having a long description (Constants having no long description are not displayed on developer.piwik.org). In this case we just highlight the constant as code but do not link to it. |
BTW: Because I've seen a link to a twig function: It is still to be defined how to document Twig filters and JavaScript functions. Not really related to this ticket but noticed it during working on this. |
Found a bug/limitation in Sami that needs to be fixed: block elements in @param & related tags do not show up correctly. For example:
appears as
I've looked into the fix, and it seems to involve three things:
Where indentNewLines indents each newline by however many spaces so it becomes part of the description element.
Not sure how to do step 2, so can't fix it myself. |
Nevermind, fixed it. Had to fork tsteur/Sami, btw. Fork is located at piwik/Sami on github. |
Fantastic work guys... @capedfuzz what is the status of this ticket, can you close the ticket? |
The goal of this ticket is to make all links in pages and guides of developer.piwik.org work and link to the correct resources.
Features
QA
The text was updated successfully, but these errors were encountered: