Documentation: Auto-generate API doc

Add a script using `crd-ref-docs` to generate our CRD documentation.
Add entry in Makefile so that the documentation must be up-to-date
if the API is modified.
Create a "reference" section the doc to document API and CLI.
Add entry in CONTRIBUTING.md about how to contribute to the
documentation.

Change-Id: I28e01dd9da5f8a4906c8398daf255cc803dff87d

CONTRIBUTING.md

@@ -33,5 +33,23 @@ Before submitting a change or a patch chain for review, please consider the foll
 
 1. Are the commit messages clear and explanatory?
 1. Do the changes need to be documented in the changelog?
-1. Do the changes cover any required modification of the existing documentation?
+1. Do the changes cover any required modification of the existing documentation? (see [guidelines](#documentation-guidelines) below)
 1. Are the changes tested? We do not require unit testing but do expect functional testing coverage.
+
+## Documentation guidelines
+
+The documentation is written in Markdown, as implemented by GitHub Pages. Please refer to
+[this documentation](https://www.markdownguide.org/tools/github-pages/) to check what elements are supported.
+
+Any change that implements a new feature or significantly changes an existing one must be reflected
+in the documentation, in the impacted section(s).
+
+### API Documentation
+
+The API documentation is auto-generated with [crd-ref-docs](https://github.com/elastic/crd-ref-docs).
+
+Running `make` or `make build` or `make build-api-doc` will update the API documentation if needed.
+
+### CLI Documentation
+
+For now the CLI documentation must be updated by hand.

Makefile

@@ -84,9 +84,13 @@ dev-deployment:
 ##@ Build
 
 .PHONY: build
-build: generate fmt vet sc ## Build manager binary.
+build: generate fmt vet sc build-api-doc ## Build manager binary.
 	go build -o bin/manager main.go
 
+.PHONY: build-api-doc
+build-api-doc: # Build the API documentation.
+	./tools/build-api-doc.sh
+
 .PHONY: run
 run: manifests generate fmt vet ## Run a controller from your host.
 	go run ./main.go

README.md

@@ -71,7 +71,7 @@ The current project status is: **Alpha - NOT PRODUCTION READY**
 * [Deployment documentation](https://softwarefactory-project.github.io/sf-operator/deployment/): this documentation covers the essentials for people or teams who intend to deploy and manage Zuul and its dependencies through the SF-Operator.
 * [Developer documentation](https://softwarefactory-project.github.io/sf-operator/developer/): this documentation describes how to set up a development and testing environment to develop the SF-Operator.
 * [End User documentation](https://softwarefactory-project.github.io/sf-operator/user/): for users of a Software Factory instance. This documentation mostly describes the `Software Factory's config repository` usage (configuration-as-code).
-* [CLI refererence](https://softwarefactory-project.github.io/sf-operator/cli/)
+* [CLI refererence](https://softwarefactory-project.github.io/sf-operator/reference/cli/)
 
 ## Getting Help
 

doc/_apidoc/config.yaml

@@ -0,0 +1,11 @@
+processor:
+  ignoreFields:
+    - "status$"
+    - "TypeMeta$"
+
+render:
+  kubernetesVersion: 1.24
+  knownTypes:
+    - name: Quantity
+      package: k8s.io/apimachinery/pkg/api/resource
+      link: https://pkg.go.dev/k8s.io/[email protected]/pkg/api/resource#Quantity

doc/index.md

@@ -2,11 +2,11 @@
 
 Welcome to SF-Operator's documentation. To know more about the project's purpose,
 please consult the [README](./README.md).
+
 ## Table of Contents
 
 1. [Operator documentation](./operator/index.md)
 1. [Deployment documentation](./deployment/index.md)
 1. [Developer documentation](./developer/index.md)
 1. [End User documentation](./user/index.md)
-1. [CLI reference](./cli/index.md)
-1. [Architectural Decision Records](./adr/index.md)
+1. [Reference](./reference/index.md)