[lfx-mentorship-2023-Sep-Nov] Add Karmada API documentation on the website

[XiShanYongYe-Chang]

CNCF LFX mentorship
https://github.com/cncf/mentoring/tree/main/programs/lfx-mentorship/2023/03-Sep-Nov

Mentor: @XiShanYongYe-Chang
Backup: @RainbowMango

What would you like to be added:

Description: Add the Karmada API documentation on the website, and complete the script for automatic document generation.

Why is this needed:

Convenient for users to quickly view the Karmada API documentation.

Tasks:

• Technical Documentation: design description and analysis
• Script Complete: automatic document generation
• Maintaining Documentation: add maintaining documents on the website

[anshgoyalevil]

@XiShanYongYe-Chang

I really want to work on this project under the LFX Fall 2023. Should I start creating the child issues to this parent issue and get a few of them resolved?

[punithnayak]

Hey @XiShanYongYe-Chang, @RainbowMango I want to work on this.I have Worked With the WIkimedia Foundation a chrome

[XiShanYongYe-Chang]

Now we are still in the project proposal stage. According to the timeline, mentees can start applying at the time Wed Aug 16 - Tues Aug 29, 5:00 PM PDT.

[anshgoyalevil]

Thanks for clarifying @XiShanYongYe-Chang
Just wanted to get my hands on the project, like some pre-contributions before applying in August.
That would help me showcase my skills required for the idea to be implemented.

[parthn2]

Hi @XiShanYongYe-Chang, I was looking on this issue and has some question. Can you please clarify this?

1. As far as I understand the task is to document this API https://github.com/karmada-io/api? Am I right?
2. We don't need to manually right the documentation. There is some script already written but not completed which could be used for automatically generating documents which we need to complete as a part of this task.

[XiShanYongYe-Chang]

@parthn2 thanks for your questions.

As far as I understand the task is to document this API https://github.com/karmada-io/api? Am I right?

What we need to do is document the API Swagger file and output it in a format similar to the Kubernetes API documentation: https://kubernetes.io/docs/reference/kubernetes-api/

We don't need to manually right the documentation.

Yes, we don't need to write it manually.

There is some script already written but not completed which could be used for automatically generating documents which we need to complete as a part of this task.

Sorry, currently there are no relevant scripts in the Karmada repo. We need to complete it so that we can automatically generate a set of up-to-date API documentation at any given time in the future.

Perhaps we can refer to Kubernetes:

https://kubernetes.io/docs/contribute/generate-ref-docs/kubernetes-api/

[allgandalf]

Hello team 👋, Rohan this side :)

I would like to work on this issue during the LFX fall term.

A quick question:

Should we include project implementation details in our Cover Letter ? Is it useful to have implementation details to increase our chances of getting selected?

[rakshitgondwal]

Hey @XiShanYongYe-Chang @RainbowMango, I am interested to apply for this project under this LFX term.
Though, generating API docs from swagger.json sounds good to me but have we considered generating the docs from the API path?
Like, we can make use of this tool (better version, currently used by elastic) too to generate the API docs, all we'll need is a path to our api dir, if we have that.
Otherwise generating the docs from swagger.json is also a good idea, I got my hands on a good tool, that can help us achieve this, will mention all about this in my cover letter. Thanks.

[XiShanYongYe-Chang]

Hi @RohanSasne

Should we include project implementation details in our Cover Letter ? Is it useful to have implementation details to increase our chances of getting selected?

If you can add this information, I feel that it will help me better understand everyone's level of understanding of the declared project.

[XiShanYongYe-Chang]

Hey @XiShanYongYe-Chang @RainbowMango, I am interested to apply for this project under this LFX term. Though, generating API docs from swagger.json sounds good to me but have we considered generating the docs from the API path? Like, we can make use of this tool (better version, currently used by elastic) too to generate the API docs, all we'll need is a path to our api dir, if we have that. Otherwise generating the docs from swagger.json is also a good idea, I got my hands on a good tool, that can help us achieve this, will mention all about this in my cover letter. Thanks.

Hi @rakshitgondwal, Thank you for guiding me to find these useful open-source tools. I have a question: do these tools only handle CRD resources, or can they also handle resources extended by the aggregation layer? We have some resources that are extended by the aggregation layer, such as Cluster, and we need them to be displayed in the API documentation as well.

[rakshitgondwal]

Hi @rakshitgondwal, Thank you for guiding me to find these useful open-source tools. I have a question: do these tools only handle CRD resources, or can they also handle resources extended by the aggregation layer? We have some resources that are extended by the aggregation layer, such as Cluster, and we need them to be displayed in the API documentation as well.

There's no specific mention about this use case, though the command to generate the docs would somewhat look like this

/path/to/gen-crd-api-reference-docs \
    -config "/path/to/example-config.json" \
    -api-dir "github.com/<path-to-karmada-api>/apis/" \
    -out-file docs.html

so if we have the aggregation layer extending resources under the apis/ dir then it should generate the docs for them too.

Also, after looking into this a bit more, the docs tooling that is being used by Kubernetes i.e. reference-docs has also been inspired by the tool I mentioned above(https://github.com/ahmetb/gen-crd-api-reference-docs), which makes it more reliable. Upto us now that which version of tooling we wanna go for.

[parthn2]

Now we are still in the project proposal stage. According to the timeline, mentees can start applying at the time Wed Aug 16 - Tues Aug 29, 5:00 PM PDT.

Hii, Just wanted to make sure! I guess the timeline you mentioned is for review of application and we can just apply until Aug 15th?

[XiShanYongYe-Chang]

Hi @parthn2, you can get the timeline here: https://github.com/cncf/mentoring/tree/main/programs/lfx-mentorship/2023/03-Sep-Nov

[chl178]

Hi @XiShanYongYe-Chang,
I've applied for the project and submitted my cover letter detailing my understanding of it. I'm eager to contribute and would appreciate any feedback.

[XiShanYongYe-Chang]

We have successfully launched the Karmada API documentation. Thank you all for your attention. Thanks @Affan-7
/assign @Affan-7
/close

[karmada-bot]

@XiShanYongYe-Chang: GitHub didn't allow me to assign the following users: Affan-7.

Note that only karmada-io members, repo collaborators and people who have commented on this issue/PR can be assigned. Additionally, issues/PRs can only have 10 assignees at the same time.
For more information please see the contributor guide

In response to this:

We have successfully launched the Karmada API documentation. Thank you all for your attention. Thanks @Affan-7
/assign @Affan-7
/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.

[karmada-bot]

@XiShanYongYe-Chang: Closing this issue.

In response to this:

We have successfully launched the Karmada API documentation. Thank you all for your attention. Thanks @Affan-7
/assign @Affan-7
/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.