Start to cleanup PyOutline and PyCue docstrings

[sharifsalah]

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

Summarize your change.
Update PyOutline and PyCue docstrings to resolve warnings when building the API reference. Also improve some of the formatting to call out parameters and return types. I also fixed some inaccurate docstrings as I came across them and improved formatting of some of the Python example code in the docstrings. There's more to do, including updating types so that they link between the generated docs and to improve coverage, clarity, and accuracy of the content. I made the changes using a mixture of regex search and replace and some manually editing.

Mostly, the changes are to update docstrings in the default expected by Sphinx, from:

       """Return an existing limit by it's id.
        @type id: str
        @param id: Name of limit to find.
        @rtype: opencue.wrappers.limit.Limit
        @return: The limit found by id.
        """

To the following:

        """Return an existing limit by it's id.
        
        :type id: str
        :param id: Name of limit to find.
        :rtype: opencue.wrappers.limit.Limit
        :return: The limit found by id.
        """

The output has been updated from something like the following:

To the following updated output:

One file to pay particular attention to is pycue/opencue/wrappers/limit.py. The indentation throughout this file was different from the others and was causing Sphinx to throw an exception when I added a description of the class.

The build output is now clean with no warnings or errors:

$ make html
Running Sphinx v1.8.5
making output directory...
loading intersphinx inventory from https://docs.python.org/objects.inv...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 11 source files that are out of date
updating environment: 11 added, 0 changed, 0 removed
reading sources... [100%] modules/outline.versions                                                                            
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] modules/outline.versions                                                                             
generating indices... genindex py-modindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

[bcipriano]

This is approved with a few minor comments. Thanks for working on this @sharifsalah, it looks like a lot of work. The docs site looks great, and this will be a big help while doing dev work -- both the reference site itself as well as the improved IDE functionality that we get for free with these cleaned-up docstrings :)

[sharifsalah]

Thanks for the review @bcipriano. Also very glad to hear that it improves the IDE experience for free :)