Moving on from Doxygen?

classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

Moving on from Doxygen?

Yuvi Panda
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

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Moving on from Doxygen?

Tyler Romeo
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 | [hidden email]


On Fri, Jul 5, 2013 at 8:36 PM, Yuvi Panda <[hidden email]> wrote:

> 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
>
> _______________________________________________
> Wikitech-l mailing list
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Moving on from Doxygen?

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

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

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

> 3. 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 <[hidden email]> 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 | [hidden email]
>
>
> On Fri, Jul 5, 2013 at 8:36 PM, Yuvi Panda <[hidden email]> wrote:
>
> > 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
> >
> > _______________________________________________
> > Wikitech-l mailing list
> > [hidden email]
> > https://lists.wikimedia.org/mailman/listinfo/wikitech-l
> _______________________________________________
> Wikitech-l mailing list
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l
>
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Moving on from Doxygen?

Matthew Walker
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 <[hidden email]>wrote:

> 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)...
>
> > 1. 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.
>
> > 2. 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.
>
> > 3. 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 <[hidden email]> 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 | [hidden email]
>>
>>
>> On Fri, Jul 5, 2013 at 8:36 PM, Yuvi Panda <[hidden email]> wrote:
>>
>> > 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
>> >
>> > _______________________________________________
>> > Wikitech-l mailing list
>> > [hidden email]
>> > https://lists.wikimedia.org/mailman/listinfo/wikitech-l
>> _______________________________________________
>> Wikitech-l mailing list
>> [hidden email]
>> https://lists.wikimedia.org/mailman/listinfo/wikitech-l
>>
>
>
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Moving on from Doxygen?

Yuvi Panda
In reply to this post by Matthew Walker
On Sat, Jul 6, 2013 at 6:36 AM, Matthew Walker <[hidden email]> wrote:
>> 1. 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'

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

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

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Moving on from Doxygen?

Yuvi Panda
In reply to this post by Matthew Walker
On Sat, Jul 6, 2013 at 6:41 AM, Matthew Walker <[hidden email]> 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

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Moving on from Doxygen?

Brian Wolff
In reply to this post by Yuvi Panda
On 7/5/13, Yuvi Panda <[hidden email]> wrote:

> On Sat, Jul 6, 2013 at 6:36 AM, Matthew Walker <[hidden email]>
> wrote:
>>> 1. 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

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

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Moving on from Doxygen?

Jan Nieuwenhuizen
In reply to this post by Yuvi Panda
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

> 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
>
> _______________________________________________
> Wikitech-l mailing list
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l

--
Jan Nieuwenhuizen <[hidden email]> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar®  http://AvatarAcademy.nl 

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Moving on from Doxygen?

Antoine Musso-3
In reply to this post by Yuvi Panda
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:
>
> 1. 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.

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

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


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

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
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Moving on from Doxygen?

Petr Bena
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 <[hidden email]> 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:
>>
>> 1. 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.
>
>> 2. 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.
>
>> 3. 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.html
>
>
>> 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/
>
> 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
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Moving on from Doxygen?

Tim Starling-2
In reply to this post by Brian Wolff
On 06/07/13 12:02, Brian Wolff wrote:

> On 7/5/13, Yuvi Panda <[hidden email]> wrote:
>> On Sat, Jul 6, 2013 at 6:36 AM, Matthew Walker <[hidden email]>
>> wrote:
>>>> 1. 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



_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l