[GSoD'20] Update how the Kubernetes website serves API references

[feloy]

This pull request implements #23809

Generating Markdown files

The goal of this PR is to generate Markdown files for the API reference, with the help of https://github.com/kubernetes-sigs/reference-docs/tree/master/gen-resourcesdocs. The result is visible at https://deploy-preview-23294--kubernetes-io-master-staging.netlify.app/docs/reference/kubernetes-api/

[k8s-ci-robot]

Thanks for your pull request. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please follow instructions at https://git.k8s.io/community/CLA.md#the-contributor-license-agreement to sign the CLA.

It may take a couple minutes for the CLA signature to be fully registered; after that, please reply here with a new comment and we'll verify. Thanks.

---

• If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
• If you signed the CLA as a corporation, please sign in with your organization's credentials at https://identity.linuxfoundation.org/projects/cncf to be authorized.
• If you have done the above and are still having issues with the CLA being reported as unsigned, please log a ticket with the Linux Foundation Helpdesk: https://support.linuxfoundation.org/
• Should you encounter any issues with the Linux Foundation Helpdesk, send a message to the backup e-mail support address at: login-issues@jira.linuxfoundation.org

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. I understand the commands that are listed here.

[netlify]

Deploy preview for kubernetes-io-master-staging ready!

Built with commit 9f6181b

https://deploy-preview-23294--kubernetes-io-master-staging.netlify.app

[netlify]

✔️ Deploy preview for kubernetes-io-master-staging ready!

🔨 Explore the source changes: 1373ad2

🔍 Inspect the deploy logs: https://app.netlify.com/sites/kubernetes-io-master-staging/deploys/60073f18b2c43b00089a5559

😎 Browse the preview: https://deploy-preview-23294--kubernetes-io-master-staging.netlify.app

[sftim]

BTW, you can add example shortcodes into content/en/docs/test.md.

[sftim]

/hold
do not merge

[feloy]

BTW, you can add example shortcodes into content/en/docs/test.md.

The swaggerui shortcode needs the swagger page layout (https://www.docsy.dev/docs/adding-content/shortcodes/#swaggerui)

---
title: A swagger page
type: swagger
---

I would prefer not to break the actual layout of the page.

[tengqm]

Preview: https://deploy-preview-23294--kubernetes-io-master-staging.netlify.app/docs/reference/swagger/batch-v1/

We know about this swagger-viewer UI long before. It is simply not usable for Kubernetes APIs.

[feloy]

The idea would be to document parts of the Kubernetes API (here the batch/v1 API only), in specific places of the documentation. More on the project: https://developers.google.cn/season-of-docs/docs/participants/project-cncf-feloy

[sftim]

@feloy, is there an issue opened to track the work that this pull request is a (draft) to implement?

(if not, please open one when you have a moment)

[celestehorgan]

@feloy Awesome to see this project underway!

A couple of general comments/questions. If you feel it's too soon to think about these @feloy, please feel free to open the issue @sftim mentioned above and record these commends over in the issue to address later.

Relevant in the scope of this PR

1. Do we actually want to enable the Authorize/Try it out features that come default with most Swagger renderings? Kubernetes is usually deployed "on prem", i.e. by and for a specific team, rather than being an API available to anyone with auth access. Maintaining a k8s deployment for people to 'try it out' on could also pose security risks. I'm not sure this is the best option for us? What do you think, @zacharysarah?

2. Is any k8s API truly "unversioned" (per the tag marker here: https://deploy-preview-23294--kubernetes-io-master-staging.netlify.app/docs/reference/swagger/batch-v1/), or are they the same version as the overall k8s version – in this case, v1.19?

General questions/comments better left for an issue/umbrella issue for this change:

1. A writer-ly question for @zacharysarah. Is this...

• The Batch API?
• The Batch Resource(s) of the Kubernetes API?
• The Batch Endpoint(s) of the Kubernetes API?
• "Batch" in the Kubernetes API?
• Other?

I'd go for either Batch API or Batch Resource of the K8s API personally.

2. If we're going to use placeholders, i.e. /apis/batch/v1/namespaces/{namespace}/jobs/{name}, we need to:

• make sure each section uses the same holders
• define them centrally for people

3. Before this goes live we need to do a sweep of the source files in https://github.com/kubernetes/api for basic language quality, i.e. capitalization at the beginning of sentences.

I think I have more but for now, this is what comes to mind.

[sftim]

BTW it's the batch API group.

[celestehorgan]

So one major thing that came to mind/was forming as I wrote that first comment is this: based purely on the existing API Reference and @feloy's first pass at rendering the swagger output, we're going to have... UX/navigation comprehension problems between what we currently have and where we'll end up.

@feloy – please don't feel too pressured by this comment! It's a matter of SIG Docs deciding what we want and how we want to display things. Just be aware :)

For example, let's say I want to create a Job, aka POST /apis/batch/v1/namespaces/{namespace}/jobs.

In our existing API Reference, you end up here. I'll drop a screencap of the navigation to make it clearer:

If I had to breadcrumb out this navigation structure, I'd do it like this: Kubernetes API Reference > Workload APIs > Jobs(*) > Create

(*) Mentally, as a user, I drop the "v1 batch" part of the name, because all the APIs in this section are "v1 _____" and my mind glosses over it.

If I had to do the same for the Swagger-rendered API Reference..

I'd end up with the following: Kubernetes API Reference > Batch API > Batch v1 > POST /apis/batch/v1/namespaces/{namespace}/jobs

This brings up two things we need to think about as a group:

• We lose the context of a group of APIs being related to "workloads"
• Instead of "Job" being the primary resource to navigate by, now "Batch" is the primary resource we see and navigate by.

For what it's worth, I think:

• Losing that grouping of things being "workload" related is, in an API as large as Kubernetes, problematic. The existing API reference also provides guidance documentation at the Workload API heading level which help situate the user. I think this is mitagate-able by creating congruent normal Docsy pages.
• The same group of endpoints now being labeled "Batch" instead of "Job" is really problematic, from a UX perspective. Ideas anyone? :/

[kbhawkey]

Hi. There is another doc authored by @feloy which includes some input about the project.
Is there a plan to capture these questions/ideas in a website project or issue?
The current reference is one large page with the left hand navigation grouping related resources.
I am not for or against these categories, but the categories provide a way
of modelling the content that somewhat ties into the concepts section (workloads, services, configuration and storage).
Would the new reference information be a complete reference or single pages listed in one content section?
The GVK remains an important piece.

[zacharysarah]

To boost visibility, @feloy's project doesn't officially begin until September 13th. Please be mindful with expectations for reviews given before the project officially begins.

[k8s-ci-robot]

Thanks for your pull request. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please follow instructions at https://git.k8s.io/community/CLA.md#the-contributor-license-agreement to sign the CLA.

It may take a couple minutes for the CLA signature to be fully registered; after that, please reply here with a new comment and we'll verify. Thanks.

---

• If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
• If you signed the CLA as a corporation, please sign in with your organization's credentials at https://identity.linuxfoundation.org/projects/cncf to be authorized.
• If you have done the above and are still having issues with the CLA being reported as unsigned, please log a ticket with the Linux Foundation Helpdesk: https://support.linuxfoundation.org/
• Should you encounter any issues with the Linux Foundation Helpdesk, send a message to the backup e-mail support address at: login-issues@jira.linuxfoundation.org

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. I understand the commands that are listed here.

[kbhawkey]

Not sure why the shortcode changes were pulled out of this PR, but:
/lgtm

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: 506f4cbc1d1223b666a0db793c9da7ddf30c139d

[zacharysarah]

@sftim

let's mark the new API reference as not indexable for search engines, initially

Possibly bikeshedding, but I think disallowing in robots.txt is easier and less painful to maintain and eventually delete than adding noindex tags to individual files, given that the new reference generation method creates numerous files instead of a single page.

It won't actually de-index files from search results--folks will get "robots.txt didn't allow this" or whatever--but I think it might work temporarily.

Thoughts?

User-agent: *
Disallow: https://kubernetes.io/docs/reference/generated/kubernetes-api/*
Allow: https://kubernetes.io/docs/reference/generated/kubernetes-api/
Allow: https://kubernetes.io/docs/reference/generated/kubernetes-api/api-index/
Allow: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/
Allow: https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/

[sftim]

@zacharysarah that's useful bikeshedding!

[sftim]

BTW usually robot exclusion uses site-relative URLs rather than full URLs.
BTW BTW we should leave /docs/reference/generated/kubernetes-api/v1.20/ indexed I think.

[sftim]

If #26155 merges, or something similar, let's merge this.

[zacharysarah]

#26155 merged, so here's an approval. @sftim, feel free to /lgtm and /hold cancel when ready. 👍🏻

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: zacharysarah

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [zacharysarah]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[sftim]

/hold cancel

Addressed

[sftim]

/remove-label tide/merge-method-squash
/lgtm

🎉 @feloy 🎉
(this is a huge improvement)

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: 7243fe0270c0277ba034c77e3b8bf7f4e68102e1