Improved API Reference

[Wilso27]

Proposed changes

I am using the Deepgram Python SDK and have found it difficult to interpret code snippets provided in your documentation largely because the API Reference doesn't work like useful ones I have used for many other APIs. When I look at an API reference, I want to be able to quickly and easily find an exact method (i.e. I could search DeepgramClient().listen.asynclive().on()) and quickly understand its purpose and parameters.

Context

It would benefit me and others because I could diagnose issues with my code much easier by finding all the information about a certain method and understanding where a problem might be arising. I used code provided in your documentation, but I didn't have any easy way of understanding it line by line. Another example is for DeepgramClient().listen.asynclive().start() which takes in options, but to find those options I had to ctrl click a bunch of objects until I found a list which only gave me names and not uses instead of being able to search for it quickly in the API reference.

[davidvonthenen]

Yep, it's been a slow process, from restructuring the project to updating the API ref and documentation.

There are some preliminary but sorely needed TLC for auto-generated docs (issue with details #304 and a request for help), which we have been working at with the time available in the day:
https://deepgram.github.io/deepgram-python-sdk/docs/v3/deepgram.html

The experience is horrible because the dot notation pushes the classes deep in the docs tree, but it covers all the methods and what they do. Again, they need improvement because this isn't publicly visible yet.
https://deepgram.github.io/deepgram-python-sdk/docs/v3/deepgram/clients/listen/client.html

There are more details about SDK here:
https://developers.deepgram.com/docs/python-sdk

Along with examples here:
https://github.com/deepgram/deepgram-python-sdk?tab=readme-ov-file#examples

We have documentation on the website which covers the API refs:
https://developers.deepgram.com/reference/deepgram-api-overview

As well as an effort to make an API spec available.

If you are interested in helping out, please pile onto the existing open docs issue here with what you would like to see:
#304

[johnbumgarner]

I agree about the API references. I'm trying to use the API for the first time and the references for Python are failing. I'm trying something basic from this page -- https://developers.deepgram.com/reference/listen-file. I get this error -- Exception: The write operation timed out

[davidvonthenen]

I agree about the API references. I'm trying to use the API for the first time and the references for Python are failing. I'm trying something basic from this page -- https://developers.deepgram.com/reference/listen-file. I get this error -- Exception: The write operation timed out

You are probably hitting the timeout for upload. This is how you increase the timeout value:
https://developers.deepgram.com/docs/python-sdk-pre-recorded-transcription#increasing-the-timeout-for-processing-larger-files

The timeout is an implementation detail, not really an API ref in nature. We could make the SDK call sit indefinitely, but then you hit that one person where it hangs, and you have the opposite problem.

[johnbumgarner]

@dvonthenen thanks for that quick response!! Is there an audio file size limit or type that works best?

[davidvonthenen]

@dvonthenen thanks for that quick response!! Is there an audio file size limit or type that works best?

If there is a size limit, it's fairly large if I remember correctly.

Having said that, if you are trying to upload a video file, you are probably doing yourself a disservice by sending the video data. You would probably save yourself a ton of time by copying out the audio and doing that upload.

[davidvonthenen]

this issue has got a bunch of things now.

if you want to talk documentation with what you would be interested in, please add to this issue:
#304

If you want to help out, please also visit the issue.

If you want to try about how to use the SDK, I would definitely take a look at the examples, documentation and if you are still stuck, visit us in discord at:
https://dpgr.am/discord

There is an #ask-ai channel that will look through the docs to answer your questions.