Hello! Our current generated documentation[1] uses doxygen, and leaves... a number of things to be desired - such as:
1. Not be tortoise slow 2. Have usable search 3. Prettier interface
I was looking around for alternatives, and ran into phpdocumentor2[2]. The project still seems active (latest commit was 3 days ago, and for vagrant support!), and the demo was quite pretty:
http://demo.phpdoc.org/Responsive/namespaces/phpDocumentor.html
Is there any particular reason we are still sticking with doxygen? Or is it just 'someone needs to find the time to move things over to the new system'?
[1]: https://doc.wikimedia.org/mediawiki-core/master/php/html/ [2]: http://www.phpdoc.org/
-- Yuvi Panda T http://yuvi.in/blog
Could we maybe get use PHPDoc to generate MediaWiki docs, so that we can compare them side-by-side.
*-- * *Tyler Romeo* Stevens Institute of Technology, Class of 2016 Major in Computer Science www.whizkidztech.com | tylerromeo@gmail.com
On Fri, Jul 5, 2013 at 8:36 PM, Yuvi Panda yuvipanda@gmail.com wrote:
Hello! Our current generated documentation[1] uses doxygen, and leaves... a number of things to be desired - such as:
- Not be tortoise slow
- Have usable search
- Prettier interface
I was looking around for alternatives, and ran into phpdocumentor2[2]. The project still seems active (latest commit was 3 days ago, and for vagrant support!), and the demo was quite pretty:
http://demo.phpdoc.org/Responsive/namespaces/phpDocumentor.html
Is there any particular reason we are still sticking with doxygen? Or is it just 'someone needs to find the time to move things over to the new system'?
-- Yuvi Panda T http://yuvi.in/blog
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Could we maybe get use PHPDoc to generate MediaWiki docs, so that we can compare them side-by-side.
This is an important request because (to play devil's advocate here a little bit)...
- Not be tortoise slow
Pretty sure this only matters because we do continuous integration -- we probably don't need to do this for every commit...? Maybe once a day?
In any case -- who says PHPDoc is any faster.
- Have usable search
The demo at least doesn't even offer search functionality...
But does this even matter? I would argue in favour of a independent search solution along the lines of Ohloh [1] so that we can integrate our JSDuck documentation.
- Prettier interface
Prettier does not mean more usable. Imho after playing with their online demo for 5 minutes it was *less* usable than doxygen. Additionally, if you think doxygen is ugly, we can reskin it!
~Matt Walker Wikimedia Foundation Fundraising Technology Team
On Fri, Jul 5, 2013 at 5:39 PM, Tyler Romeo tylerromeo@gmail.com wrote:
Could we maybe get use PHPDoc to generate MediaWiki docs, so that we can compare them side-by-side.
*-- * *Tyler Romeo* Stevens Institute of Technology, Class of 2016 Major in Computer Science www.whizkidztech.com | tylerromeo@gmail.com
On Fri, Jul 5, 2013 at 8:36 PM, Yuvi Panda yuvipanda@gmail.com wrote:
Hello! Our current generated documentation[1] uses doxygen, and leaves... a number of things to be desired - such as:
- Not be tortoise slow
- Have usable search
- Prettier interface
I was looking around for alternatives, and ran into phpdocumentor2[2]. The project still seems active (latest commit was 3 days ago, and for vagrant support!), and the demo was quite pretty:
http://demo.phpdoc.org/Responsive/namespaces/phpDocumentor.html
Is there any particular reason we are still sticking with doxygen? Or is it just 'someone needs to find the time to move things over to the new system'?
-- Yuvi Panda T http://yuvi.in/blog
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Ack -- my [1] reference was supposed to be https://www.ohloh.net/ but thinking about it; we want documentation search not code search and ideally it would be opensource... but my point remains! We need a cross language/documentation search system.
~Matt Walker Wikimedia Foundation Fundraising Technology Team
On Fri, Jul 5, 2013 at 6:06 PM, Matthew Walker mwalker@wikimedia.orgwrote:
Could we maybe get use PHPDoc to generate MediaWiki docs, so that we can
compare them side-by-side.
This is an important request because (to play devil's advocate here a little bit)...
- Not be tortoise slow
Pretty sure this only matters because we do continuous integration -- we probably don't need to do this for every commit...? Maybe once a day?
In any case -- who says PHPDoc is any faster.
- Have usable search
The demo at least doesn't even offer search functionality...
But does this even matter? I would argue in favour of a independent search solution along the lines of Ohloh [1] so that we can integrate our JSDuck documentation.
- Prettier interface
Prettier does not mean more usable. Imho after playing with their online demo for 5 minutes it was *less* usable than doxygen. Additionally, if you think doxygen is ugly, we can reskin it!
~Matt Walker Wikimedia Foundation Fundraising Technology Team
On Fri, Jul 5, 2013 at 5:39 PM, Tyler Romeo tylerromeo@gmail.com wrote:
Could we maybe get use PHPDoc to generate MediaWiki docs, so that we can compare them side-by-side.
*-- * *Tyler Romeo* Stevens Institute of Technology, Class of 2016 Major in Computer Science www.whizkidztech.com | tylerromeo@gmail.com
On Fri, Jul 5, 2013 at 8:36 PM, Yuvi Panda yuvipanda@gmail.com wrote:
Hello! Our current generated documentation[1] uses doxygen, and leaves... a number of things to be desired - such as:
- Not be tortoise slow
- Have usable search
- Prettier interface
I was looking around for alternatives, and ran into phpdocumentor2[2]. The project still seems active (latest commit was 3 days ago, and for vagrant support!), and the demo was quite pretty:
http://demo.phpdoc.org/Responsive/namespaces/phpDocumentor.html
Is there any particular reason we are still sticking with doxygen? Or is it just 'someone needs to find the time to move things over to the new system'?
-- Yuvi Panda T http://yuvi.in/blog
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
On Sat, Jul 6, 2013 at 6:41 AM, Matthew Walker mwalker@wikimedia.org wrote:
Ack -- my [1] reference was supposed to be https://www.ohloh.net/ but thinking about it; we want documentation search not code search and ideally it would be opensource... but my point remains! We need a cross language/documentation search system.
I would love for us to have one, but that doesn't change the fact that the current one sucks.
-- Yuvi Panda T http://yuvi.in/blog
On Sat, Jul 6, 2013 at 6:36 AM, Matthew Walker mwalker@wikimedia.org wrote:
- Not be tortoise slow
Pretty sure this only matters because we do continuous integration -- we probably don't need to do this for every commit...? Maybe once a day?
In any case -- who says PHPDoc is any faster.
Slow to use, not slow to generate. On my firefox it constantly gets stopped with a 'script on this page is taking too long to run'
- Have usable search
The demo at least doesn't even offer search functionality...
But does this even matter? I would argue in favour of a independent search solution along the lines of Ohloh [1] so that we can integrate our JSDuck documentation.
Haven't checked out Ohloh's, but something as simple as 'I want to see documentation for WikiPage::factory' should be achievable by typing 'WikiPage::factory' into the docs. I'm setting up a phpdoc instance on my local system, to see how it goes.
- Prettier interface
Prettier does not mean more usable. Imho after playing with their online demo for 5 minutes it was *less* usable than doxygen. Additionally, if you think doxygen is ugly, we can reskin it!
My googling skills have not found me too many other skins - I'll be very happy if you could find / write one!
-- Yuvi Panda T http://yuvi.in/blog
On 7/5/13, Yuvi Panda yuvipanda@gmail.com wrote:
On Sat, Jul 6, 2013 at 6:36 AM, Matthew Walker mwalker@wikimedia.org wrote:
- Not be tortoise slow
Pretty sure this only matters because we do continuous integration -- we probably don't need to do this for every commit...? Maybe once a day?
In any case -- who says PHPDoc is any faster.
Slow to use, not slow to generate. On my firefox it constantly gets stopped with a 'script on this page is taking too long to run'
Interesting. For me its speedy (or at least acceptably fast) and I'm on firefox 3.5
- Have usable search
The demo at least doesn't even offer search functionality...
But does this even matter? I would argue in favour of a independent search solution along the lines of Ohloh [1] so that we can integrate our JSDuck documentation.
Haven't checked out Ohloh's, but something as simple as 'I want to see documentation for WikiPage::factory' should be achievable by typing 'WikiPage::factory' into the docs. I'm setting up a phpdoc instance on my local system, to see how it goes.
I generally go directly to the class I want, so not really something that would bother me (Actually I didn't even know we had a search box).
I also primarily use grep locally to search for things... I guess newbies which are the documentations primary use case, probably are less likely to do that.
--bawolff
On 06/07/13 12:02, Brian Wolff wrote:
On 7/5/13, Yuvi Panda yuvipanda@gmail.com wrote:
On Sat, Jul 6, 2013 at 6:36 AM, Matthew Walker mwalker@wikimedia.org wrote:
- Not be tortoise slow
Pretty sure this only matters because we do continuous integration -- we probably don't need to do this for every commit...? Maybe once a day?
In any case -- who says PHPDoc is any faster.
Slow to use, not slow to generate. On my firefox it constantly gets stopped with a 'script on this page is taking too long to run'
Interesting. For me its speedy (or at least acceptably fast) and I'm on firefox 3.5
Expanding large tree view lists, like the class list, seems quite slow. For me on Firefox 21.0, it took about 5 seconds to expand the class list, and used an extra 140MB of RSS at peak. It seems to expand the class list every time you visit a class page, and it blocks the rendering thread, so that could start to grate after a while. The solution, I suppose, is GENERATE_TREEVIEW=no.
-- Tim Starling
Yuvi Panda writes:
Hello! Our current generated documentation[1] uses doxygen, and leaves... a number of things to be desired - such as:
What about a bug report [or a patch ;-)]?
Jan
- Not be tortoise slow
- Have usable search
- Prettier interface
I was looking around for alternatives, and ran into phpdocumentor2[2]. The project still seems active (latest commit was 3 days ago, and for vagrant support!), and the demo was quite pretty:
http://demo.phpdoc.org/Responsive/namespaces/phpDocumentor.html
Is there any particular reason we are still sticking with doxygen? Or is it just 'someone needs to find the time to move things over to the new system'?
-- Yuvi Panda T http://yuvi.in/blog
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Le 06/07/13 02:36, Yuvi Panda a écrit :
Hello! Our current generated documentation[1] uses doxygen, and leaves... a number of things to be desired - such as:
- Not be tortoise slow
I have originally migrated from PHPDoc to Doxygen because it was blazing fast to generate doc. Doxygen also supports several languages, so if we came adding a second language, we could have used the same documentation generator. History show that JavaScript is better documented using JSDuck: https://doc.wikimedia.org/mediawiki-core/master/js/
It does manpages as well :-) But we can probably live without it.
From time to time, I look at other documentation generator for PHP
language. All ends up eating all memory and being painfully slow to generate the doc when they don't cause a segfault.
- Have usable search
Doxygen has an EXTERNAL_SEARCH configuration that makes it generate an XML file which could probably get indexed somehow in Solr. SEARCHENGINE_URL would point to the search instance.
- Prettier interface
Some CSS loves is needed :) It can definitely be made as shown on: http://www.openfoam.org/docs/cpp/
Kde adapted it as well: http://api.kde.org/4.x-api/kde-baseapps-apidocs/kate/part/html/hierarchy.htm...
I was looking around for alternatives, and ran into phpdocumentor2[2]. The project still seems active (latest commit was 3 days ago, and for vagrant support!), and the demo was quite pretty:
http://demo.phpdoc.org/Responsive/namespaces/phpDocumentor.html
Is there any particular reason we are still sticking with doxygen? Or is it just 'someone needs to find the time to move things over to the new system'?
There is also Sami used by Symfony: Example: http://api.symfony.com/2.3/index.html Code: https://github.com/fabpot/sami
And apigen https://github.com/apigen/apigen
Why you want to move from it? Just create a new project on labs (tools) and cron a job.
It only need to checkout latest MW and regenerate the documentation, this is so simple you could even have multiple of these interfaces and everyone could pick what they like
On Sat, Jul 6, 2013 at 10:19 AM, Antoine Musso hashar+wmf@free.fr wrote:
Le 06/07/13 02:36, Yuvi Panda a écrit :
Hello! Our current generated documentation[1] uses doxygen, and leaves... a number of things to be desired - such as:
- Not be tortoise slow
I have originally migrated from PHPDoc to Doxygen because it was blazing fast to generate doc. Doxygen also supports several languages, so if we came adding a second language, we could have used the same documentation generator. History show that JavaScript is better documented using JSDuck: https://doc.wikimedia.org/mediawiki-core/master/js/
It does manpages as well :-) But we can probably live without it.
From time to time, I look at other documentation generator for PHP language. All ends up eating all memory and being painfully slow to generate the doc when they don't cause a segfault.
- Have usable search
Doxygen has an EXTERNAL_SEARCH configuration that makes it generate an XML file which could probably get indexed somehow in Solr. SEARCHENGINE_URL would point to the search instance.
- Prettier interface
Some CSS loves is needed :) It can definitely be made as shown on: http://www.openfoam.org/docs/cpp/
Kde adapted it as well: http://api.kde.org/4.x-api/kde-baseapps-apidocs/kate/part/html/hierarchy.htm...
I was looking around for alternatives, and ran into phpdocumentor2[2]. The project still seems active (latest commit was 3 days ago, and for vagrant support!), and the demo was quite pretty:
http://demo.phpdoc.org/Responsive/namespaces/phpDocumentor.html
Is there any particular reason we are still sticking with doxygen? Or is it just 'someone needs to find the time to move things over to the new system'?
There is also Sami used by Symfony: Example: http://api.symfony.com/2.3/index.html Code: https://github.com/fabpot/sami
And apigen https://github.com/apigen/apigen
-- Antoine "hashar" Musso
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
wikitech-l@lists.wikimedia.org