View mode: basic / threaded / horizontal-split · Log in · Help
January 27, 2008
Descent and gotoapi
Hi,

Guillaume mentioned the "gotoapi" on another thread. Seems like a useful 
resource for D libraries too, and can be customized here: 
http://www.gotapi.com/contribute/

My questions is this: since Descent can internally infer the public API of a 
D library, could it be adjusted to also generate the kind of XML tagging 
required by gotoapi?

- Kris
January 27, 2008
Re: Descent and gotoapi
The API provided by Descent includes top level members like classes, 
structs, functions, templates, etc. For each of these you can get a lot 
of information also, like which is the base class of a class, and which 
interfaces it implements, or which is the return type of a method and 
the types of the parameters, etc. (though this functionality is only 
present in the trunk revision, not in 0.4).

So writing a plugin that generates the files required by gotoapi should 
be very, very simple. No changes are required in Descent. :-)

If anyone is interested in doing it, I can give help on how to write an 
Eclipse plugin, and which are the important classes/packages needed to 
do it.

Kris escribió:
> Hi,
> 
> Guillaume mentioned the "gotoapi" on another thread. Seems like a useful 
> resource for D libraries too, and can be customized here: 
> http://www.gotapi.com/contribute/
> 
> My questions is this: since Descent can internally infer the public API of a 
> D library, could it be adjusted to also generate the kind of XML tagging 
> required by gotoapi?
> 
> - Kris
January 28, 2008
Re: Descent and gotoapi
Ary Borenszweig wrote:
> The API provided by Descent includes top level members like classes, 
> structs, functions, templates, etc. For each of these you can get a lot 
> of information also, like which is the base class of a class, and which 
> interfaces it implements, or which is the return type of a method and 
> the types of the parameters, etc. (though this functionality is only 
> present in the trunk revision, not in 0.4).
> 
> So writing a plugin that generates the files required by gotoapi should 
> be very, very simple. No changes are required in Descent. :-)
> 
> If anyone is interested in doing it, I can give help on how to write an 
> Eclipse plugin, and which are the important classes/packages needed to 
> do it.
> 
> Kris escribió:
>> Hi,
>>
>> Guillaume mentioned the "gotoapi" on another thread. Seems like a 
>> useful resource for D libraries too, and can be customized here: 
>> http://www.gotapi.com/contribute/
>>
>> My questions is this: since Descent can internally infer the public 
>> API of a D library, could it be adjusted to also generate the kind of 
>> XML tagging required by gotoapi?
>>
>> - Kris

Actually, I can take a break from the unit test stuff (that's not useful 
without a builder anyway) and work on a documentation generation system 
that has interlinks. Would it be more useful to have that or the gotapi?
January 28, 2008
Re: Descent and gotoapi
"Robert Fraser" <fraserofthenight@gmail.com> wrote in message 
news:fnjt4u$2t5p$1@digitalmars.com...
> Ary Borenszweig wrote:
>> The API provided by Descent includes top level members like classes, 
>> structs, functions, templates, etc. For each of these you can get a lot 
>> of information also, like which is the base class of a class, and which 
>> interfaces it implements, or which is the return type of a method and the 
>> types of the parameters, etc. (though this functionality is only present 
>> in the trunk revision, not in 0.4).
>>
>> So writing a plugin that generates the files required by gotoapi should 
>> be very, very simple. No changes are required in Descent. :-)
>>
>> If anyone is interested in doing it, I can give help on how to write an 
>> Eclipse plugin, and which are the important classes/packages needed to do 
>> it.
>>
>> Kris escribió:
>>> Hi,
>>>
>>> Guillaume mentioned the "gotoapi" on another thread. Seems like a useful 
>>> resource for D libraries too, and can be customized here: 
>>> http://www.gotapi.com/contribute/
>>>
>>> My questions is this: since Descent can internally infer the public API 
>>> of a D library, could it be adjusted to also generate the kind of XML 
>>> tagging required by gotoapi?
>>>
>>> - Kris
>
> Actually, I can take a break from the unit test stuff (that's not useful 
> without a builder anyway) and work on a documentation generation system 
> that has interlinks. Would it be more useful to have that or the gotapi?

Descent is the best! :)

Interlinked doc would likely be more valuable to Tango at this time, since 
it can presumeably be hosted anywhere? But it's your call. I guess there 
might be more "presentation" style effort in the interlinked stuff, while 
gotoapi would be free of such concerns?

- Kris
January 28, 2008
Re: Descent and gotoapi
Kris wrote:
> "Robert Fraser" <fraserofthenight@gmail.com> wrote in message 
> news:fnjt4u$2t5p$1@digitalmars.com...
>> Ary Borenszweig wrote:
>>> The API provided by Descent includes top level members like classes, 
>>> structs, functions, templates, etc. For each of these you can get a lot 
>>> of information also, like which is the base class of a class, and which 
>>> interfaces it implements, or which is the return type of a method and the 
>>> types of the parameters, etc. (though this functionality is only present 
>>> in the trunk revision, not in 0.4).
>>>
>>> So writing a plugin that generates the files required by gotoapi should 
>>> be very, very simple. No changes are required in Descent. :-)
>>>
>>> If anyone is interested in doing it, I can give help on how to write an 
>>> Eclipse plugin, and which are the important classes/packages needed to do 
>>> it.
>>>
>>> Kris escribió:
>>>> Hi,
>>>>
>>>> Guillaume mentioned the "gotoapi" on another thread. Seems like a useful 
>>>> resource for D libraries too, and can be customized here: 
>>>> http://www.gotapi.com/contribute/
>>>>
>>>> My questions is this: since Descent can internally infer the public API 
>>>> of a D library, could it be adjusted to also generate the kind of XML 
>>>> tagging required by gotoapi?
>>>>
>>>> - Kris
>> Actually, I can take a break from the unit test stuff (that's not useful 
>> without a builder anyway) and work on a documentation generation system 
>> that has interlinks. Would it be more useful to have that or the gotapi?
> 
> Descent is the best! :)
> 
> Interlinked doc would likely be more valuable to Tango at this time, since 
> it can presumeably be hosted anywhere? But it's your call. I guess there 
> might be more "presentation" style effort in the interlinked stuff, while 
> gotoapi would be free of such concerns?
> 
> - Kris 
> 
> 

I was thinking that I would generate docs as closely to the Ddoc format 
as possible (including parsing macros & all that good stuff). But the 
gotapi might still be useful since everything is listed and searchable, 
right? I think the gotapi thing is better as a separate plugin, though.

We should move this convo to IRC, but if I did that, my chances of 
finishing my homework would be shot for tonight.
January 28, 2008
Re: Descent and gotoapi
"Robert Fraser" <fraserofthenight@gmail.com> wrote...
[snip]
> I was thinking that I would generate docs as closely to the Ddoc format as 
> possible (including parsing macros & all that good stuff). But the gotapi 
> might still be useful since everything is listed and searchable, right? I 
> think the gotapi thing is better as a separate plugin, though.
>
> We should move this convo to IRC, but if I did that, my chances of 
> finishing my homework would be shot for tonight

<g> maybe catch you tomorrow, and thanks!
January 28, 2008
Re: Descent and gotoapi
Robert Fraser wrote:

> Kris wrote:
>> "Robert Fraser" <fraserofthenight@gmail.com> wrote in message
>> news:fnjt4u$2t5p$1@digitalmars.com...
>>> Ary Borenszweig wrote:
>>>> The API provided by Descent includes top level members like classes,
>>>> structs, functions, templates, etc. For each of these you can get a lot
>>>> of information also, like which is the base class of a class, and which
>>>> interfaces it implements, or which is the return type of a method and
>>>> the types of the parameters, etc. (though this functionality is only
>>>> present in the trunk revision, not in 0.4).
>>>>
>>>> So writing a plugin that generates the files required by gotoapi should
>>>> be very, very simple. No changes are required in Descent. :-)
>>>>
>>>> If anyone is interested in doing it, I can give help on how to write an
>>>> Eclipse plugin, and which are the important classes/packages needed to
>>>> do it.
>>>>
>>>> Kris escribió:
>>>>> Hi,
>>>>>
>>>>> Guillaume mentioned the "gotoapi" on another thread. Seems like a
>>>>> useful resource for D libraries too, and can be customized here:
>>>>> http://www.gotapi.com/contribute/
>>>>>
>>>>> My questions is this: since Descent can internally infer the public
>>>>> API of a D library, could it be adjusted to also generate the kind of
>>>>> XML tagging required by gotoapi?
>>>>>
>>>>> - Kris
>>> Actually, I can take a break from the unit test stuff (that's not useful
>>> without a builder anyway) and work on a documentation generation system
>>> that has interlinks. Would it be more useful to have that or the gotapi?
>> 
>> Descent is the best! :)
>> 
>> Interlinked doc would likely be more valuable to Tango at this time,
>> since it can presumeably be hosted anywhere? But it's your call. I guess
>> there might be more "presentation" style effort in the interlinked stuff,
>> while gotoapi would be free of such concerns?
>> 
>> - Kris
>> 
>> 
> 
> I was thinking that I would generate docs as closely to the Ddoc format
> as possible (including parsing macros & all that good stuff). But the
> gotapi might still be useful since everything is listed and searchable,
> right? I think the gotapi thing is better as a separate plugin, though.
> 
> We should move this convo to IRC, but if I did that, my chances of
> finishing my homework would be shot for tonight.

I chatted with Ary earlier today - I don't think Descent generated API docs
can ever be a permanent solution for Tango as we want to be able to have it
part of the various scripts, both for releases and continously updated on
server for trunk. For that I hope that someone would tackle rebuild to do
the same, or for dil to suddenly be complete compiler <g>.

So maybe gotapi should have higher priority, at least from the above
perspective.

-- 
Lars Ivar Igesund
blog at http://larsivi.net
DSource, #d.tango & #D: larsivi
Dancing the Tango
January 29, 2008
Re: Descent and gotoapi
Lars Ivar Igesund wrote:
> 
> I chatted with Ary earlier today - I don't think Descent generated API
> docs can ever be a permanent solution for Tango as we want to be able to
> have it part of the various scripts, both for releases and continously
> updated on server for trunk. For that I hope that someone would tackle
> rebuild to do the same, or for dil to suddenly be complete compiler <g>.
> 
> So maybe gotapi should have higher priority, at least from the above
> perspective.
> 

Hi,

Beside D, my other favorite language is Ruby so I've made a little Ruby
script (see attachment) that can parse the Tango HTML documentation and
create a XML file for gotapi. (If there was an HTML parser like Hpricot in
D, I would have done it in D!) But, I have no idea if the XML will be
accepted or not like it is by gotapi. Anyway, it's a good start.

To use the script, you need Ruby and then you can install Hpricot with "gem
install hpricot". You can then run the Ruby script like this:

ruby TangoDocToXML.rb > TangoDoc.xml

The XML is big so I won't attach it... but don't run it too often because
it downloads the HTML pages from dsource! It would be better to parse local
documentation but I don't have it...

Also, there are errors in the HTML file for tango.core.Variant and
tango.util.Convert so they are explicitly excluded by the script.

Hope this helps!

Guillaume
January 29, 2008
Re: Descent and gotoapi
Guillaume B. wrote:

> Lars Ivar Igesund wrote:
>> 
>> I chatted with Ary earlier today - I don't think Descent generated API
>> docs can ever be a permanent solution for Tango as we want to be able to
>> have it part of the various scripts, both for releases and continously
>> updated on server for trunk. For that I hope that someone would tackle
>> rebuild to do the same, or for dil to suddenly be complete compiler <g>.
>> 
>> So maybe gotapi should have higher priority, at least from the above
>> perspective.
>> 
> 
>  Hi,
> 
>  Beside D, my other favorite language is Ruby so I've made a little Ruby
> script (see attachment) that can parse the Tango HTML documentation and
> create a XML file for gotapi. (If there was an HTML parser like Hpricot in
> D, I would have done it in D!) But, I have no idea if the XML will be
> accepted or not like it is by gotapi. Anyway, it's a good start.
> 
>  To use the script, you need Ruby and then you can install Hpricot with
>  "gem
> install hpricot". You can then run the Ruby script like this:
> 
> ruby TangoDocToXML.rb > TangoDoc.xml
> 
>  The XML is big so I won't attach it... but don't run it too often because
> it downloads the HTML pages from dsource! It would be better to parse
> local documentation but I don't have it...
> 
>  Also, there are errors in the HTML file for tango.core.Variant and
> tango.util.Convert so they are explicitly excluded by the script.
> 
>  Hope this helps!
> 
>  Guillaume

We will have to try this out. Thank you very, very much :)

-- 
Lars Ivar Igesund
blog at http://larsivi.net
DSource, #d.tango & #D: larsivi
Dancing the Tango
January 29, 2008
Re: Descent and gotoapi
Lars Ivar Igesund wrote:

> Robert Fraser wrote:
> 
>> Kris wrote:
>>> "Robert Fraser" <fraserofthenight@gmail.com> wrote in message
>>> news:fnjt4u$2t5p$1@digitalmars.com...

>>>> Actually, I can take a break from the unit test stuff (that's not
>>>> useful without a builder anyway) and work on a documentation generation
>>>> system that has interlinks. Would it be more useful to have that or the
>>>> gotapi?
>>> 
>>> Descent is the best! :)
>>> 
>>> Interlinked doc would likely be more valuable to Tango at this time,
>>> since it can presumeably be hosted anywhere? But it's your call. I guess
>>> there might be more "presentation" style effort in the interlinked
>>> stuff, while gotoapi would be free of such concerns?
>>> 
>>> - Kris
>>> 
>>> 
>> 
>> I was thinking that I would generate docs as closely to the Ddoc format
>> as possible (including parsing macros & all that good stuff). But the
>> gotapi might still be useful since everything is listed and searchable,
>> right? I think the gotapi thing is better as a separate plugin, though.
>> 
>> We should move this convo to IRC, but if I did that, my chances of
>> finishing my homework would be shot for tonight.
> 
> I chatted with Ary earlier today - I don't think Descent generated API
> docs can ever be a permanent solution for Tango as we want to be able to
> have it part of the various scripts, both for releases and continously
> updated on server for trunk. For that I hope that someone would tackle
> rebuild to do the same, or for dil to suddenly be complete compiler <g>.
> 
> So maybe gotapi should have higher priority, at least from the above
> perspective.
> 

Considering Guillaume's gotapi contribution, just completely ignore the
above. I was probably just selfish in any case :)

-- 
Lars Ivar Igesund
blog at http://larsivi.net
DSource, #d.tango & #D: larsivi
Dancing the Tango
Top | Discussion index | About this forum | D home