Publish reference docs for Python modules

[sharifsalah]

Describe the enhancement
Update OpenCue to support generating and publishing API reference docs for the various Python packages and modules, starting with the outline package. I propose we adopt the Sphinx autodoc extension for this enhancement.

Screenshots
The end result would look something along the lines of the following:

Version Number
N/A

Additional context
Currently, the only way for OpenCue adopters to learn about the various Python APIs is to browse the source code. We can add support to generate and publish versioned API reference docs for all Python APIs. The outline package is most useful to OpenCue users and administrators. We can also publish reference docs for the other Python packages that will be useful for developers and contributors.

We can also add support and instructions to allow developers to build and preview changes to the reference docs locally before creating pull requests.

[bcipriano]

Sounds good to me!

[sharifsalah]

Support for PyOutline added in #563

Will work on adding the remaining Python packages next.

[sharifsalah]

Added support for PyCue packages FileSequence and opencue. sphinx-build completes without errors or warnings.

However, if I enable nit-picky mode, there are still a lot of warnings, related to missing references. (which I was expecting as I haven't worked on adding all the references)

Will work on cleaning these up next.

[to09]

Have you started working on this issue, otherwise I would like to complete it?

[sharifsalah]

This is a fairly big ongoing project, you should see that I've already linked various pull requests to this issue. There is certainly more work you could contribute to it, but I should mention that it is time-consuming before you volunteer.

We're trying to document all of the Python packages and modules in OpenCue. You can see a list of the modules we've already documented in:

https://github.com/AcademySoftwareFoundation/OpenCue/tree/master/docs/modules

The main work is to update the code comments to RST format as I explain in #589

[to09]

Thanks @sharifsalah, I will start working to update code comments to RST format after the issue template.

[bcipriano]

@to09 I would strongly encourage you to send SMALL PRs here -- please don't go through the trouble of updating an entire file all at once. Just pick one or two methods to document and send those first.

[to09]

Sure, I will start working on these soon.

[bcipriano]

@sharifsalah This came up during our last TSC meeting -- we'd love to get these API reference docs finished up and published.

I've done a good amount of work recently cleaning up docstrings as part of #78, which I think puts us pretty close to completion here.

What else is left other than updating docstrings? I imagine we'll need to, as part of one of our automated pipelines, build the docs HTML and publish it somewhere, then configure some opencue.io subdomain to point to those published files. Do I have that roughly right?

[sharifsalah]

Yes roughly right. I think building the HTML and related assets is probably the trickier bit. Most of my notes for building are documented on the opencue.io site. From memory, when I last looked at this I was thinking the output of the Sphinx build would then be published as a ZIP file for each release of OpenCue.

The docs could then be downloaded, unzipped, and published at deploy time by incorporating some steps into build.sh. The docs could be published on a subdomain or could also (probably more easily) published on the main domain in a sub-directory. For an example of publishing under the /api directory, see https://5e984ce13834eb00074d050e--elated-haibt-1b47ff.netlify.app/api/

I did some look and feel work in #683, but I expect a little more might be required depending on how the cleaned up strings and docs look?

One thing I never got round to looking at was versioning. Ideally the API reference would be published for every release of OpenCue so that users can select the version they are running or developing against. Right now there isn't really a mechanism on opencue.io to support versioning. I believe Docsy / Hugo support it though. You can see an example of this on the Agones site which uses a fairly similar stack. (the Release dropdown button)

Does all that make sense?