Add more details to documentation about version changes

[OrangeChannel]

Not really needed as we also have a more detailed changelog but this can be seen all over the Python library docs and looks nice anyways. Since this repo almost serves as an ideal way to package and document a vapoursynth package, can't hurt to include some more sphinx features that others could use.

Once the doodle1 audio support branch gets merged, we can also include a .. note:: or .. deprecated:: for vsutil.split() since for most uses, using the new std.SplitPlanes function should be preferred.

We might also want to include a .. warning:: about vsutil.get_w() not guaranteed to return a mod2/4 resolution since that seems to be a thing other *func.py's are doing but this should be pretty straightforward with the only_even param.

As a note, there needs to be blank line underneath the auto*:: directives before using one of these paragraph-level directives because it breaks the docs otherwise. Other docs (like the python stdlib) don't do this because it seems to only be a thing when using the autodoc directives, and the Python docs and a lot of other projects don't use these.

Live version at https://vsutil-orangechannel.readthedocs.io/en/even_better_docs/api.html

[FichteFoll]

but this should be pretty straightforward with the only_even param

That parameter makes it obvious enough in my books.

Is there a particular reason why you didn't include these directives in the docstrings? Those already use sphinx/reST features and it keeps this information to one place, i.e. the definition itself.

[OrangeChannel]

Hmm, no particular reason, though since this stuff is only relevant to the built docs, I though it would fit better on the doc files.

I tried adding them in the docstrings and there's a bit of an unwanted behavior with the decorator docstrings/return types.

This is with the directive in the rst files

And this is with it defined at the very bottom of the docstring with a blank line above:

It only affects the decorators since we don't have proper docstrings for them with :param: and :return: while the other functions have the same behavior on both builds: in the rst /// in the docstrings

It's already been reported to the typehinting extension but I don't know if this will be changed/fixed: https://github.com/agronholm/sphinx-autodoc-typehints/issues/75#issuecomment-530344805

I think it's best to keep them in the API doc files since they look a bit odd in the docstrings (and the stuff above) and makes more sense to me adding them to the rst files when a release gets made as opposed to adding them in the docstrings.

[FichteFoll]

Well, it's fine to me either way, I was just curious about your motivation.

[kageru]

I don’t think this adds much value, but it’s another point for documentation that has to be maintained (or, more realistically, will be neglected).