Documentation creates steep learning curve.

[gyennie]

My guess is that most of those who use settle on python as their k8s client are doing so due to python being their dominant language. The clean programming pattern for this client appears to be relying on the structs of each component needed to build request bodies and not combining structs with python dicts to generate requests. There are a lot of structs to choose from. Point being: the pythonic way of implementing the client is not necessarily obvious and users can benefit from documentation that points them to a clean programming pattern.

My request is to break out documentation into a similar format to k8s concepts docs https://kubernetes.io/docs/concepts/ and subtopic the same resources and have tutorials to manage said resources. As an example:

If I were looking to use the python client to create a job programmatically, I could navigate to:

Workloads
        |___Controllers
                    |___ Jobs

Where there is a clean tutorial that can show you how to build a job using only the structs required.

For example, to build the jobs in the k8s documentation https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/

apiVersion: batch/v1
kind: Job
metadata:
  name: pi
spec:
  template:
    spec:
      containers:
      - name: pi
        image: perl
        command: ["perl",  "-Mbignum=bpi", "-wle", "print bpi(2000)"]
      restartPolicy: Never
  backoffLimit: 4

The tutorial can show code like so:

from kubernetes import client
container = client.V1Container(name="pi")
container.image = "perl"
container.command = ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
temp_spec = client.V1PodSpec(containers=[container])
temp_spec.restart_policy = "Never"
template = client.V1beta1JobTemplateSpec()
template.spec = temp_spec
spec = client.V1JobSpec(template=template)
spec.backoff_limit = 4
job = client.V1Job()
job.spec = spec
meta = client.V1ObjectMeta()
meta.name = "pi"
job.metadata = meta

[roycaihw]

A couple of ideas:

• Similar to APIs and models, the documentations are also auto-generated from openapi spec. If we want to have hierarchical directories of documentation, we must have scripts to automate the process because we have to re-construct the directories every time we do a release (re-generate the client)
• For tutorial, we can start with the existing examples, to make the examples hierarchical / more useful for navigating.

[sarwatfatimam]

Hello,

I would like to work on this issue. Any specific guidelines for contribution for documents?

[brendandburns]

@sarwatfatimam that would be great. There are no real guidelines other than you will need to update the docs and send a pull request (PR) if you need help creating a PR, the docs here:

https://help.github.com/articles/creating-a-pull-request/

Are pretty good.

[govindKAG]

Would something like this be considered pythonic?
https://github.com/mozilla/agithub

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

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/test-infra repository.

[palnabarun]

/assign

[palnabarun]

/unassign