Add some docstrings for Frame base class

[jlaine]

This PR adds docstrings for the Frame base class, notably about timestamps.

I couldn't figure out how to document index and planes which are defined in the .pxd file, any hints?

[jlaine]

Let me know whether you have a preference as to whether or not I should include the :type: for each property. Thanks!

[mikeboers]

Cherry-picked onto develop.

I like being more specific by having the :type:, even though the template is rendering that page not very nicely.

I also want to look into hosting multiple versions of the docs, cause I didn't just build and deploy it cause I'm not going to necessarily cut a new release into PyPI right away.

[jlaine]

readthedocs.org handles a "latest" and "stable" out of the box and I'm almost sure you can add more versions.

Sad to hear no pypi release in sight, I could have done with the timestamp fixes for a MediaPlayer class I'm adding to my WebRTC implementation:

https://github.com/jlaine/aiortc/blob/48ea3aa6f27c4f999937d24b0213c44c3dd7b394/aiortc/contrib/media.py#L190

Anything I can do to help push out a minor release?

[mikeboers]

I've moved the docs to my own hosting, and wrote a tiny Javascript thing to add a Dropdown at the top. See http://docs.mikeboers.com/pyav/develop/

This project would be far too hard to get to build on RTD, that I gave up long ago.

I suppose you've already done a ton to help push out a release, because so much more passes now, right? With that being the case, there isn't really anything stopping me from doing it...

[jlaine]

Very cool! Next on my list is:

• contributing some examples to the docs especially for reading audio/video using PyAV

• contributing more docstrings. I don't know if you saw my question about how to document properties defined in .pxd files?

• I've been reading up on cython and it would seem we can / are encouraged to use normal @Property / @propname.setter syntax. Do we want a global pass on this?

[mikeboers]

You're my hero.

1. Examples. The examples directory is there, but many of them are way too heavy with diagnostic stuff because I use them while developing. I was hoping to start putting lots of simpler focused examples in docs/examples.

I'm not keen on the current setup with the testcode blocks, as I don't get highlighting over here, and I can't run them, etc.. I was thinking of making a directive to include a Python file, and scrub out common stuff that we don't need to see in the docs (e.g. import av, or even larger blocks of setup.)

2. I don't know if I saw the thing about PXD docstrings. So many notifications! Ah! Please feel free to email me at mail-at-mikeboers.com if you want.

3. As long as we don't have to raise the Cython version bar (which I just set to 0.27), then I'm all for a pass for the new syntax. One less thing for people to learn about Cython!