📖 [Docs] API Reference Doc Generation #1230
Conversation
✅ Deploy Preview for olmv1 ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
| @@ -299,6 +299,16 @@ quickstart: $(KUSTOMIZE) manifests #EXHELP Generate the installation release man | |||
|
|
|||
| ##@ Docs | |||
|
|
|||
| .PHONY: crd-ref-docs | |||
| API_REFERENCE_FILENAME := operator-controller-api-reference.md | |||
There was a problem hiding this comment.
Any strong thoughts on the filename? I prepended with operator-controller on the off-chance we put other APIs in here.
There was a problem hiding this comment.
operator-controller-api-reference.md sounds good to me.
| API_REFERENCE_FILENAME := operator-controller-api-reference.md | ||
| crd-ref-docs: $(CRD_REF_DOCS) | ||
| rm -f $(ROOT_DIR)/docs/drafts/$(API_REFERENCE_FILENAME) | ||
| $(CRD_REF_DOCS) --source-path=$(ROOT_DIR)/api \ |
There was a problem hiding this comment.
There are a wealth of options and configuration we can use when we generate these; if there are any that seem interesting or necessary here please let me know! Otherwise for now I'm just dumping the entire API reference into one .md file. We could for instance build a config file to ignore the ClusterExtensionList type if we wanted to.
dtfranz
force-pushed
the
api-reference-docs
branch
from
78bd76b
to
21d6827
Compare
|
Just needed to rebase, all good now. |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1230 +/- ##
=======================================
Coverage 76.53% 76.53%
=======================================
Files 40 40
Lines 2340 2340
=======================================
Hits 1791 1791
Misses 392 392
Partials 157 157
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
dtfranz
force-pushed
the
api-reference-docs
branch
from
21d6827
to
7deae44
Compare
dtfranz
changed the title
| @@ -1,6 +1,6 @@ | |||
| module github.com/operator-framework/operator-controller | |||
|
|
|||
| go 1.22.5 | |||
| go 1.22.7 | |||
There was a problem hiding this comment.
Version bump required by the crd-ref-docs latest version
dtfranz
force-pushed
the
api-reference-docs
branch
from
7deae44
to
e170ced
Compare
|
Other than the nits I made in Slack, my only other comments are refinements to try in the future. |
| @@ -0,0 +1,281 @@ | |||
| # API Reference | |||
There was a problem hiding this comment.
Could we change this heading easily?
| # API Reference | |
| # Operator Controller API Reference |
Makefile
Outdated
| $(CRD_REF_DOCS) --source-path=$(ROOT_DIR)/api \ | ||
| --config=$(ROOT_DIR)/config/base/crd/bases/olm.operatorframework.io_clusterextensions.yaml \ | ||
| --renderer=markdown \ | ||
| --output-path=$(ROOT_DIR)/docs/refs/api/ |
There was a problem hiding this comment.
Nit: I did some digging in the source code and it looks like they support this being a path to a file as well - could you verify if setting --output-path=$(ROOT_DIR)/docs/refs/api/$(API_REFERENCE_FILENAME) would allow us to drop the mv operation after this?
There was a problem hiding this comment.
Ah - you're right. I did try that before but I must have formatted it wrong or had some other issue; I assumed it didn't work. Thanks for digging in to find that! I've updated the PR.
There was a problem hiding this comment.
Just a minor nit - I don't think it should hold this PR. Thanks @dtfranz !
Adds API reference doc generation via github.com/elastic/crd-ref-docs, and adds make target + dependency to the Makefile so we can ensure the document is always up-to-date. Signed-off-by: dtfranz <dfranz@redhat.com>
dtfranz
force-pushed
the
api-reference-docs
branch
from
e170ced
to
587c775
Compare
Adds API reference doc generation via github.com/elastic/crd-ref-docs, and adds make target + dependency to the Makefile so we can ensure the document is always up-to-date.
Closes #1126
Description
Reviewer Checklist