doctrine-website-sphinx
doctrine-website-sphinx copied to clipboard
doctrine
Documentation should link API
All mentions of classes and methods in the documentation should link to API documentation.
For example, at http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/query-builder.html the Doctrine\DBAL\Connection#createQueryBuilder should link to http://www.doctrine-project.org/api/dbal/2.3/class-Doctrine.DBAL.Connection.html#_createQueryBuilder.
Such links make it much easier to understand and use the documented features in real applications.
For example Doxygen converts known names of classes and methods to links automatically, even in Markdown pages. It should be relatively easy to obtain list of known methods and classes with their URLs from the generated documentation and then replace the names with links in the documentation.
(Issue moved from https://github.com/doctrine/doctrine2/issues/6617.)
The documentation gets also generated in pdfs, so you can't just paste in there the http link but I am sure that you can make those links. It's just going to take longer and need to be done by hand one by one.
I don't see difference between HTML and PDF output. Both can link to HTML resources. If the API is part of the PDF, the link can target the chapter in the same file. If not, then link web page.
Also, I don't see the need for manual processing. Just replace everything. There will be few false positives, but it is much easier to fix these than replace manually everything.
Tbh, I would prefer linking the source files directly: phpdoc is extremely useless nowadays
On 11 Aug 2017 17:20, "Josef Kufner" [email protected] wrote:
I don't see difference between HTML and PDF output. Both can link to HTML resources. If the API is part of the PDF, the link can target the chapter in the same file. If not, then link web page.
Also, I don't see the need for manual processing. Just replace everything. There will be few false positives, but it is much easier to fix these than replace manually everything.
— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/doctrine/doctrine-website-sphinx/issues/154#issuecomment-321842181, or mute the thread https://github.com/notifications/unsubscribe-auth/AAJakKbIbingxr4u3ITvgycPhDYsIbPXks5sXHEhgaJpZM4O0rxN .
