examples from existing project documentation are not easily used

[Robert Collins]

 affects acire
 done

Short story: acire would benefit by having a way to sync/pull in
examples from other projects (e.g. bzr) where developers have already
written examples. For details see the IRC log below.

In terms of implementing this, I would start by writing a small, generic
interface 'pull-examples', and then implement that interface for each
project I want to snarf examples from. Its so minimal I'd almost just
use a callable.

e.g. in some python file.

snarfers = []
def snarf_bzrlib():
    """snarf bzrlibs integration examples."""
    # code here
snarfers.append(snarf_bzrlib)

def snarf_examples():
    """Update the examples for projects that have them."""
    for snarfer in snarfers:
        snarfer()

-------------------------
10:51 < jono_> lifeless, I would just like to see a collection of
examples in
https://code.edge.launchpad.net/~jonobacon/python-snippets/trunk
10:51 < jono_> I just added one for checking out a branch
10:51 < jono_> and then people can view them with Acire
10:55 -!- komputes [~komputes@ubuntu/member/komputes] has quit [Read
error: Connection reset by peer]
10:56 -!- _Groo_ [~[e-mail]] has quit
[Remote host closed the connection]
10:58 < lifeless> jono_: some things you may find useful -
10:58 < lifeless> http://people.canonical.com/~mwh/bzrlibapi/
10:59 < lifeless>
http://doc.bazaar.canonical.com/bzr.dev/developers/integration.html
10:59 < lifeless> jono_: I think it would be a shame to end up with two,
separate sets of docs for doing stuff with bzrlib
10:59 < lifeless> jono_: why can't Acire look at our existing docs?
11:00 -!- poolie [~mbp@canonical/launchpad/poolie] has quit [Quit:
Leaving.]
11:00 < jono_> well python-snippets is not for docs, it is just a
library that aggregates examples
11:00 < lifeless> jono_: the second link is probably more the sort of
thing you're looking f or
11:00 < lifeless> that page is full of examples
11:00 < jono_> so if you are a developer you have a regularly growing
library of examples to lean on
11:00 < jono_> sure, and it would be great to put those examples in
python-snippets
11:01 < lifeless> jono_: I think it would be better to have acire pull
them in automatically.
11:01 < lifeless> jono_: rather than duplicating content, which can then
go stale.
11:01 -!- jibel [~j-lalleme@2a01:e35:2e17:46e0:21d:e0ff:fe3a:b40d] has
quit [Quit: Ex-Chat]
11:01 < lifeless> jono_: I can file a bug for you, if you like.
11:01 < jono_> lifeless, how could that work for any project?
11:01 < jono_> lifeless, write a patch, that would be better ;-)
11:01 < lifeless> jono_: I don't know, I'm not an Acire developer ;)
11:01 < jono_> I don't think it would be possible in a generic
11:02 < jono_> way
11:02 < jono_> if you don't want to contribute the examples, thats fine
11:02 < jono_> I just think it will help people get started quicker
11:02 < lifeless> jono_: uhm, I don't think we're communicating
effectively
11:02 < lifeless> I know of the acire project - its a nice idea.
11:02 < jono_> right
11:03 < lifeless> and you're welcome to take the examples we've written
already. I think that that creates a problem for acire though
11:03 -!- Philip5 [~Philip@ubuntu/member/philip5] has quit [Remote host
closed the connection]
11:03 < lifeless> the problem is that you have to sync on an ongoing
basis
11:03 < lifeless> or the examples will stop working
11:03 < lifeless> it also means that patches to the bzrlib docs to
improve this may end up going to acire instead
11:03 < lifeless> I don't think either of those things are desirable.
11:04 < jono_> lifeless, I agree with the problem, I just don't know
what the solution is :)
11:04 < jono_> I suspect that if python-snippets gains momentum, people
will fix the examples
11:04 < jono_> that has happened so far
11:04 < lifeless> so, if you agree with the problem, I can file a bug.
That records the problem and perhaps someone with an interest can
implement a solution.
11:04 < jono_> I would love a way to pull in snippets automatically tbh
11:04 < jono_> sure :)
11:04 < lifeless> I can suggest techniques to do pull-ins for you
11:05 < lifeless> its not conceptually hard
11:05 < jono_> cool
11:05 < jono_> :)
11:05 < lifeless> lp:acire ?
11:05 < jono_> yep

[Jono Bacon (jonobacon)]

I think this would be a great additional tool for gathering snippets to pull in python-snippets: kind of like a crawler for snippets.