Some suggestions for improvements to auto-generated docs

[calebAtIspot]

I noticed a few minor improvements that can be made to the auto-generated docs. Admittedly, these changes are obvious for the user to make, but typically one expects examples to work out-of-the-box as much as possible.

• The empty classes don't always work. For example, pass in a empty kubernetes.client.V1ServiceAccount() to replace_namespaced_service_account and you'll get an error the name of the object (name-example based on URL) was undeterminable: name must be provided. The class could use arguments or a message telling the user to provide arguments.
• name does not follow kubernetes naming format, should have - instead of _
• namespace does not follow kubernetes naming format, should have - instead of _

[roycaihw]

I agree the auto-generated doc examples don't always work out of the box. That's also one reason for us to maintain the manually written examples: https://github.com/kubernetes-client/python/tree/master/examples

The challenge with updating the auto-generated doc is they are generated by upstream openapi-generator. We may need to make changes upstream for these examples to work out of the box with Kubernetes conventions.

/help

[k8s-ci-robot]

@roycaihw: This request has been marked as needing help from a contributor.

Guidelines

Please ensure that the issue body includes answers to the following questions:

• Why are we solving this issue?
• To address this issue, are there any code changes? If there are code changes, what needs to be done in the code and what places can the assignee treat as reference points?
• Does this issue have zero to low barrier of entry?
• How can the assignee reach out to you for help?

For more details on the requirements of such an issue, please see here and ensure that they are met.

If this request no longer meets these requirements, the label can be removed by commenting with the /remove-help command.

In response to this:

I agree the auto-generated doc examples don't always work out of the box. That's also one reason for us to maintain the manually written examples: https://github.com/kubernetes-client/python/tree/master/examples

The challenge with updating the auto-generated doc is they are generated by upstream openapi-generator. We may need to make changes upstream for these examples to work out of the box with Kubernetes conventions.

/help

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[jennyluciav]

@roycaihw I'd like to help here if help is still wanted