Documentation could be more eloquent on python side

[GDelevoye]

Hello !

I could not make anything work for a whole afternoon just because I missed this sentence in the README

then open a Python shell in the same folder and you'll be able to import string_sum.

But before that, I really cursed my computer like "How can it be that a a package aimed at extending python doesn't even include a single python line in its doc ?"

Probably there are many people like me who focus more on the code examples than plain text in documentations, so maybe after the whole rust code example in the README, it could be a cool idea to put a clear and example on how the module can be used from the python side:

>>> import mymodule
>>> mymodule.myfunction()

Because once you know it it seems very trivial. But for a new user like me, I didn't even dream it could be so simple :)

It's a great feature that maybe you should advertize more. It took me ~1 day to chose which tool I'd use to interface my rust code with my python code, and one supplemental afternoon to make PyO3 work... It's not much, but it could have been reduced to 5 mn if the two python lines above were put in the doc, and maybe I'm not the only one in this case :)

That being said pyO3 is an incredible package, thank you all for developping it

[davidhewitt]

Hi, thanks for the feedback, I agree the frontpage readme needs work. It's actually top of my list of things I still want to do for the 0.14 release (#1570 )

I'm sorry that this caused you lost time in the meanwhile because I didn't manage to get to this sooner.

[GDelevoye]

Thanks David, I didn't see #1570, so I apologize

[davidhewitt]

No problem - I'll keep this issue open as it's a nice example of the kinds of things that the current README does not explain well, and close it once I've had a chance to write documentation.

[davidhewitt]

I think there's been a lot of documentation imprivemo and additional examples added to the guide since there was last discussion on this thread, so I'm going to claim we've improved things enough and close this one.