Docs clarity and improvements

[mabdullahadeel]

The problem

Currently, the way sdk docs here and the start guide here are structured in a way that the code samples just shows the bare minimum use case which might be okay in many situations when developer is familiar with sdk. But for someone trying python sdk for the first time, I think there is a crucial part of code samples missing which is the import statements above the code.

For Example

pnconfig = PNConfiguration()
pnconfig.publish_key = "myPublishKey"
pnconfig.subscribe_key = "mySubscribeKey"
pnconfig.uuid = "myUniqueUUID"

pubnub = PubNub(pnconfig)

this is a code sample copied using the copy icon from getting started guide

For someone setting PubNub for the first time, it's very difficult to figure out the imports for PNConfiguration & PubNub.
For this example searching for a little while get me to the later section where I was able to find the imports for this specific case mentioned above. That pretty much all I got.

When I got to the Access Manager Docs here. I came across this example here

channels = [
    Channel.id("channel-a").read(),
    Channel.id("channel-b").read().write(),
    Channel.id("channel-c").read().write(),
    Channel.id("channel-d").read().write()
]
groups = [
    Group.id("channel-group-b").read()
]
uuids = [
    UUID.id("uuid-c").get(),
    UUID.id("uuid-d").get().update()
]
envelope = pubnub.grant_token()
    .channels(channels)
    .groups(groups)
    .ttl(15)
    .uuids(uuids)
    .authorized_uuid("my-authorized-uuid")
    .sync()

In this case, there is no way for a new to pubnub dev to figure out import statements for Channel, Group, etc type.

The solution proposals

1- SDK docs improvements

One straight solution would be to improve the current SDK docs so that they include import statements at least where necessary like the above-mentioned Access Manager docs case.
But this might increase the lengths of docs pages which should arguably be short and concise.

2- Use inline docs

Another simpler solution would be to use something like pydocs3 which can be used to create html or other supported types to generate automatic documentation for each class and save it in the docs folder in the codebase.
Then actions can be used to automatically compile and deploy those to something like readthedocs or some alternative. This will solve the problem by introducing search in these docs and developers can quickly see the supported methods and figure out imports for anything in the official SDK docs.

Thanks