kubernetes-client/python

Some suggestions for improvements to auto-generated docs

Open

#2,337 opened on Jan 27, 2025

View on GitHub
 (3 comments) (0 reactions) (0 assignees)Python (6,225 stars) (3,323 forks)batch import
help wantedkind/documentation

Description

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 _

Contributor guide

Tech stack
python
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
PythonBasic understanding of Kubernetes resources
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75
Research direction
Investigate the auto generation pipeline in the kubernetes client/python repository, specifically the templates or scripts that produce the documentation files. Identify where empty class examples are generated and modify the code to either include arguments or display a helpful error message. Additionally, adjust the naming convention for name and namespace parameters to use hyphens instead of underscores, ensuring consistency with Kubernetes naming conventions.
Some suggestions for improvements to auto-generated docs · kubernetes-client/python#2337 | Good First Issue