{"id":15044580,"url":"https://github.com/elastic/crd-ref-docs","last_synced_at":"2025-05-15T07:06:02.763Z","repository":{"id":37900828,"uuid":"231115418","full_name":"elastic/crd-ref-docs","owner":"elastic","description":"Generates Kubernetes CRD API reference documentation","archived":false,"fork":false,"pushed_at":"2025-05-09T07:51:46.000Z","size":302,"stargazers_count":126,"open_issues_count":24,"forks_count":58,"subscribers_count":67,"default_branch":"master","last_synced_at":"2025-05-12T00:17:34.110Z","etag":null,"topics":["docs","go","kubernetes"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elastic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-12-31T16:10:06.000Z","updated_at":"2025-05-09T21:09:32.000Z","dependencies_parsed_at":"2023-10-04T17:55:13.200Z","dependency_job_id":"383ebc7e-3556-4da4-94d7-9ab749640999","html_url":"https://github.com/elastic/crd-ref-docs","commit_stats":{"total_commits":51,"total_committers":18,"mean_commits":"2.8333333333333335","dds":0.7254901960784313,"last_synced_commit":"0ad85c56e5a611240525e8b4a641b9cee33acd9a"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fcrd-ref-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fcrd-ref-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fcrd-ref-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fcrd-ref-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elastic","download_url":"https://codeload.github.com/elastic/crd-ref-docs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254292042,"owners_count":22046426,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docs","go","kubernetes"],"created_at":"2024-09-24T20:50:45.074Z","updated_at":"2025-05-15T07:05:57.754Z","avatar_url":"https://github.com/elastic.png","language":"Go","readme":"![](https://github.com/elastic/crd-ref-docs/workflows/Build/badge.svg)\n\n# CRD Reference Documentation Generator\n\nGenerates API reference documentation by scanning a source tree for exported CRD types.\n\nThis is a fresh implementation inspired by the https://github.com/ahmetb/gen-crd-api-reference-docs project. While trying to adopt the `gen-crd-api-refernce-docs` to generate documentation for [Elastic Cloud on Kubernetes](https://github.com/elastic/cloud-on-k8s), we encountered a few shortcomings such as the lack of support for Go modules, slow scan times, and rendering logic that was hard to adapt to Asciidoc (our preferred documentation markup language). This project attempts to address those issues by re-implementing the type discovery logic and decoupling the rendering logic so that different markup formats can be supported.\n\n## Usage\n\nPre-built Linux binaries can be downloaded from the Github Releases tab. Alternatively, you can download and build the source with Go tooling:\n\n```\ngo get -u github.com/elastic/crd-ref-docs\n```\n\nThe tool can be invoked as follows to generate documentation:\n\n```\ncrd-ref-docs \\\n    --source-path=$GOPATH/src/github.com/elastic/cloud-on-k8s/pkg/apis \\\n    --config=config.yaml\n```\n\nBy default, documentation is rendered in Asciidoc format. In order to generate documentation in Markdown format, you will have to specify the `markdown` renderer:\n\n```\ncrd-ref-docs \\\n    --source-path=$GOPATH/src/github.com/elastic/cloud-on-k8s/pkg/apis \\\n    --config=config.yaml \\\n    --renderer=markdown\n```\n\nDefault templates are embedded in the binary. You may provide your own templates by specifying the templates directory:\n\n```\ncrd-ref-docs \\\n    --source-path=$GOPATH/src/github.com/elastic/cloud-on-k8s/pkg/apis \\\n    --config=config.yaml \\\n    --renderer=asciidoctor \\\n    --templates-dir=templates/asciidoctor\n```\n\nDefault output mode writes all data to a single output file. \nYou can choose between single mode and group mode by specifying the output mode. \nIn group mode, separate files are created for each API group, ensuring that the specified output path is an existing directory.\n```\ncrd-ref-docs \\\n    --source-path=$GOPATH/src/github.com/elastic/cloud-on-k8s/pkg/apis \\\n    --config=config.yaml \\\n    --output-path=./docs \\\n    --output-mode=group\n```\n\n### Configuration\n\nConfiguration options such as types and fields to exclude from the documentation can be specified using a YAML file.\n\n```yaml\nprocessor:\n  # RE2 regular expressions describing types that should be excluded from the generated documentation.\n  ignoreTypes:\n    - \"(Elasticsearch|Kibana|ApmServer)List$\"\n    - \"(Elasticsearch|Kibana|ApmServer)Health$\"\n    - \"(Elasticsearch|Kibana|ApmServer|Reconciler)Status$\"\n    - \"ElasticsearchSettings$\"\n    - \"Associa(ted|tor|tionStatus|tionConf)$\"\n  # RE2 regular expressions describing type fields that should be excluded from the generated documentation.\n  ignoreFields:\n    - \"status$\"\n    - \"TypeMeta$\"\n\nrender:\n  # Version of Kubernetes to use when generating links to Kubernetes API documentation.\n  kubernetesVersion: 1.22\n  # Generate better link for known types\n  knownTypes:\n    - name: SecretObjectReference\n      package: sigs.k8s.io/gateway-api/apis/v1beta1\n      link: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.SecretObjectReference\n```\n\n### Advanced Features\n\n#### Custom Markers\n\nYou can add custom markers to your CRD types to provide additional information in the generated documentation.\nFor example, you can add a `hidefromdoc` marker to indicate that a type is hide from the documentation.\n\n```yaml\nprocessor:\n ignoreGroupVersions:\n   - \"GVK\"\n ignoreTypes:\n   - \"Embedded[2-4]$\"\n ignoreFields:\n   - \"status$\"\n   - \"TypeMeta$\"\n customMarkers:\n   - name: \"hidefromdoc\"\n     target: field\n\nrender:\n kubernetesVersion: 1.25\n knownTypes:\n   - name: SecretObjectReference\n     package: sigs.k8s.io/gateway-api/apis/v1beta1\n     link: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.SecretObjectReference\n```\n\nYou can then add the `hidefromdoc` marker to the field you want to hidden from the documentation. Markers can be added\nto fields, types and packages. The `target` field in the configuration specifies the target of the marker (it can be either\n`field`, `type` or `package`).\n\n```go\ntype Embedded1 struct {\n\tEmbedded2 `json:\",inline\"`\n\t// +hidefromdoc\n\tE         string `json:\"e,omitempty\"`\n\tEmbeddedX `json:\",inline\"`\n}\n```\n\nThen update the templates to render the custom markers. You can find an example [here](./test/templates/markdown/type.tpl).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felastic%2Fcrd-ref-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felastic%2Fcrd-ref-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felastic%2Fcrd-ref-docs/lists"}