search

doctrine / doctrine-website-sphinx

Sphinx-based Doctrine Website
18 stars 25 forks source link

Documentation should link API #154

Open jkufner opened 7 years ago

jkufner commented 7 years ago

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.)

mikeSimonson commented 7 years ago

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.

jkufner commented 7 years ago

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.

Ocramius commented 7 years ago

Tbh, I would prefer linking the source files directly: phpdoc is extremely useless nowadays

On 11 Aug 2017 17:20, "Josef Kufner" notifications@github.com 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 .