Improve PyDocs Generation

[davidvonthenen]

Proposed changes

Improve on the generated pydocs introduced in this PR #281 to make the look-and-feel user friendly.

This is a follow up to issue: #223

Context

Possible Implementation

NA

Other information

NA

[JayantToleti]

Hi I'm keen on contributing to this! Is there anything I need to know before i jump into this? Thank You

[davidvonthenen]

hi @JayantToleti

Thanks for your interest in helping with this.

The docs are currently getting generated here:
https://deepgram.github.io/deepgram-python-sdk/docs/v3/deepgram.html

The outstanding items are to see if we can get the docs to better align with the "structure" of the project. We currently have this helper mechanism to access classes using "dot notation" (example, deepgram.listen.prerecorded.v("1").transcribe_file(), this unfortunately doesn't play well with how the submodules appear on the left menu.

Options:

• Ideally, we would like to be able to traverse the menu to follow this "dot notation". So that you can traverse the menu like you would do the classes. This requires a way to have a parent -> child doc relationship. TASK: Need to investigate if there is a way to "structure" this documentation through pydoc annotations in source code.
• If there isn't a convenient way of doing this previous item, TASK: Are there annotations that can be used to prevent displaying/rendering certain pages so that we only display the leaf most classes (i.e., the classes that actually contain the implementation) in the menu/navigation?

This is what's left. Of course, once we figure this out, we need to improve the actual pydoc comments inline/code, but that's currently an easier hurdle.

Other option, we can always use another tool to get the pydoc comments to generate docs.