Re: [Wikitech-l] Making it possible to create method documentation links on MW.org

[Tim Landscheidt]

Antoine Musso  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 mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l

Re: [Wikitech-l] Making it possible to create method documentation links on MW.org

[Antoine Musso]

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 "hashar" Musso


___
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l

Re: [Wikitech-l] Making it possible to create method documentation links on MW.org

[Daniel Friesen]

On Fri, 22 Mar 2013 05:05:13 -0700, Waldir Pimenta   
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#detailscould
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.


--
~Daniel Friesen (Dantman, Nadir-Seen-Fire) [http://danielfriesen.name/]


___
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l

Re: [Wikitech-l] Making it possible to create method documentation links on MW.org

[Waldir Pimenta]

On Fri, Mar 22, 2013 at 9:43 AM, Daniel Friesen
wrote:

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

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#detailscould
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
___
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l

[Wikitech-l] Making it possible to create method documentation links on MW.org

[Daniel Friesen]

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

...


--
~Daniel Friesen (Dantman, Nadir-Seen-Fire) [http://danielfriesen.name/]


___
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l