Improve Python reference documentation

[JeanChristopheMorinPerso]

Link the Issue(s) this Pull Request is related to.

Relates to #704 (and maybe others, I haven't searched extensively).

Summarize your change.

This PR refreshes the Python API reference documentation.

The rendered version can be found at https://jcmorin-opentimelineio.readthedocs.io/en/latest/index.html.

Changes are:

1. Addition of new docstrings (some from the previous Python implementation and some from me).
2. Move from running the sphinx-apidoc command to using sphinx.ext.autosummary. This gives better control over the generated documentation and improves the user experience.
3. The left menu in the docs is now organized in labelled categories. This is a small improvement, but it makes a huge readability/discover-ability improvements.
   
4. Cleanup of the Sphinx configuration file to follow best practices established by the Sphinx community (only set the necessary settings, link to Sphinx docs instead of duplicating documentation of each setting, etc).
5. The docstrings generated by Pybind11 are now cleaned up by post-processors in Sphinx.
   • The self argument is stripped off as it's useless.
   • Overloads are properly handled and displayed in the rendered HTML.
6. Now using intersphinx to link to the python.org docs.
7. Switch the the newest ReadTheDocs config format.
8. Updated Python version used in ReadTheDocs to 3.10.
9. Added the spatial coordinates doc to the main doctree.
10. Simplified the build process a little bit.
11. Switched to https://myst-parser.readthedocs.io/en/latest/index.html since recommonmark is deprecated.
12. Dependencies needed to build the docs are now specified in docs/requirements.txt.
13. New GitHub Actions workflow that checks that all links are working and also checks that there is no warnings or errors when building the docs.

[jminor]

This is amazing! I made some edits in several places that will hopefully make some things more clear.

[codecov-commenter]

Codecov Report

Merging #1209 (dc56677) into main (1ec6f07) will decrease coverage by 0.02%.
The diff coverage is 85.10%.

@@            Coverage Diff             @@
##             main    #1209      +/-   ##
==========================================
- Coverage   86.14%   86.11%   -0.03%     
==========================================
  Files         196      196              
  Lines       19813    19822       +9     
  Branches     2314     2316       +2     
==========================================
+ Hits        17068    17070       +2     
- Misses       2181     2186       +5     
- Partials      564      566       +2     

Flag	Coverage Δ
py-unittests	86.11% <85.10%> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
...-opentimelineio/opentimelineio/adapters/adapter.py	87.50% <ø> (ø)
...-opentimelineio/opentimelineio/adapters/fcp_xml.py	87.83% <ø> (ø)
...opentimelineio/opentimelineio/algorithms/filter.py	94.93% <ø> (ø)
...timelineio/opentimelineio/algorithms/stack_algo.py	64.28% <ø> (ø)
...elineio/opentimelineio/algorithms/timeline_algo.py	100.00% <ø> (ø)
...timelineio/opentimelineio/algorithms/track_algo.py	89.61% <ø> (ø)
...timelineio/console/autogen_plugin_documentation.py	72.72% <ø> (ø)
...-opentimelineio/opentimelineio/core/composition.py	100.00% <ø> (ø)
src/py-opentimelineio/opentimelineio/hooks.py	100.00% <ø> (ø)
...-opentimelineio/opentimelineio/plugins/manifest.py	86.56% <ø> (ø)
... and 19 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1ec6f07...dc56677. Read the comment docs.

[JeanChristopheMorinPerso]

Thanks @jminor for the review! I addressed all your comments and suggestions and I also completed what I wanted to do. The ReadTheDocs setup should be much more reliable now because the dependencies required to build the docs are now pinned to specific versions.

So the PR is now officially ready for more reviews.

[JeanChristopheMorinPerso]

It's also good to note that there is only 2 Sphinx warnings left when building the docs :)

docstring of opentimelineio._otio.PyCapsule.parent:: WARNING: py:class reference target not found: opentimelineio::v1_0::Composition
docstring of opentimelineio._otio.Item:: WARNING: py:class reference target not found: bool_

To remove the first warning, we would need to shuffle the order of the code in src/py-opentimelineio/opentimelineio-bindings/otio_serializableObjects.cpp.

For the second warning, we would need to update to Pybind11 2.9.1 where we are interested in Render py::bool_ and py::float_ as bool and float respectively..

[JeanChristopheMorinPerso]

Alright, I fixed the docstring of opentimelineio._otio.PyCapsule.parent:: WARNING: py:class reference target not found: opentimelineio::v1_0::Composition warning. Only one left, but I'll do that in another pull request since it implies updating Pybind11.

[JeanChristopheMorinPerso]

I pushed new commits that address the PR comments I had from @meshula and there is also a new GitHub action workflow that checks for dead links in the docs.

I had to rebase all commits because of DCO and fix merge conflicts.

[codecov-commenter]

Codecov Report

Merging #1209 (d4774b0) into main (d9f3e4d) will decrease coverage by 0.02%.
The diff coverage is 85.10%.

@@            Coverage Diff             @@
##             main    #1209      +/-   ##
==========================================
- Coverage   86.20%   86.17%   -0.03%     
==========================================
  Files         196      196              
  Lines       19839    19848       +9     
  Branches     2317     2319       +2     
==========================================
+ Hits        17103    17105       +2     
- Misses       2170     2175       +5     
- Partials      566      568       +2     

Flag	Coverage Δ
py-unittests	86.17% <85.10%> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
...-opentimelineio/opentimelineio/adapters/adapter.py	87.50% <ø> (ø)
...-opentimelineio/opentimelineio/adapters/fcp_xml.py	87.83% <ø> (ø)
...opentimelineio/opentimelineio/algorithms/filter.py	94.93% <ø> (ø)
...timelineio/opentimelineio/algorithms/stack_algo.py	64.28% <ø> (ø)
...elineio/opentimelineio/algorithms/timeline_algo.py	100.00% <ø> (ø)
...timelineio/opentimelineio/algorithms/track_algo.py	89.61% <ø> (ø)
...timelineio/console/autogen_plugin_documentation.py	72.72% <ø> (ø)
...-opentimelineio/opentimelineio/core/composition.py	100.00% <ø> (ø)
src/py-opentimelineio/opentimelineio/hooks.py	100.00% <ø> (ø)
...-opentimelineio/opentimelineio/plugins/manifest.py	86.56% <ø> (ø)
... and 19 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d9f3e4d...d4774b0. Read the comment docs.

[JeanChristopheMorinPerso]

I create a PR to update Pybind11 to 2.9.2, see #1312 . Hopefully it will be merged before we merge this current PR so that I can add a new job to check for Sphinx warnings in CI.

[JeanChristopheMorinPerso]

@jminor @meshula (I wish there was a TSC tag... There is only the committer tag which includes John Mertic...), Gentle ping on this PR. I just added the job that checks if there is any build error/warning as I said previously.

This PR is now pretty much done from my point of view, unless someone wants to do another review pass at the docstrings or anything else?

[ssteinbach]

This looks great, thanks @JeanChristopheMorinPerso ! One (non blocking) question- do you know why some headers appear twice on mobile?

[JeanChristopheMorinPerso]

Good question @ssteinbach ! Both pages seem to contain the same section names. When you click on the sections, the content is different, so they don't seem duplicated.

Does that make sense?

[ssteinbach]

Wow this is a great change. Thanks for working through this!

[JeanChristopheMorinPerso]

Thanks for the reviews and accepting the pull request! 🎉✨