-
Notifications
You must be signed in to change notification settings - Fork 1.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #129 from pwittrock/gitbook-original
Add / Update GitBook *Test* and *Docs* chapters
- Loading branch information
Showing
4 changed files
with
140 additions
and
16 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,106 @@ | ||
{% panel style="info", title="Under Development" %} | ||
This book is being actively developed. | ||
{% endpanel %} | ||
|
||
# Generating API Documentation | ||
|
||
Kubebuilder will generate API reference documentation for your APIs with `kubebuilder docs`. The | ||
reference documentation will be built under `docs/reference/build/index.html` and can be opened | ||
directly in a web browser. | ||
|
||
- Use `--docs-copyright` to set the copyright footer | ||
- Use `--title` to set the title | ||
|
||
{% panel style="info", title="Non-Kubebuilder Projects" %} | ||
Kubebuilder can also be used to generate API reference documentation for non-kubebuilder projects, as long as the | ||
resources are annotated with `// +kubebuilder:resource` the same as they are in kubebuilder projects. | ||
{% endpanel %} | ||
|
||
## Creating Examples | ||
|
||
Users can provide resource examples by running | ||
`kubebuilder create example --kind <kind> --group <group> --version <version> `. This will create an example | ||
file under `docs/reference/kind/kind.yaml` for the user to edit. The contents of this file will appear | ||
next to the API reference documentation after rerunning `kubebuilder docs`. | ||
|
||
- `note:` description that will appear directly above the example | ||
- `sample:` example yaml that will be displayed | ||
|
||
## Editing Overview and API Group Documentation | ||
|
||
Users can modify documentation of the overview and API *groups* by editing the files under | ||
`docs/reference/static_includes`. | ||
|
||
- Edit `_overview.md` to provide documentation for the full set of APIs. | ||
- Edit `_<group>.md` to provide documentation for a specific API group. | ||
|
||
## Customizing the API documentation | ||
|
||
The generated documentation is controller by the `docs/reference/config.yaml` file generated by kubebuilder. This | ||
file may be manually changed by users to customize the appearance of the documentation. | ||
|
||
{% panel style="warning", title="Modifying config.yaml" %} | ||
When manually modifying config.yaml, users must run `kubebuilder docs` with `--generate-config=false` to | ||
prevent the file from being rewritten. | ||
{% endpanel %} | ||
|
||
#### Table of Contents | ||
|
||
{% method %} | ||
|
||
`docs/reference/config.yaml` is automatically generated to create a section for each API group including | ||
the APIs in the group, and to show the most mature versions of each API. Both the API sections and | ||
displayed API versions may be manually controlled. | ||
|
||
{% sample lang="yaml" %} | ||
> generated config.yaml for `kubebuilder create resource --kind Bee --group insect --version v1beta1` | ||
```yaml | ||
example_location: "examples" | ||
api_groups: | ||
- "Insect" | ||
resource_categories: | ||
- name: "Insect" | ||
include: "insect" | ||
resources: | ||
- name: "Bee" | ||
version: "v1beta1" | ||
group: "insect" | ||
``` | ||
{% endmethod %} | ||
#### Adding Notes and Warnings to APIs | ||
{% method %} | ||
- Add a note to include more information about a particular resource by providing html in a `description_note:`. | ||
- Add a warning about a particular resource by providing html in a `description_warning:`. | ||
- Inline field definitions beneath the Resource (the same way they are done for Spec and Status) by adding a | ||
`inline_definitions:` section. | ||
- `name:` the display name of the Section | ||
- `match:` the naming pattern of fields to inline, where `${resource}` is the name of the resource. | ||
|
||
{% sample lang="yaml" %} | ||
> modified config.yaml for `kubebuilder create resource --kind Bee --group insect --version v1beta1` | ||
|
||
```yaml | ||
example_location: "examples" | ||
api_groups: | ||
- "Insect" | ||
inline_definitions: | ||
- name: Something | ||
match: ${resource}Something | ||
resource_categories: | ||
- name: "Insect" | ||
include: "insect" | ||
resources: | ||
- name: "Bee" | ||
version: "v1beta1" | ||
group: "insect" | ||
description_note: "More information <a href=\"link to info\">here</a>" | ||
description_warning: "Warning about this. <a href=\"link to info\">More information.</a>" | ||
``` | ||
{% endmethod %} | ||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters