Inference Graph YAML unformatted

[yolk-pie-L]

Expected Behavior

When I was learning how to use InferenceGraph, I noticed that the API documentation YAML does not have proper indentation.

You can check it at https://kserve.github.io/website/0.11/reference/api/#serving.kserve.io/v1alpha1.InferenceRouter

Actual Behavior

The entire YAML file lacks any indentation, with all code being indented to the left.

Additional Info

Additional context
Add any other context about the problem here.

[spolti]

Very nice finding @yolk-pie-L, if you want to contribute by fixing it, feel free, it will be really appreciated :)

[spolti]

@yuzisun @ckadner @terrytangyuan Hey guys, I was investigating this issue and found that:

These yaml files are loaded from: https://github.com/kserve/kserve/blob/master/pkg/apis/serving/v1alpha1/inference_graph.go#L104

and this script will generate the reference api doc.

The script above uses this tool to read all the api files and build this api.md

However, the tool that reads the comments from the go files seems to be removing all the spaces from the yaml chunks.

On the other hand, if we try to add something like tabulations, (simple pressing tab) go fmt would remove that from the comments.

With that said, the only way I found to make the indentation to work with the current approach, is a little bit hacky, but solves the issue we have by updating these contents from go comments by adding tabulation controller chaaracter.
The proposed solution looks like:

1 - add tabulation character in the go comments, like (kserve/kserve side):

// ```yaml
//
// kind: InferenceGraph
// metadata:
//
// \tname: canary-route
//
// spec:
//
// \tnodes:
//
//\t\troot:
//\t\t\trouterType: Splitter
...

2- And in the kserve/website, have a script to read these comments and apply the tabulation, e.g.:

...
        indented_line=""
        while [[ $next_line != "</code></pre>" ]]; do
            # Add break lines
            indented_line+="$next_line\n"
            # Read the next line
            read -r next_line
        done
        # Print the indented YAML content by applying the tabs
        tabs 2
        echo -e $indented_line
...

3 - call this script inside the gen-api-reference-docs.sh to properly format it, it will output in the docs/reference/api.md something like this:

<p>InferenceRouter defines the router for each InferenceGraph node with one or multiple steps</p>
<pre><code class="language-yaml">
kind: InferenceGraph                                                                                                                                                                                                  
metadata:
  name: canary-route
spec:
  nodes:
    root:
      routerType: Splitter
...

Please let me know what you think about it, this approach is basically done in my end, I can send the PRs for a better review.

[yolk-pie-L]

The yaml file in the inference_graph.go cannot work, I have tried it. I think it is only for demonstration, but not a real file that follows the api. So to fix the documentation, I think we need to rewrite the yaml file.
@spolti

[spolti]

@yolk-pie-L my guess it that it was done this way to keep easier to generate the api reference doc, this approach have this downside part. Let's wait others to see what we can do :)

[ckadner]

Interesting find. Reading about the tool makes me think it's time to switch to a more modern and currently maintained approach/tool:

https://github.com/ahmetb/gen-crd-api-reference-docs?tab=readme-ov-file#alternatives

Alternatives
This project has inspired creation of the following projects:

[Kubernetes reference-docs generator](https://github.com/kubernetes-sigs/reference-docs): used in [official Kubernetes component reference docs](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)

[crd-ref-docs by Elastic](https://github.com/elastic/crd-ref-docs): A fresh implementation of this project.

Nowadays, I don't have a lot of time to maintain this tool. So consider using one of the above in case this repo does not work for you.

If you're an open source project, consider exposing your CRD API Reference via https://doc.crds.dev/ without much effort.