[katello-devel] API documentation proposal

[Ivan Nečas]

On 05/04/2012 09:04 AM, Ivan Nečas wrote:
> On 05/03/2012 10:58 PM, Eric Helms wrote:
>> Inecas -
>>
>> I thought I read this supports direct HTML and Markdown. Does it also 
>> support output in RST format?
> Not now. Generally it supports every markup language that has it's 
> binding to Ruby, however I was not able to find a suitable one for 
> RST. The main problem would be with the long descriptions of actions 
> and resources: you write it in markup language you like (RDoc, 
> Textile, Markdown) and the library generates a HTML from that to be 
> able to serve it directly to the browser. So it's not a problem to 
> write the documentaion in Markdown and then export the whole thing 
> like Markdown. However to be able to export it to RST, it's reasonable 
> to write the docs itself in RST (to avoid transforming Markdown or 
> whatever to RST, not that it would be impossible but it's just not 
> necessary). And here is the problem that comparing to Markdown, RST 
> support in Ruby seems quite poor.
>
> There is also another reason why I would vote for Markdown: it's 
> support on Github (if we plan to stay there for a while), Markdown is 
> the first-class citizen there and the knowledge of its syntax is IMO 
> more spread than RST, which is very good property of a markup language.
I see, the Sphinx requires RST. I've found a tool that would enable 
rest-api supporting RST (and bunch of other formats),  so it would be no 
problem to get the output in RST.  One thing that we need to improve is 
production environment: we should avoid processing the markup on startup 
of the server but instead let it pre-generate in build phase. If nothing 
else: to reduce the production dependencies.
>
> -- Ivan
>>
>> - Eric
>>
>> On 05/03/2012 01:05 PM, Bryan Kearney wrote:
>>> This looks great. If it is easy to integrate, then I would suggest 
>>> we do so. What is the psosibility to export this in some format? I 
>>> will get flogged, but XML would be great to turn it into doco we 
>>> could load into the wiki page.
>>>
>>> -- bk
>>>
>>> _______________________________________________
>>> katello-devel mailing list
>>> katello-devel at redhat.com
>>> https://www.redhat.com/mailman/listinfo/katello-devel
>>
>> _______________________________________________
>> katello-devel mailing list
>> katello-devel at redhat.com
>> https://www.redhat.com/mailman/listinfo/katello-devel
>
>


-- 
Ivan