On Wed, Feb 18, 2015 at 12:59 PM, Gordon Sim <g...@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. >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. --Rafael
