Skip to content
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.

Sign up for GitHub

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

Jump to bottom

feat: Generate Build API docs #147

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: Generate Build API docs #147

wants to merge 1 commit into from

Conversation

adambkaplan
Copy link
Member

@adambkaplan adambkaplan commented Feb 17, 2025 •
edited
Loading

Changes

Auto-generate API reference docs from Go comments. This is considered
best practice.

  • Utilize elastic/crd-ref-docs tool. This is much easier to use than
    the Kubernetes CRD docs stack.
  • Copy markdown templates from elastic/crd-ref-docs, so they can be
    customized later.
  • Use Makefile to run script generating docs from Shipwright build
    project.

The main branch is used to generate the docs for now, since it contains
the necessary kubebuilder markers to generate useful reference
material. In the future, we can pin this to a release tag.

Fixes #146

/kind feature

Submitter Checklist

  • Includes tests if functionality changed/was added
  • Includes docs if changes are user-facing
  • Set a kind label on this PR
  • Release notes block has been filled in, or marked NONE

See the contributor guide
for details on coding conventions, github and prow interactions, and the code review process.

Release Notes

Generate Build API reference docs directly from the build project codebase.

@openshift-ci openshift-ci bot added kind/feature Categorizes issue or PR as related to a new feature. do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. labels Feb 17, 2025
@pull-request-size pull-request-size bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Feb 17, 2025
@openshift-ci OpenShift CI
Copy link
Contributor

openshift-ci bot commented Feb 17, 2025

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please ask for approval from adambkaplan. For more information see the Code Review Process.

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

Needs approval from an approver in each of these files:

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

@adambkaplan adambkaplan mentioned this pull request Feb 17, 2025
Merged
4 tasks
@adambkaplan
Copy link
Member Author

Blocked by shipwright-io/build#1802 - otherwise the generated build.md doc will miss the table of contents for top level Kind objects, which is very necessary to navigate the doc.

@adambkaplan adambkaplan force-pushed the gen-api-docs branch 2 times, most recently from 64fe18e to 550afae Compare February 20, 2025 20:17
@adambkaplan adambkaplan changed the title WIP - Generate Build API docs feat: Generate Build API docs Feb 20, 2025
@openshift-ci openshift-ci bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Feb 20, 2025
@adambkaplan
Copy link
Member Author

PR is no longer blocked and is ready for review.

@adambkaplan
feat: Generate Build API Reference Docs
b0a3ce9 
Auto-generate API reference docs from Go comments. This is considered
best practice.

- Utilize elastic/crd-ref-docs tool. This is much easier to use than
  the Kubernetes CRD docs stack.
- Copy markdown templates from elastic/crd-ref-docs, so they can be
  customized later.
- Use Makefile to run script generating docs from Shipwright build
  project.
- Added a contributor guide to fix a broken link, and describe how to
  generate API docs to future contributors.

Documentation was generated from the v0.15.0 release tag.

Signed-off-by: Adam Kaplan <[email protected]>
@adambkaplan
Copy link
Member Author

@SaschaSchwarze0 @qu1queee PR has been updated with the generated APIs v0.15.0 🎉

I'll make a follow-up PR to draft the release announcement.

@qu1queee qu1queee self-requested a review February 27, 2025 07:52
@adambkaplan
Copy link
Member Author

Release annoucement PR: #150

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@rolfedh rolfedh Awaiting requested review from rolfedh

@SaschaSchwarze0 SaschaSchwarze0 Awaiting requested review from SaschaSchwarze0

@qu1queee qu1queee Awaiting requested review from qu1queee

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
kind/feature Categorizes issue or PR as related to a new feature. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.
Projects
Shipwright Overview
Status: No status
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

[FEATURE] Auto-generate Build API Reference Docs
1 participant
@adambkaplan