[DOC] Contributing guide update to describe Custom Resource API Reference build (strimzi#3541)

* [DOC] Contributing guide update to describe Custom Resource API Reference build

Signed-off-by: prmellor <[email protected]>

* review edits JS

Signed-off-by: prmellor <[email protected]>

* review edits DL

Signed-off-by: prmellor <[email protected]>

Author: PaulRMellor

documentation/contributing/introduction.adoc

@@ -36,18 +36,20 @@ Assemblies, which usually encapsulate a feature or process, bring the related co
 An assembly is like a sub-section or chapter in a book.
 For example, the _Deploying Strimzi_ guide has a chapter called _Verifying the Strimzi deployment_, which is contained in its own assembly.
 
+.Documentation folder descriptions
 [source,options="nowrap",subs="+quotes"]
 ----
-contributing/                        # Documentation contributor guide (this book)
-deploying/                           # Deploying Strimzi
-quickstart/                          # Strimzi Quick Start guide
-overview/                            # Strimzi Overview guide
-using/                               # Using Strimzi
-assemblies/                          # Assemblies provide content for all guides
-modules/                             # Modules provide the content for assemblies
-shared/                              # Shared include files
-shared/attributes.adoc               # Global book attributes
-shared/images/                       # Shared image files
+api/                          # Property descriptions for the Custom Resource API Reference section of the Using Strimzi guide
+contributing/                 # Documentation contributor guide (this book)
+deploying/                    # Deploying Strimzi
+quickstart/                   # Strimzi Quick Start guide
+overview/                     # Strimzi Overview guide
+using/                        # Using Strimzi
+assemblies/                   # Assemblies provide content for all guides
+modules/                      # Modules provide the content for assemblies
+shared/                       # Shared include files
+shared/attributes.adoc        # Global book attributes
+shared/images/                # Shared image files
 ----
 
 === Strimzi Overview guide
@@ -80,4 +82,59 @@ In contrast to the _Deploying_ guide, this guide provides a reduced set of instr
 
 The _Using Strimzi_ guide provides configuration instructions for Kafka components, and instructions for using Strimzi Operators.
 The majority of the content relates to how you might want to modify your deployment and introduce additional features, such as Cruise Control or distributed tracing.
-The _Using Strimzi_ guide also contains the API reference guide which is generated directly from the Java code of the operators.
+
+=== Custom Resource API Reference
+
+The _Using Strimzi_ guide (documentation/using/master.adoc) also contains a _Custom Resource API Reference_ that describes the configuration properties for custom resources.
+
+The _Custom Resource API Reference_ is built from two files.
+
+.Custom Resource API Reference files
+[source,asciidoc,options="nowrap"]
+----
+\include::modules/con-common-configuration-properties.adoc[leveloffset=+1]
+\include::modules/appendix_crds.adoc[]
+----
+
+The `con-common-configuration-properties.adoc` file contains descriptions of common configuration properties.
+The content for the `documentation/modules/appendix_crds.adoc` file is generated directly from descriptions in the Java code.
+
+Java files in the `api/` folder are annotated so that the descriptions are picked up in the build.
+
+.Java annotations for documentation
+[source,java,options="nowrap"]
+----
+import io.strimzi.crdgenerator.annotations.Description;
+import io.strimzi.crdgenerator.annotations.DescriptionFile;
+----
+
+The tables in `appendix_crds.adoc` are built from `@Description` annotations in the Java files.
+
+Additional information is included by adding:
+
+. An `@DescriptionFile` annotation to the Java file
+. A corresponding description file (`.adoc`) in the `documentation/api/` folder
+. An `include:__DESCRIPTION-FILE-NAME__` reference to the `appendix_crds.adoc`
+
+The `include:__DESCRIPTION-FILE-NAME__` reference is added automatically by the Maven build, so you do not need to add it manually.
+
+For example, to add additional configuration for the `KafkaUserQuotas` custom resource:
+
+. `api/src/main/java/io/strimzi/api/kafka/model/KafkaUserQuotas.java` contains:
+** `import io.strimzi.crdgenerator.annotations.Description`
+** `import io.strimzi.crdgenerator.annotations.DescriptionFile`
+** `@Description("_descriptions for individual properties..._");`
+** An `@DescriptionFile` annotation
+. `documentation/api` includes the `io.strimzi.api.kafka.model.KafkaUserQuotas.adoc` file containing the additional configuration description.
++
+The description file requires the same name as the related Java package.
+. `appendix_crds.adoc` contains a reference to include the additional configuration description:
++
+[source,asciidoc,options="nowrap"]
+----
+### `KafkaUserQuotas` schema reference
+
+/include::../api/io.strimzi.api.kafka.model.KafkaUserQuotas.adoc[leveloffset=+1]
+----
+
+If you change anything in the `api` module of the Java code, you must rebuild the _Custom Resource API Reference_ using a xref:make-tooling[make command].

documentation/contributing/make-tooling.adoc

@@ -12,15 +12,19 @@ Make is a useful tool for building your documentation and pushing it to a public
 `make docu_html`:: Generate the HTML version of all the guides (the HTML files can be found in `documentation/html)
 `make docu_htmlnoheader`:: Generate the HTML version of all the guides without the HTML headers so they are suitable for including into a website (the HTML files can be found in `documentation/htmlnoheader)
 
-== Generate the API Reference
+== Generate the Custom Resource API Reference
 
-The API Reference is stored in the `documentation/modules/appendix_crds.adoc` file.
+The `documentation/modules/appendix_crds.adoc` file provides the main content for the _Custom Resource API Reference_.
 It is generated directly from the Java code when building the operators.
-If you change the Strimzi API, you need to regenerate the API Reference with following command:
+
+If you change the Strimzi API, you need to regenerate the API Reference before submitting your PR by running the following from the root:
 
 [source,shell,subs=attributes+]
 ----
 mvn clean -DskipTests install
+make crd_install
 ----
 
-NOTE: You have to generate the API Reference only if you changed anything in the `api` module of the Java code.
+The build uses https://github.com/mikefarah/yq[`yq`^], so make sure it is kept up-to-date for it to work properly.
+
+NOTE: You only have to generate the _Custom Resource API Reference_ if you changed anything in the `api` module of the Java code.