Merge pull request #178 from pwittrock/docs-gen

Update GitBook doc generation page

Author: Phillip Wittrock

docs/book/beyond_basics/generating_documentation.md

@@ -22,14 +22,34 @@ defining the resource.  No blank lines may appear between the annotation and the
 
 ## Creating Examples
 
+{% method %}
+
 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
+file under `docs/reference/examples/<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
 
+{% sample lang="code" %}
+
+> $ kubebuilder create example --kind Frigate --version v1beta1 --group ships
+
+```yaml
+# docs/reference/examples/frigate/frigate.yaml
+note: frigate example
+sample: |
+  apiVersion: v1beta1
+  kind: frigate
+  metadata:
+    name: frigate
+  spec:
+    todo: "write me"
+```
+{% endmethod %}
+
+
 ## Editing Overview and API Group Documentation
 
 Users can modify documentation of the overview and API *groups* by editing the files under
@@ -38,10 +58,39 @@ Users can modify documentation of the overview and API *groups* by editing the f
 - Edit `_overview.md` to provide documentation for the full set of APIs.
 - Edit `_<group>.md` to provide documentation for a specific API group.
 
+## Adding Notes and Warnings for APIs
+
+{% method %}
+
+It is possible to add *notes* and *warnings* to APIs in the reference documentation by annotating
+the go struct with `// +kubebuilder:doc:note=` or `// +kubebuilder:doc:warning=`.  These will
+show up in *blue* and *orange* boxes.
+
+{% sample lang="code" %}
+```go
+// Frigate API documentation goes here.
+// +kubebuilder:doc:note=this is a note
+// +kubebuilder:doc:warning=this is a warning
+// +k8s:openapi-gen=true
+// +kubebuilder:resource:path=frigates
+type Frigate struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+    // Spec field documentation goes here.
+	Spec   FrigateSpec   `json:"spec,omitempty"`
+
+    // Status field documentation goes here.
+	Status FrigateStatus `json:"status,omitempty"`
+}
+```
+{% endmethod %}
+
 ## 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.
+file may be manually changed by users to customize the appearance of the documentation, however this is
+discouraged as the user will need to manually managed the config going forward.
 
 {% panel style="warning", title="Modifying config.yaml" %}
 When manually modifying config.yaml, users must run `kubebuilder docs` with `--generate-config=false` to
@@ -54,57 +103,24 @@ prevent the file from being rewritten.
 
 `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.
+displayed API versions may be manually controlled if needed.
 
-{% sample lang="yaml" %}
+{% sample lang="code" %}
 > generated config.yaml for `kubebuilder create resource --kind Bee --group insect --version v1beta1`
 
 ```yaml
 example_location: "examples"
 api_groups: 
-  - "Insect"
+  - "Ship"
 resource_categories: 
-- name: "Insect"
-  include: "insect"
+- name: "Ship"
+  include: "ship"
   resources: 
-  - name: "Bee"
+  - name: "Frigate"
     version: "v1beta1"
-    group: "insect"
+    group: "ship"
+    description_warning: "test warnings message annotations"
+    description_note: "test notes message annotations"
 ```
 {% 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 %}
-
-
-