-
Notifications
You must be signed in to change notification settings - Fork 14.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[GSoD'20] Update how the Kubernetes website serves API references #23294
[GSoD'20] Update how the Kubernetes website serves API references #23294
Conversation
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.
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. |
9f6181b
to
ea5bbd1
Compare
Deploy preview for kubernetes-io-master-staging ready! Built with commit 9f6181b https://deploy-preview-23294--kubernetes-io-master-staging.netlify.app |
✔️ 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
BTW, you can add example shortcodes into content/en/docs/test.md
.
/hold |
The swaggerui shortcode needs the swagger page layout (https://www.docsy.dev/docs/adding-content/shortcodes/#swaggerui)
I would prefer not to break the actual layout of the page. |
We know about this swagger-viewer UI long before. It is simply not usable for Kubernetes APIs. |
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 |
@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) |
@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
General questions/comments better left for an issue/umbrella issue for this change:
I'd go for either Batch API or Batch Resource of the K8s API personally.
I think I have more but for now, this is what comes to mind. |
BTW it's the |
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 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:
For what it's worth, I think:
|
Hi. There is another doc authored by @feloy which includes some input about the project. |
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. |
63ab0de
to
b0326f2
Compare
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.
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. |
32e93e3
to
add24db
Compare
Not sure why the shortcode changes were pulled out of this PR, but: |
LGTM label has been added. Git tree hash: 506f4cbc1d1223b666a0db793c9da7ddf30c139d
|
Possibly bikeshedding, but I think disallowing in 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?
|
@zacharysarah that's useful bikeshedding! |
BTW usually robot exclusion uses site-relative URLs rather than full URLs. |
If #26155 merges, or something similar, let's merge this. |
[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:
Approvers can indicate their approval by writing |
/hold cancel |
/remove-label tide/merge-method-squash 🎉 @feloy 🎉 |
LGTM label has been added. Git tree hash: 7243fe0270c0277ba034c77e3b8bf7f4e68102e1
|
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/