├── template ├── placeholder.go ├── pkg.tpl ├── members.tpl └── type.tpl ├── .github ├── dependabot.yml └── workflows │ └── ci.yml ├── .gitignore ├── go.mod ├── .goreleaser.yml ├── example-config.json ├── go.sum ├── README.md ├── LICENSE └── main.go /template/placeholder.go: -------------------------------------------------------------------------------- 1 | // Placeholder file to make Go vendor this directory properly. 2 | package template 3 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: gomod 4 | directory: / 5 | schedule: 6 | interval: weekly 7 | 8 | - package-ecosystem: github-actions 9 | directory: / 10 | schedule: 11 | interval: weekly 12 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Binaries for programs and plugins 2 | refdocs 3 | *.exe 4 | *.exe~ 5 | *.dll 6 | *.so 7 | *.dylib 8 | 9 | # Test binary, build with `go test -c` 10 | *.test 11 | 12 | # Output of the go coverage tool, specifically when used with LiteIDE 13 | *.out 14 | 15 | # goreleaser output 16 | dist 17 | 18 | gen-crd-api-reference-docs 19 | -------------------------------------------------------------------------------- /go.mod: -------------------------------------------------------------------------------- 1 | module github.com/ahmetb/gen-crd-api-reference-docs 2 | 3 | go 1.21.0 4 | 5 | require ( 6 | github.com/russross/blackfriday/v2 v2.1.0 7 | k8s.io/gengo/v2 v2.0.0-20250106234829-0359904fc2a6 8 | k8s.io/klog/v2 v2.130.1 9 | ) 10 | 11 | require ( 12 | github.com/go-logr/logr v1.4.1 // indirect 13 | golang.org/x/mod v0.14.0 // indirect 14 | golang.org/x/tools v0.16.1 // indirect 15 | ) 16 | -------------------------------------------------------------------------------- /.goreleaser.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | builds: 3 | - env: 4 | - CGO_ENABLED=0 5 | goos: 6 | - linux 7 | - darwin 8 | goarch: 9 | - amd64 10 | - arm64 11 | flags: 12 | - -trimpath 13 | ldflags: 14 | - -s -w -X main.version={{.Version}} 15 | 16 | archives: 17 | - files: 18 | - LICENSE 19 | - template/** 20 | - example-config.json 21 | 22 | checksum: 23 | name_template: "checksums.txt" 24 | 25 | sboms: 26 | - artifacts: archive 27 | documents: 28 | - "${artifact}.spdx.json" 29 | 30 | signs: 31 | - cmd: cosign 32 | artifacts: checksum 33 | output: true 34 | certificate: "${artifact}.pem" 35 | args: 36 | - sign-blob 37 | - "--output-signature=${signature}" 38 | - "--output-certificate=${certificate}" 39 | - "${artifact}" 40 | - "--yes" 41 | -------------------------------------------------------------------------------- /example-config.json: -------------------------------------------------------------------------------- 1 | { 2 | "hideMemberFields": [ 3 | "TypeMeta" 4 | ], 5 | "hideTypePatterns": [ 6 | "ParseError$", 7 | "List$" 8 | ], 9 | "externalPackages": [ 10 | { 11 | "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$", 12 | "docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration" 13 | }, 14 | { 15 | "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/", 16 | "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}" 17 | }, 18 | { 19 | "typeMatchPrefix": "^github\\.com/knative/pkg/apis/duck/", 20 | "docsURLTemplate": "https://pkg.go.dev/github.com/knative/pkg/apis/duck/{{arrIndex .PackageSegments -1}}#{{.TypeIdentifier}}" 21 | } 22 | ], 23 | "typeDisplayNamePrefixOverrides": { 24 | "k8s.io/api/": "Kubernetes ", 25 | "k8s.io/apimachinery/pkg/apis/": "Kubernetes " 26 | }, 27 | "markdownDisabled": false 28 | } 29 | -------------------------------------------------------------------------------- /template/pkg.tpl: -------------------------------------------------------------------------------- 1 | {{ define "packages" }} 2 | 3 | {{ with .packages}} 4 |

Packages:

5 | 12 | {{ end}} 13 | 14 | {{ range .packages }} 15 |

16 | {{- packageDisplayName . -}} 17 |

18 | 19 | {{ with (index .GoPackages 0 )}} 20 | {{ with .DocComments }} 21 |
22 | {{ safe (renderComments .) }} 23 |
24 | {{ end }} 25 | {{ end }} 26 | 27 | Resource Types: 28 | 37 | 38 | {{ range (visibleTypes (sortedTypes .Types))}} 39 | {{ template "type" . }} 40 | {{ end }} 41 |
42 | {{ end }} 43 | 44 |

45 | Generated with gen-crd-api-reference-docs 46 | {{ with .gitCommit }} on git commit {{ . }}{{end}}. 47 |

48 | 49 | {{ end }} 50 | -------------------------------------------------------------------------------- /template/members.tpl: -------------------------------------------------------------------------------- 1 | {{ define "members" }} 2 | 3 | {{ range .Members }} 4 | {{ if not (hiddenMember .)}} 5 | 6 | 7 | {{ fieldName . }}
8 | 9 | {{ if linkForType .Type }} 10 | 11 | {{ typeDisplayName .Type }} 12 | 13 | {{ else }} 14 | {{ typeDisplayName .Type }} 15 | {{ end }} 16 | 17 | 18 | 19 | {{ if fieldEmbedded . }} 20 |

21 | (Members of {{ fieldName . }} are embedded into this type.) 22 |

23 | {{ end}} 24 | 25 | {{ if isOptionalMember .}} 26 | (Optional) 27 | {{ end }} 28 | 29 | {{ safe (renderComments .CommentLines) }} 30 | 31 | {{ if and (eq (.Type.Name.Name) "ObjectMeta") }} 32 | Refer to the Kubernetes API documentation for the fields of the 33 | metadata field. 34 | {{ end }} 35 | 36 | {{ if or (eq (fieldName .) "spec") }} 37 |
38 |
39 | 40 | {{ template "members" .Type }} 41 |
42 | {{ end }} 43 | 44 | 45 | {{ end }} 46 | {{ end }} 47 | 48 | {{ end }} 49 | -------------------------------------------------------------------------------- /go.sum: -------------------------------------------------------------------------------- 1 | github.com/go-logr/logr v1.4.1 h1:pKouT5E8xu9zeFC39JXRDukb6JFQPXM5p5I91188VAQ= 2 | github.com/go-logr/logr v1.4.1/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY= 3 | github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI= 4 | github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= 5 | github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= 6 | github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= 7 | golang.org/x/mod v0.14.0 h1:dGoOF9QVLYng8IHTm7BAyWqCqSheQ5pYWGhzW00YJr0= 8 | golang.org/x/mod v0.14.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c= 9 | golang.org/x/sync v0.5.0 h1:60k92dhOjHxJkrqnwsfl8KuaHbn/5dl0lUPUklKo3qE= 10 | golang.org/x/sync v0.5.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= 11 | golang.org/x/tools v0.16.1 h1:TLyB3WofjdOEepBHAU20JdNC1Zbg87elYofWYAY5oZA= 12 | golang.org/x/tools v0.16.1/go.mod h1:kYVVN6I1mBNoB1OX+noeBjbRk4IUEPa7JJ+TJMEooJ0= 13 | k8s.io/gengo/v2 v2.0.0-20250106234829-0359904fc2a6 h1:SdzkGIk4b5LFkVO36PuO0Bx4tpBDJDpNN0F1/v8JM5c= 14 | k8s.io/gengo/v2 v2.0.0-20250106234829-0359904fc2a6/go.mod h1:EJykeLsmFC60UQbYJezXkEsG2FLrt0GPNkU5iK5GWxU= 15 | k8s.io/klog/v2 v2.130.1 h1:n9Xl7H1Xvksem4KFG4PYbdQCQxqc/tTUyrgXaOhHSzk= 16 | k8s.io/klog/v2 v2.130.1/go.mod h1:3Jpz1GvMt720eyJH1ckRHK1EDfpxISzJ7I9OYgaDtPE= 17 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | push: 5 | branches: 6 | - master 7 | tags: 8 | - "v[0-9]+.[0-9]+.[0-9]+*" 9 | pull_request: 10 | branches: 11 | - master 12 | 13 | permissions: 14 | contents: read 15 | 16 | jobs: 17 | build: 18 | name: Build 19 | runs-on: ubuntu-24.04 20 | permissions: 21 | contents: write 22 | id-token: write 23 | steps: 24 | - name: Checkout Repository 25 | uses: actions/checkout@v5.0.0 26 | with: 27 | fetch-depth: 0 28 | 29 | - name: Setup Golang Environment 30 | uses: actions/setup-go@v5.5.0 31 | with: 32 | go-version: stable 33 | 34 | - name: Download Syft 35 | uses: anchore/sbom-action/download-syft@v0.20.0 36 | if: github.ref_type == 'tag' 37 | 38 | - name: Install Cosign 39 | uses: sigstore/cosign-installer@v3.8.2 40 | if: github.ref_type == 'tag' 41 | 42 | - name: Build binary 43 | uses: goreleaser/goreleaser-action@v6.3.0 44 | with: 45 | version: latest 46 | args: ${{ github.ref_type == 'tag' && 'release' || 'build --snapshot' }} --clean 47 | env: 48 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 49 | 50 | - name: Print version 51 | run: ./dist/gen-crd-api-reference-docs_linux_amd64_v1/gen-crd-api-reference-docs -version 52 | continue-on-error: true 53 | -------------------------------------------------------------------------------- /template/type.tpl: -------------------------------------------------------------------------------- 1 | {{ define "type" }} 2 | 3 |

4 | {{- .Name.Name }} 5 | {{ if eq .Kind "Alias" }}({{.Underlying}} alias){{ end -}} 6 |

7 | {{ with (typeReferences .) }} 8 |

9 | (Appears on: 10 | {{- $prev := "" -}} 11 | {{- range . -}} 12 | {{- if $prev -}}, {{ end -}} 13 | {{- $prev = . -}} 14 | {{ typeDisplayName . }} 15 | {{- end -}} 16 | ) 17 |

18 | {{ end }} 19 | 20 |
21 | {{ safe (renderComments .CommentLines) }} 22 |
23 | 24 | {{ with (constantsOfType .) }} 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | {{- range . -}} 34 | 35 | {{- /* 36 | renderComments implicitly creates a

element, so we 37 | add one to the display name as well to make the contents 38 | of the two cells align evenly. 39 | */ -}} 40 |

41 | 42 | 43 | {{- end -}} 44 | 45 |
ValueDescription

{{ typeDisplayName . }}

{{ safe (renderComments .CommentLines) }}
46 | {{ end }} 47 | 48 | {{ if .Members }} 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | {{ if isExportedType . }} 58 | 59 | 62 | 67 | 68 | 69 | 73 | 74 | 75 | {{ end }} 76 | {{ template "members" .}} 77 | 78 |
FieldDescription
60 | apiVersion
61 | string		 63 | 64 | {{apiGroup .}} 65 | 66 |
70 | kind
71 | string 72 | 		{{.Name.Name}}
79 | {{ end }} 80 | 81 | {{ end }} 82 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Kubernetes Custom Resource API Reference Docs generator 2 | 3 | If you have a project that is providing Custom Resource Definitions and wanted to generate 4 | API Reference Docs [like this][ar] this tool is for you. 5 | 6 | [ar]: https://knative.dev/docs/reference/api/serving-api/ 7 | 8 | 9 | > [!WARNING] 10 | > **This project is not super actively maintained.** 11 | > Consider using the [**crd-ref-docs** by Elastic](https://github.com/elastic/crd-ref-docs) project 12 | instead. 13 | 14 | ## Alternatives 15 | 16 | This project has inspired creation of the following projects: 17 | 18 | - [**Kubernetes reference-docs generator**](https://github.com/kubernetes-sigs/reference-docs): 19 | used in [official Kubernetes component reference docs](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/) 20 | 21 | - [**crd-ref-docs** by Elastic](https://github.com/elastic/crd-ref-docs): A fresh implementation 22 | of this project. 23 | 24 | - If you're an open source project, consider exposing your 25 | CRD API Reference via https://doc.crds.dev/ without much effort. 26 | 27 | 28 | 29 | 30 | 31 | ## Current Users 32 | 33 | - [**Knative** API reference docs](https://knative.dev/docs/reference/api/serving-api/) 34 | - [**FluxCD** API reference docs](https://fluxcd.io/docs/components/source/api/) 35 | - [**Argo CD** operator API reference docs](https://argocd-operator.readthedocs.io/en/latest/reference/api.html/) 36 | - [**Contour** ingress controller API reference docs](https://projectcontour.io/docs/v1.19.0/config/api/) 37 | - [**Kubeflow** API reference docs](https://www.kubeflow.org/docs/reference/overview/) 38 | - [**cert-manager** API reference docs](https://cert-manager.io/docs/reference/api-docs/) 39 | - [**Open Service Mesh** API reference docs](https://release-v0-11.docs.openservicemesh.io/docs/api_reference/config/v1alpha1/) 40 | - [**PlanetScale Vitess Operator** API reference docs](https://github.com/planetscale/vitess-operator/blob/main/docs/api.md) 41 | - [**Agones** API reference docs](https://agones.dev/site/docs/reference/agones_crd_api_reference/) 42 | - [**Gardener** API reference docs](https://gardener.cloud/api-reference/) 43 | - [**New Relic Alert Manager** API reference docs](https://github.com/fpetkovski/newrelic-alert-manager/tree/master/docs) 44 | - [**Antrea** API reference docs](https://antrea.io/docs/v1.3.0/docs/api-reference/) 45 | - [**kube-green** API reference docs](https://kube-green.dev/docs/apireference_v1alpha1/) 46 | - [**Azure Service Operator** supported resources](https://azure.github.io/azure-service-operator/reference/) 47 | - [**NGINX Gateway Fabric** API reference docs](https://docs.nginx.com/nginx-gateway-fabric/reference/api/) 48 | - _[[ADD YOUR PROJECT HERE]]_ 49 | 50 | Also some **forks**: 51 | 52 | - [**elastic/crd-ref-docs**](https://github.com/elastic/crd-ref-docs): A fresh re-implementation inspired 53 | by this project that supports AsciiDoc. Used by Elastic Cloud on Kubernetes API reference docs. 54 | 55 | ## Why 56 | 57 | Normally you would want to use the same [docs generator][dg] as [Kubernetes API 58 | reference][ar], but here's why I wrote a different parser/generator: 59 | 60 | 1. Today, Kubernetes API [does not][pr] provide OpenAPI specs for CRDs (e.g. 61 | Knative), therefore the [gen-apidocs][ga] 62 | generator used by Kubernetes won't work. 63 | 64 | 2. Even when Kubernetes API starts providing OpenAPI specs for CRDs, your CRD 65 | must have a validation schema (e.g. Knative API doesn't!) 66 | 67 | 3. Kubernetes [gen-apidocs][ga] parser relies on running a `kube-apiserver` and 68 | calling `/apis` endpoint to get OpenAPI specs to generate docs. **This tool 69 | doesn't need that!** 70 | 71 | [dg]: https://github.com/kubernetes-incubator/reference-docs/ 72 | [ga]: https://github.com/kubernetes-incubator/reference-docs/tree/master/gen-apidocs/generators 73 | [pr]: https://github.com/kubernetes/kubernetes/pull/71192 74 | 75 | ## How 76 | 77 | This is a custom API reference docs generator that uses the 78 | [k8s.io/gengo](https://godoc.org/k8s.io/gengo) project to parse types and 79 | generate API documentation from it. 80 | 81 | Capabilities of this tool include: 82 | 83 | - Doesn't depend on OpenAPI specs, or kube-apiserver, or a running cluster. 84 | - Relies only on the Go source code (pkg/apis/**/*.go) to parse API types. 85 | - Can link to other sites for external APIs. For example, if your types have a 86 | reference to Kubernetes core/v1.PodSpec, you can link to it. 87 | - [Configurable](./example-config.json) settings to hide certain fields or types 88 | entirely from the generated output. 89 | - Either output to a file or start a live http-server (for rapid iteration). 90 | - Supports markdown rendering from godoc type, package and field comments. 91 | 92 | ## Try it out 93 | 94 | 1. Clone this repository. 95 | 96 | 2. Make sure you have go1.11+ installed. Then run `go build`, you should get a 97 | `gen-crd-api-reference-docs` binary executable in the current directory. 98 | 99 | 3. Clone a Knative repository, set GOPATH correctly, 100 | and call the compiled binary within that directory. 101 | 102 | ```sh 103 | # go into a repository root with GOPATH set. (I use my own script 104 | # goclone(1) to have a separate GOPATH for each repo I clone.) 105 | $ goclone knative/build 106 | 107 | $ /path/to/gen-crd-api-reference-docs \ 108 | -config "/path/to/example-config.json" \ 109 | -api-dir "github.com/knative/build/pkg/apis/build/v1alpha1" \ 110 | -out-file docs.html 111 | ``` 112 | 113 | 4. Visit `docs.html` to view the results. 114 | 115 | ----- 116 | 117 | This is not an official Google project. See [LICENSE](./LICENSE). 118 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /main.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import ( 4 | "bytes" 5 | "encoding/json" 6 | "flag" 7 | "fmt" 8 | "html/template" 9 | "io" 10 | "net/http" 11 | "os" 12 | "os/exec" 13 | "path/filepath" 14 | "reflect" 15 | "regexp" 16 | "runtime" 17 | "runtime/debug" 18 | "sort" 19 | "strconv" 20 | "strings" 21 | texttemplate "text/template" 22 | "time" 23 | "unicode" 24 | 25 | "github.com/russross/blackfriday/v2" 26 | "k8s.io/gengo/v2" 27 | "k8s.io/gengo/v2/parser" 28 | "k8s.io/gengo/v2/types" 29 | "k8s.io/klog/v2" 30 | ) 31 | 32 | var ( 33 | flConfig = flag.String("config", "", "path to config file") 34 | flAPIDir = flag.String("api-dir", "", "api directory (or import path), point this to pkg/apis") 35 | flTemplateDir = flag.String("template-dir", "template", "path to template/ dir") 36 | flVersion = flag.Bool("version", false, "print version and exit") 37 | 38 | flHTTPAddr = flag.String("http-addr", "", "start an HTTP server on specified addr to view the result (e.g. :8080)") 39 | flOutFile = flag.String("out-file", "", "path to output file to save the result") 40 | 41 | // set by go build 42 | version string 43 | ) 44 | 45 | const ( 46 | docCommentForceIncludes = "// +gencrdrefdocs:force" 47 | ) 48 | 49 | type generatorConfig struct { 50 | // HiddenMemberFields hides fields with specified names on all types. 51 | HiddenMemberFields []string `json:"hideMemberFields"` 52 | 53 | // HideTypePatterns hides types matching the specified patterns from the 54 | // output. 55 | HideTypePatterns []string `json:"hideTypePatterns"` 56 | 57 | // ExternalPackages lists recognized external package references and how to 58 | // link to them. 59 | ExternalPackages []externalPackage `json:"externalPackages"` 60 | 61 | // TypeDisplayNamePrefixOverrides is a mapping of how to override displayed 62 | // name for types with certain prefixes with what value. 63 | TypeDisplayNamePrefixOverrides map[string]string `json:"typeDisplayNamePrefixOverrides"` 64 | 65 | // MarkdownDisabled controls markdown rendering for comment lines. 66 | MarkdownDisabled bool `json:"markdownDisabled"` 67 | 68 | // GitCommitDisabled causes the git commit information to be excluded from the output. 69 | GitCommitDisabled bool `json:"gitCommitDisabled"` 70 | } 71 | 72 | type externalPackage struct { 73 | TypeMatchPrefix string `json:"typeMatchPrefix"` 74 | DocsURLTemplate string `json:"docsURLTemplate"` 75 | } 76 | 77 | type apiPackage struct { 78 | apiGroup string 79 | apiVersion string 80 | GoPackages []*types.Package 81 | Types []*types.Type // because multiple 'types.Package's can add types to an apiVersion 82 | Constants []*types.Type 83 | } 84 | 85 | func (v *apiPackage) identifier() string { return fmt.Sprintf("%s/%s", v.apiGroup, v.apiVersion) } 86 | 87 | func init() { 88 | klog.InitFlags(nil) 89 | flag.Set("alsologtostderr", "true") // for klog 90 | flag.Parse() 91 | 92 | commitHash, commitTime, dirtyBuild := getBuildInfo() 93 | arch := fmt.Sprintf("%v/%v", runtime.GOOS, runtime.GOARCH) 94 | 95 | if *flVersion { 96 | fmt.Printf("gen-crd-api-reference-docs version=%s commit=%s date=%s dirty=%v arch=%s go=%v\n", version, commitHash, commitTime, dirtyBuild, arch, runtime.Version()) 97 | os.Exit(0) 98 | } 99 | 100 | if *flConfig == "" { 101 | panic("-config not specified") 102 | } 103 | if *flAPIDir == "" { 104 | panic("-api-dir not specified") 105 | } 106 | if *flHTTPAddr == "" && *flOutFile == "" { 107 | panic("-out-file or -http-addr must be specified") 108 | } 109 | if *flHTTPAddr != "" && *flOutFile != "" { 110 | panic("only -out-file or -http-addr can be specified") 111 | } 112 | if err := resolveTemplateDir(*flTemplateDir); err != nil { 113 | panic(err) 114 | } 115 | } 116 | 117 | func resolveTemplateDir(dir string) error { 118 | path, err := filepath.Abs(dir) 119 | if err != nil { 120 | return err 121 | } 122 | if fi, err := os.Stat(path); err != nil { 123 | return fmt.Errorf("cannot read the %s directory: %w", path, err) 124 | } else if !fi.IsDir() { 125 | return fmt.Errorf("%s path is not a directory", path) 126 | } 127 | return nil 128 | } 129 | 130 | func main() { 131 | defer klog.Flush() 132 | 133 | f, err := os.Open(*flConfig) 134 | if err != nil { 135 | klog.Fatalf("failed to open config file: %+v", err) 136 | } 137 | d := json.NewDecoder(f) 138 | d.DisallowUnknownFields() 139 | var config generatorConfig 140 | if err := d.Decode(&config); err != nil { 141 | klog.Fatalf("failed to parse config file: %+v", err) 142 | } 143 | 144 | klog.Infof("parsing go packages in directory %s", *flAPIDir) 145 | pkgs, err := parseAPIPackages(*flAPIDir) 146 | if err != nil { 147 | klog.Fatal(err) 148 | } 149 | if len(pkgs) == 0 { 150 | klog.Fatalf("no API packages found in %s", *flAPIDir) 151 | } 152 | 153 | apiPackages, err := combineAPIPackages(pkgs) 154 | if err != nil { 155 | klog.Fatal(err) 156 | } 157 | 158 | mkOutput := func() (string, error) { 159 | var b bytes.Buffer 160 | err := render(&b, apiPackages, config) 161 | if err != nil { 162 | return "", fmt.Errorf("failed to render the result: %w", err) 163 | } 164 | 165 | // remove trailing whitespace from each html line for markdown renderers 166 | s := regexp.MustCompile(`(?m)^\s+`).ReplaceAllString(b.String(), "") 167 | return s, nil 168 | } 169 | 170 | if *flOutFile != "" { 171 | dir := filepath.Dir(*flOutFile) 172 | if err := os.MkdirAll(dir, 0o755); err != nil { 173 | klog.Fatalf("failed to create dir %s: %v", dir, err) 174 | } 175 | s, err := mkOutput() 176 | if err != nil { 177 | klog.Fatalf("failed: %+v", err) 178 | } 179 | if err := os.WriteFile(*flOutFile, []byte(s), 0o644); err != nil { 180 | klog.Fatalf("failed to write to out file: %v", err) 181 | } 182 | klog.Infof("written to %s", *flOutFile) 183 | } 184 | 185 | if *flHTTPAddr != "" { 186 | h := func(w http.ResponseWriter, r *http.Request) { 187 | now := time.Now() 188 | defer func() { klog.Infof("request took %v", time.Since(now)) }() 189 | s, err := mkOutput() 190 | if err != nil { 191 | fmt.Fprintf(w, "error: %+v", err) 192 | klog.Warningf("failed: %+v", err) 193 | } 194 | if _, err := fmt.Fprint(w, s); err != nil { 195 | klog.Warningf("response write error: %v", err) 196 | } 197 | } 198 | http.HandleFunc("/", h) 199 | klog.Infof("server listening at %s", *flHTTPAddr) 200 | klog.Fatal(http.ListenAndServe(*flHTTPAddr, nil)) 201 | } 202 | } 203 | 204 | // groupName extracts the "//+groupName" meta-comment from the specified 205 | // package's comments, or returns empty string if it cannot be found. 206 | func groupName(pkg *types.Package) string { 207 | m := gengo.ExtractCommentTags("+", pkg.Comments) 208 | v := m["groupName"] 209 | if len(v) == 1 { 210 | return v[0] 211 | } 212 | return "" 213 | } 214 | 215 | func parseAPIPackages(dir string) ([]*types.Package, error) { 216 | p := parser.New() 217 | 218 | pkgsFound, errFind := p.FindPackages(dir + "/...") 219 | if errFind != nil { 220 | return nil, fmt.Errorf("failed to find packages in %s: %w", dir, errFind) 221 | } 222 | klog.Infof("found %d packages", len(pkgsFound)) 223 | 224 | errLoad := p.LoadPackages(pkgsFound...) 225 | if errLoad != nil { 226 | return nil, fmt.Errorf("failed to load packages: %w", errLoad) 227 | } 228 | 229 | scan, err := p.NewUniverse() 230 | if err != nil { 231 | return nil, fmt.Errorf("failed to parse pkgs and types: %w", err) 232 | } 233 | 234 | var pkgs []*types.Package 235 | for _, pkg := range scan { 236 | 237 | klog.V(3).Infof("trying package=%v groupName=%s", p, groupName(pkg)) 238 | 239 | // Do not pick up packages that are in vendor/ as API packages. (This 240 | // happened in knative/eventing-sources/vendor/..., where a package 241 | // matched the pattern, but it didn't have a compatible import path). 242 | if isVendorPackage(pkg) { 243 | klog.V(3).Infof("package=%v coming from vendor/, ignoring.", pkg.Name) 244 | continue 245 | } 246 | 247 | if groupName(pkg) != "" && len(pkg.Types) > 0 || containsString(pkg.DocComments, docCommentForceIncludes) { 248 | klog.V(3).Infof("package=%v has groupName and has types", pkg.Name) 249 | klog.Info("using package=", pkg.Name) 250 | pkgs = append(pkgs, pkg) 251 | } 252 | } 253 | return pkgs, nil 254 | } 255 | 256 | func containsString(sl []string, str string) bool { 257 | for _, s := range sl { 258 | if str == s { 259 | return true 260 | } 261 | } 262 | return false 263 | } 264 | 265 | // combineAPIPackages groups the Go packages by the they 266 | // offer, and combines the types in them. 267 | func combineAPIPackages(pkgs []*types.Package) ([]*apiPackage, error) { 268 | pkgMap := make(map[string]*apiPackage) 269 | var pkgIds []string 270 | 271 | flattenTypes := func(typeMap map[string]*types.Type) []*types.Type { 272 | typeList := make([]*types.Type, 0, len(typeMap)) 273 | 274 | for _, t := range typeMap { 275 | typeList = append(typeList, t) 276 | } 277 | 278 | return typeList 279 | } 280 | 281 | for _, pkg := range pkgs { 282 | apiGroup, apiVersion, err := apiVersionForPackage(pkg) 283 | if err != nil { 284 | return nil, fmt.Errorf("could not get apiVersion for package %s: %w", pkg.Path, err) 285 | } 286 | 287 | typeList := make([]*types.Type, 0, len(pkg.Types)) 288 | for _, t := range pkg.Types { 289 | typeList = append(typeList, t) 290 | } 291 | 292 | id := fmt.Sprintf("%s/%s", apiGroup, apiVersion) 293 | v, ok := pkgMap[id] 294 | if !ok { 295 | pkgMap[id] = &apiPackage{ 296 | apiGroup: apiGroup, 297 | apiVersion: apiVersion, 298 | Types: flattenTypes(pkg.Types), 299 | Constants: flattenTypes(pkg.Constants), 300 | GoPackages: []*types.Package{pkg}, 301 | } 302 | pkgIds = append(pkgIds, id) 303 | } else { 304 | v.Types = append(v.Types, flattenTypes(pkg.Types)...) 305 | v.Constants = append(v.Types, flattenTypes(pkg.Constants)...) 306 | v.GoPackages = append(v.GoPackages, pkg) 307 | } 308 | } 309 | 310 | sort.Sort(sort.StringSlice(pkgIds)) 311 | 312 | out := make([]*apiPackage, 0, len(pkgMap)) 313 | for _, id := range pkgIds { 314 | out = append(out, pkgMap[id]) 315 | } 316 | return out, nil 317 | } 318 | 319 | // isVendorPackage determines if package is coming from vendor/ dir. 320 | func isVendorPackage(pkg *types.Package) bool { 321 | vendorPattern := string(os.PathSeparator) + "vendor" + string(os.PathSeparator) 322 | return strings.Contains(pkg.Dir, vendorPattern) 323 | } 324 | 325 | func findTypeReferences(pkgs []*apiPackage) map[*types.Type][]*types.Type { 326 | m := make(map[*types.Type][]*types.Type) 327 | for _, pkg := range pkgs { 328 | for _, typ := range pkg.Types { 329 | for _, member := range typ.Members { 330 | t := member.Type 331 | t = tryDereference(t) 332 | m[t] = append(m[t], typ) 333 | } 334 | } 335 | } 336 | return m 337 | } 338 | 339 | func isExportedType(t *types.Type) bool { 340 | // TODO(ahmetb) use types.ExtractSingleBoolCommentTag() to parse +genclient 341 | // https://godoc.org/k8s.io/gengo/types#ExtractCommentTags 342 | return strings.Contains(strings.Join(t.SecondClosestCommentLines, "\n"), "+genclient") 343 | } 344 | 345 | func fieldName(m types.Member) string { 346 | v := reflect.StructTag(m.Tags).Get("json") 347 | v = strings.TrimSuffix(v, ",omitempty") 348 | v = strings.TrimSuffix(v, ",inline") 349 | if v != "" { 350 | return v 351 | } 352 | return m.Name 353 | } 354 | 355 | func fieldEmbedded(m types.Member) bool { 356 | return strings.Contains(reflect.StructTag(m.Tags).Get("json"), ",inline") 357 | } 358 | 359 | func isLocalType(t *types.Type, typePkgMap map[*types.Type]*apiPackage) bool { 360 | t = tryDereference(t) 361 | _, ok := typePkgMap[t] 362 | return ok 363 | } 364 | 365 | func renderComments(s []string, markdown bool) string { 366 | s = filterCommentTags(s) 367 | doc := strings.Join(s, "\n") 368 | 369 | if markdown { 370 | // TODO(ahmetb): when a comment includes stuff like "http://" 371 | // we treat this as a HTML tag with markdown renderer below. solve this. 372 | return string(blackfriday.Run([]byte(doc))) 373 | } 374 | return nl2br(doc) 375 | } 376 | 377 | func safe(s string) template.HTML { return template.HTML(s) } 378 | 379 | func nl2br(s string) string { 380 | return strings.Replace(s, "\n\n", string(template.HTML("

")), -1) 381 | } 382 | 383 | func hiddenMember(m types.Member, c generatorConfig) bool { 384 | for _, v := range c.HiddenMemberFields { 385 | if m.Name == v { 386 | return true 387 | } 388 | } 389 | return false 390 | } 391 | 392 | func typeIdentifier(t *types.Type) string { 393 | t = tryDereference(t) 394 | return t.Name.String() // {PackagePath.Name} 395 | } 396 | 397 | // apiGroupForType looks up apiGroup for the given type 398 | func apiGroupForType(t *types.Type, typePkgMap map[*types.Type]*apiPackage) string { 399 | t = tryDereference(t) 400 | 401 | v := typePkgMap[t] 402 | if v == nil { 403 | klog.Warningf("WARNING: cannot read apiVersion for %s from type=>pkg map", t.Name.String()) 404 | return "" 405 | } 406 | 407 | return v.identifier() 408 | } 409 | 410 | // anchorIDForLocalType returns the #anchor string for the local type 411 | func anchorIDForLocalType(t *types.Type, typePkgMap map[*types.Type]*apiPackage) string { 412 | return fmt.Sprintf("%s.%s", apiGroupForType(t, typePkgMap), t.Name.Name) 413 | } 414 | 415 | // linkForType returns an anchor to the type if it can be generated. returns 416 | // empty string if it is not a local type or unrecognized external type. 417 | func linkForType(t *types.Type, c generatorConfig, typePkgMap map[*types.Type]*apiPackage) (string, error) { 418 | t = tryDereference(t) // dereference kind=Pointer 419 | 420 | if isLocalType(t, typePkgMap) { 421 | return "#" + anchorIDForLocalType(t, typePkgMap), nil 422 | } 423 | 424 | arrIndex := func(a []string, i int) string { 425 | return a[(len(a)+i)%len(a)] 426 | } 427 | 428 | // types like k8s.io/apimachinery/pkg/apis/meta/v1.ObjectMeta, 429 | // k8s.io/api/core/v1.Container, k8s.io/api/autoscaling/v1.CrossVersionObjectReference, 430 | // github.com/knative/build/pkg/apis/build/v1alpha1.BuildSpec 431 | if t.Kind == types.Struct || t.Kind == types.Pointer || t.Kind == types.Interface || t.Kind == types.Alias { 432 | id := typeIdentifier(t) // gives {{ImportPath.Identifier}} for type 433 | segments := strings.Split(t.Name.Package, "/") // to parse [meta, v1] from "k8s.io/apimachinery/pkg/apis/meta/v1" 434 | 435 | for _, v := range c.ExternalPackages { 436 | r, err := regexp.Compile(v.TypeMatchPrefix) 437 | if err != nil { 438 | return "", fmt.Errorf("pattern %q failed to compile: %w", v.TypeMatchPrefix, err) 439 | } 440 | if r.MatchString(id) { 441 | tpl, err := texttemplate.New("").Funcs(map[string]interface{}{ 442 | "lower": strings.ToLower, 443 | "arrIndex": arrIndex, 444 | }).Parse(v.DocsURLTemplate) 445 | if err != nil { 446 | return "", fmt.Errorf("docs URL template failed to parse: %w", err) 447 | } 448 | 449 | var b bytes.Buffer 450 | if err := tpl. 451 | Execute(&b, map[string]interface{}{ 452 | "TypeIdentifier": t.Name.Name, 453 | "PackagePath": t.Name.Package, 454 | "PackageSegments": segments, 455 | }); err != nil { 456 | return "", fmt.Errorf("docs url template execution error: %w", err) 457 | } 458 | return b.String(), nil 459 | } 460 | } 461 | klog.Warningf("not found external link source for type %v", t.Name) 462 | } 463 | return "", nil 464 | } 465 | 466 | // tryDereference returns the underlying type when t is a pointer, map, or slice. 467 | func tryDereference(t *types.Type) *types.Type { 468 | for t.Elem != nil { 469 | t = t.Elem 470 | } 471 | return t 472 | } 473 | 474 | // finalUnderlyingTypeOf walks the type hierarchy for t and returns 475 | // its base type (i.e. the type that has no further underlying type). 476 | func finalUnderlyingTypeOf(t *types.Type) *types.Type { 477 | for { 478 | if t.Underlying == nil { 479 | return t 480 | } 481 | 482 | t = t.Underlying 483 | } 484 | } 485 | 486 | func typeDisplayName(t *types.Type, c generatorConfig, typePkgMap map[*types.Type]*apiPackage) string { 487 | s := typeIdentifier(t) 488 | 489 | if isLocalType(t, typePkgMap) { 490 | s = tryDereference(t).Name.Name 491 | } 492 | 493 | switch t.Kind { 494 | case types.Struct, 495 | types.Interface, 496 | types.Alias, 497 | types.Builtin: 498 | // noop 499 | 500 | case types.Pointer: 501 | // Use the display name of the element of the pointer as the display name of the pointer. 502 | return typeDisplayName(t.Elem, c, typePkgMap) 503 | 504 | case types.Slice: 505 | // Use the display name of the element of the slice to build the display name of the slice. 506 | elemName := typeDisplayName(t.Elem, c, typePkgMap) 507 | return fmt.Sprintf("[]%s", elemName) 508 | 509 | case types.Map: 510 | // Use the display names of the key and element types of the map to build the display name of the map. 511 | keyName := typeDisplayName(t.Key, c, typePkgMap) 512 | elemName := typeDisplayName(t.Elem, c, typePkgMap) 513 | return fmt.Sprintf("map[%s]%s", keyName, elemName) 514 | 515 | case types.DeclarationOf: 516 | // For constants, we want to display the value 517 | // rather than the name of the constant, since the 518 | // value is what users will need to write into YAML 519 | // specs. 520 | if t.ConstValue != nil { 521 | u := finalUnderlyingTypeOf(t) 522 | // Quote string constants to make it clear to the documentation reader. 523 | if u.Kind == types.Builtin && u.Name.Name == "string" { 524 | return strconv.Quote(*t.ConstValue) 525 | } 526 | 527 | return *t.ConstValue 528 | } 529 | 530 | klog.Fatalf("type %s is a non-const declaration, which is unhandled", t.Name) 531 | 532 | default: 533 | klog.Fatalf("type %s has kind=%v which is unhandled", t.Name, t.Kind) 534 | } 535 | 536 | // substitute prefix, if registered 537 | for prefix, replacement := range c.TypeDisplayNamePrefixOverrides { 538 | if strings.HasPrefix(s, prefix) { 539 | s = strings.Replace(s, prefix, replacement, 1) 540 | } 541 | } 542 | 543 | return s 544 | } 545 | 546 | func hideType(t *types.Type, c generatorConfig) bool { 547 | for _, pattern := range c.HideTypePatterns { 548 | if regexp.MustCompile(pattern).MatchString(t.Name.String()) { 549 | return true 550 | } 551 | } 552 | if !isExportedType(t) && unicode.IsLower(rune(t.Name.Name[0])) { 553 | // types that start with lowercase 554 | return true 555 | } 556 | return false 557 | } 558 | 559 | func typeReferences(t *types.Type, c generatorConfig, references map[*types.Type][]*types.Type) []*types.Type { 560 | var out []*types.Type 561 | m := make(map[*types.Type]struct{}) 562 | for _, ref := range references[t] { 563 | if !hideType(ref, c) { 564 | m[ref] = struct{}{} 565 | } 566 | } 567 | for k := range m { 568 | out = append(out, k) 569 | } 570 | sortTypes(out) 571 | return out 572 | } 573 | 574 | func sortTypes(typs []*types.Type) []*types.Type { 575 | sort.Slice(typs, func(i, j int) bool { 576 | t1, t2 := typs[i], typs[j] 577 | if isExportedType(t1) && !isExportedType(t2) { 578 | return true 579 | } else if !isExportedType(t1) && isExportedType(t2) { 580 | return false 581 | } 582 | return t1.Name.String() < t2.Name.String() 583 | }) 584 | return typs 585 | } 586 | 587 | func visibleTypes(in []*types.Type, c generatorConfig) []*types.Type { 588 | var out []*types.Type 589 | for _, t := range in { 590 | if !hideType(t, c) { 591 | out = append(out, t) 592 | } 593 | } 594 | return out 595 | } 596 | 597 | func packageDisplayName(pkg *types.Package, apiVersions map[string]string) string { 598 | apiGroupVersion, ok := apiVersions[pkg.Path] 599 | if ok { 600 | return apiGroupVersion 601 | } 602 | return pkg.Path // go import path 603 | } 604 | 605 | func filterCommentTags(comments []string) []string { 606 | var out []string 607 | for _, v := range comments { 608 | if !strings.HasPrefix(strings.TrimSpace(v), "+") { 609 | out = append(out, v) 610 | } 611 | } 612 | return out 613 | } 614 | 615 | func isOptionalMember(m types.Member) bool { 616 | tags := gengo.ExtractCommentTags("+", m.CommentLines) 617 | _, ok := tags["optional"] 618 | return ok 619 | } 620 | 621 | func apiVersionForPackage(pkg *types.Package) (string, string, error) { 622 | group := groupName(pkg) 623 | version := pkg.Name // assumes basename (i.e. "v1" in "core/v1") is apiVersion 624 | r := `^v\d+((alpha|beta|api|stable)[a-z0-9]+)?$` 625 | if !regexp.MustCompile(r).MatchString(version) { 626 | return "", "", fmt.Errorf("cannot infer kubernetes apiVersion of go package %s (basename %q doesn't match expected pattern %s that's used to determine apiVersion)", pkg.Path, version, r) 627 | } 628 | return group, version, nil 629 | } 630 | 631 | // extractTypeToPackageMap creates a *types.Type map to apiPackage 632 | func extractTypeToPackageMap(pkgs []*apiPackage) map[*types.Type]*apiPackage { 633 | out := make(map[*types.Type]*apiPackage) 634 | for _, ap := range pkgs { 635 | for _, t := range ap.Types { 636 | out[t] = ap 637 | } 638 | for _, t := range ap.Constants { 639 | out[t] = ap 640 | } 641 | } 642 | return out 643 | } 644 | 645 | // packageMapToList flattens the map. 646 | func packageMapToList(pkgs map[string]*apiPackage) []*apiPackage { 647 | // TODO(ahmetb): we should probably not deal with maps, this type can be 648 | // a list everywhere. 649 | out := make([]*apiPackage, 0, len(pkgs)) 650 | for _, v := range pkgs { 651 | out = append(out, v) 652 | } 653 | return out 654 | } 655 | 656 | // constantsOfType finds all the constants in pkg that have the 657 | // same underlying type as t. This is intended for use by enum 658 | // type validation, where users need to specify one of a specific 659 | // set of constant values for a field. 660 | func constantsOfType(t *types.Type, pkg *apiPackage) []*types.Type { 661 | constants := []*types.Type{} 662 | 663 | for _, c := range pkg.Constants { 664 | if c.Underlying == t { 665 | constants = append(constants, c) 666 | } 667 | } 668 | 669 | return sortTypes(constants) 670 | } 671 | 672 | func render(w io.Writer, pkgs []*apiPackage, config generatorConfig) error { 673 | references := findTypeReferences(pkgs) 674 | typePkgMap := extractTypeToPackageMap(pkgs) 675 | 676 | t, err := template.New("").Funcs(map[string]interface{}{ 677 | "isExportedType": isExportedType, 678 | "fieldName": fieldName, 679 | "fieldEmbedded": fieldEmbedded, 680 | "typeIdentifier": func(t *types.Type) string { return typeIdentifier(t) }, 681 | "typeDisplayName": func(t *types.Type) string { return typeDisplayName(t, config, typePkgMap) }, 682 | "visibleTypes": func(t []*types.Type) []*types.Type { return visibleTypes(t, config) }, 683 | "renderComments": func(s []string) string { return renderComments(s, !config.MarkdownDisabled) }, 684 | "packageDisplayName": func(p *apiPackage) string { return p.identifier() }, 685 | "apiGroup": func(t *types.Type) string { return apiGroupForType(t, typePkgMap) }, 686 | "packageAnchorID": func(p *apiPackage) string { 687 | // TODO(ahmetb): currently this is the same as packageDisplayName 688 | // func, and it's fine since it returns valid DOM id strings like 689 | // 'serving.knative.dev/v1alpha1' which is valid per HTML5, except 690 | // spaces, so just trim those. 691 | return strings.Replace(p.identifier(), " ", "", -1) 692 | }, 693 | "linkForType": func(t *types.Type) string { 694 | v, err := linkForType(t, config, typePkgMap) 695 | if err != nil { 696 | klog.Fatal(fmt.Errorf("error getting link for type=%s: %w", t.Name, err)) 697 | return "" 698 | } 699 | return v 700 | }, 701 | "anchorIDForType": func(t *types.Type) string { return anchorIDForLocalType(t, typePkgMap) }, 702 | "safe": safe, 703 | "sortedTypes": sortTypes, 704 | "typeReferences": func(t *types.Type) []*types.Type { return typeReferences(t, config, references) }, 705 | "hiddenMember": func(m types.Member) bool { return hiddenMember(m, config) }, 706 | "isLocalType": isLocalType, 707 | "isOptionalMember": isOptionalMember, 708 | "constantsOfType": func(t *types.Type) []*types.Type { return constantsOfType(t, typePkgMap[t]) }, 709 | }).ParseGlob(filepath.Join(*flTemplateDir, "*.tpl")) 710 | if err != nil { 711 | return fmt.Errorf("parse error: %w", err) 712 | } 713 | 714 | var gitCommit []byte 715 | if !config.GitCommitDisabled { 716 | gitCommit, _ = exec.Command("git", "rev-parse", "--short", "HEAD").Output() 717 | } 718 | 719 | if err := t.ExecuteTemplate(w, "packages", map[string]interface{}{ 720 | "packages": pkgs, 721 | "config": config, 722 | "gitCommit": strings.TrimSpace(string(gitCommit)), 723 | }); err != nil { 724 | return fmt.Errorf("template execution error: %w", err) 725 | } 726 | 727 | return nil 728 | } 729 | 730 | func getBuildInfo() (string, string, bool) { 731 | var commitHash, commitTime string 732 | var dirtyBuild bool 733 | info, ok := debug.ReadBuildInfo() 734 | if !ok { 735 | return "", "", false 736 | } 737 | for _, kv := range info.Settings { 738 | switch kv.Key { 739 | case "vcs.revision": 740 | commitHash = kv.Value 741 | case "vcs.time": 742 | commitTime = kv.Value 743 | case "vcs.modified": 744 | dirtyBuild = kv.Value == "true" 745 | } 746 | } 747 | return commitHash, commitTime, dirtyBuild 748 | } 749 | --------------------------------------------------------------------------------