On 02/18/2015 11:33 PM, Rafael Schloming wrote:
On Wed, Feb 18, 2015 at 12:59 PM, Gordon Sim <[email protected]> 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: [email protected]
For additional commands, e-mail: [email protected]
