Fixes #401 Networking capabilities should be documented

[mothslaw]

Context:

Our docs currently do not mention networking at all.

This diff adds a "best practices" page about networking.

Problem:

Plugin writers today can't find out info about when they can/cannot use the network.

Solution:

Gave a quick explanation of when network access is possible, with a couple of tips for how to best do networking in a plugin context.

Testing

Set up a local docs server and read through the new changes.

Notes To Reviewers:

Since this makes no functional change, this should count as a "patch" for purposes of bumping the version. Therefore, I ran "bumpversion patch", as this is the first change after an official release. Thus the version moves from 3.1.0 to 3.1.1.dev0.

I think Kurt will very soon be adding other changes that will bump the minor version (to 3.2.0) and therefore we'll never actually release a 3.1.1. Still, I think that 3.1.1.dev0 is the right thing to do for this diff.

Future work:

Although I added stuff about strings (see below), there is more work that could be done here. This additional work is covered by Issue #385.

Bonus:

I also added some more doc improvements, based on recent discussions with plugin developers:

• Notes about interpreter lifetimes.
• Notes about which libraries/modules are available
• Much more information about string processing/handling in a plugin context.
• My editor auto-removed some unnecessary whitespace at the end of some lines.

[ankursarin]

should we tell them that they can use any linux x86 compatible libraries?

[mothslaw]

I was a little torn on this. I thought there were probably two good options:

1. Leave it vague like this. This gives enough clues to people who know what they're doing so that they know that they need to match architectures of binaries. This doesn't really help people who don't already know about binary packages and/or cross-compilation of source code, though.

2. Put in a ton more information, including examples. This would hopefully give everyone enough information to do what they need to do.

For now, I thought (1) was okay. I figured that we were likely going to be closing in on a real supported solution for 3rd-party libraries soon... and at that point we could expand this doc into something more generally useful.

What do you think?

[ankursarin]

should we move this to the code sharing best practices section?

[mothslaw]

Today, the "code sharing" section really doesn't talk about 3rd-party code at all. It's focused on how plugin code can be broken up into separate modules.

So, my thinking here was...

• That code sharing section can stay as-is for now.
• This new section is a kind of "stub" where we say that we don't really support 3rd-party code yet, but if you need it anyhow, here's how you can hack it.
• Soon, we'll really support 3rd-party code, and this stub can be replaced with its own page describing whatever we settle on as the recommended way to do it.

I do think that at least a link from code sharing back to this section would be good, though. I can add that.

[mothslaw]

Added the link. Let me know if you think the rest is okay.

[kurthdelphix]

Based on my recent experience, bumping the version will affect the QA blackbox tests AFAIK, maybe you would find it easier to wait for my changes to go in and leverage that version change.

[jeffngo]

Looks good to me... especially the page on python strings. That was a good read.