kubernetes-client / kubernetes-client/python
Some suggestions for improvements to auto-generated docs
- Dominant language
- Python
- Stars
- 7.7k
- Forks
- 3.5k
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 18
Description
I noticed a few minor improvements that can be made to the [auto-generated docs](https://github.com/kubernetes-client/python/blob/master/kubernetes/docs/CoreV1Api.md#replace_namespaced_secret). 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 _
Contributor guide
Research direction
Start with the linked auto-generated docs in kubernetes/docs/CoreV1Api.md, especially replace_namespaced_secret and replace_namespaced_service_account, and reproduce the empty V1ServiceAccount() error. Check how the examples are generated; done means the empty-class guidance or arguments are usable and the name and namespace examples follow Kubernetes naming format.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100