Right now a lot of our links to generated documentation on php classes are manually copied.
One of the reasons for this seems to be how badly Doxygen handles the anchors to sections on individual methods. Instead of simply using the method name it generates a md5 hash of a signature that is impossible to know simply with a class and method name. Meaning we can't simply have a template to link to documentation.
However Doxygen exports a tagfile that includes a list of classes, their methods, and the anchors used for their links.
This is currently at: (*warning* large file) https://doc.wikimedia.org/mediawiki-core/master/php/html/tagfile.xml
What does everyone think of making it so that when Jenkins generates this documentation. It processes the tagfile, splits it up and converts it into multiple lua tables, then uses the API to update a Module: page on mediawiki.org.
This way templates can have some Lua code that uses that data to create links with something like:
local classes = mw.loadData( 'DoxygenTags mediawiki-core class' ) ...
function p.methodLink(className, methodName) local class = classes[className] ... local method = members.function[methodName] ... return "https://doc.wikimedia.org/mediawiki-core/master/php/html/" + method.anchorfile + "#" + method.anchor end
...
On Fri, Mar 22, 2013 at 9:43 AM, Daniel Friesen daniel@nadir-seen-fire.comwrote:
Right now a lot of our links to generated documentation on php classes are manually copied.
One of the reasons for this seems to be how badly Doxygen handles the anchors to sections on individual methods. Instead of simply using the method name it generates a md5 hash of a signature that is impossible to know simply with a class and method name. Meaning we can't simply have a template to link to documentation.
However Doxygen exports a tagfile that includes a list of classes, their methods, and the anchors used for their links.
This is currently at: (*warning* large file) https://doc.wikimedia.org/**mediawiki-core/master/php/**html/tagfile.xmlhttps://doc.wikimedia.org/mediawiki-core/master/php/html/tagfile.xml
What does everyone think of making it so that when Jenkins generates this documentation. It processes the tagfile, splits it up and converts it into multiple lua tables, then uses the API to update a Module: page on mediawiki.org.
This way templates can have some Lua code that uses that data to create links with something like:
local classes = mw.loadData( 'DoxygenTags mediawiki-core class' ) ...
function p.methodLink(className, methodName) local class = classes[className] ... local method = members.function[methodName] ... return "https://doc.wikimedia.org/**mediawiki-core/master/php/** html/ https://doc.wikimedia.org/mediawiki-core/master/php/html/" + method.anchorfile + "#" + method.anchor end
...
I would go further and suggest a way to integrate code comments into manual pages at mediawiki.org, so that we could have good documentation in both code and mw.org, without needing to sync it manually. For example, the detailed description of api.php found at https://doc.wikimedia.org/mediawiki-core/master/php/html/api_8php.html#detai... be integrated into https://www.mediawiki.org/wiki/Manual:api.php
Similarly, the contents of README files and the docs folder should be integratable into mw.org.
If what Daniel suggests is feasible, I assume this also is, and imo would greatly improve the availability and quality of both in-wiki and code documentation.
--Waldir
On Fri, 22 Mar 2013 05:05:13 -0700, Waldir Pimenta waldir@email.com wrote:
I would go further and suggest a way to integrate code comments into manual pages at mediawiki.org, so that we could have good documentation in both code and mw.org, without needing to sync it manually. For example, the detailed description of api.php found at https://doc.wikimedia.org/mediawiki-core/master/php/html/api_8php.html#detai... be integrated into https://www.mediawiki.org/wiki/Manual:api.php
Similarly, the contents of README files and the docs folder should be integratable into mw.org.
If what Daniel suggests is feasible, I assume this also is, and imo would greatly improve the availability and quality of both in-wiki and code documentation.
--Waldir
This information isn't available in the current doxygen output. Tagfile provides an index. But that kind of content is only available in the full html output. You might be able to get at it if we turned on XML output. But it would have a ridiculous amount of extra cruft you won't want and will take a lot of work to format.
Le 22/03/13 10:43, Daniel Friesen a écrit :
What does everyone think of making it so that when Jenkins generates this documentation. It processes the tagfile, splits it up and converts it into multiple lua tables, then uses the API to update a Module: page on mediawiki.org.
If you can come back with an even more complicated suggestion, I am all for it. Meanwhile lets point people to doc.wikimedia.org and let everyone directly use Doxygen output instead of mw.org.
Antoine Musso hashar+wmf@free.fr wrote:
What does everyone think of making it so that when Jenkins generates this documentation. It processes the tagfile, splits it up and converts it into multiple lua tables, then uses the API to update a Module: page on mediawiki.org.
If you can come back with an even more complicated suggestion, I am all for it. Meanwhile lets point people to doc.wikimedia.org and let everyone directly use Doxygen output instead of mw.org.
I think Daniel's idea has some merit to it though obviously you are (very) right about the unnecessary complexity.
How about a simple CGI on doc.wikimedia.org that provides redirects? Or, even better and more reusable by other projects: Make Doxygen output predictable anchors in addi- tion to the hash ones?
Tim
wikitech-l@lists.wikimedia.org