kubernetes-client / kubernetes-client/python

Some suggestions for improvements to auto-generated docs

Open
#2,337 4 comments 0 reactions 0 assignees View on GitHub
help wanted kind/documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.