Re: [proton]: docs for python reactive api

[Gordon Sim <gs...@redhat.com>]

On 02/18/2015 11:33 PM, Rafael Schloming wrote:
> On Wed, Feb 18, 2015 at 12:59 PM, Gordon Sim <gs...@redhat.com> wrote:
>
>> I've made a start on some documentation for the reactive python api. This
>> consists of an updated version of the tutorial that lived alongside the
>> examples when they were in a separate branch, and a start at an overview of
>> the model and key classes involved. I used sphinx for this as it provided
>> some helpful tools like the ability to include text from the actual
>> examples (avoiding copying the text and the associated pitfalls).
>>
>> Initially I put it in the top level docs directory as that was what I
>> first noticed. However I now see there is also a docs directory under
>> proton-c. So where would be the best place to house this, assuming there
>> are no objections to including it in the current tree? Should it be the top
>> level docs dir? The one under proton-c? Something new under
>> proton-c/bindings/python? include it in examples/python ?
>>
>
> Is it pure tutorial or does it include API docs? From a build/structural
> perspective if it includes API docs I would think it needs to live under
> proton-c/bindings/python, however if it's just pure tutorial then probably
> living alongside the examples make sense as the doc and the examples will
> presumably be somewhat interdependent, especially if the docs actually
> include snippets from the real examples.

It has a bit of both. As well as the tutorial there is the beginnings of 
a short overview section. Both this and the tutorial link in places to 
some selected class reference docs. I also included some autogenerated 
docs of the full api, but that was really just an experiment at this 
stage and we may not want to use that in the end (I had to disable a 
couple of classes dues to errors).

I went ahead and committed the start of the work under 
proton-c/bindings/python/docs. That seems the least annoying place at 
present and as you say we can always revise as we build out more 
comprehensive docs across languages etc.

>  From a navigational perspective I think we should feature it fairly
> prominently though, e.g. replace what is in the top level docs directory
> with some sort of more useful overview and have an easy path to the
> tutorial and api docs for various languages.
>
>
>> I've attached a patch with what I have to date. I need to integrate the
>> sphinx build process into cmake somehow, which will be the next step, but
>> there is also plenty more to do on the content itself. If we agree it can
>> go into the tree and agree where it should go, then I'll commit the content
>> as I work on improving it to allow others to follow or join in more easily
>> if they wish.
>>
>
> I haven't looked at the patch in detail, but honestly I'd just go ahead.
> It's not like the current doc structure is super well thought out. I would
> like to be able to use sphinx for the reactor examples also, so I'm
> certainly eager to see that integrated into the build.

I've still not got that done yet, but its on my list and will get there 
soon.

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org