api-docs/

README

Generating API Reference Documentation

• 1. Fork Frisbee repository
• 2. Set up the Kubernetes Custom Resource API Reference Docs generator
• 3. Generate the API reference docs

This document describes the process to generate custom API reference documentation meant to be served on Frisbee's docs website.

1. Fork Frisbee repository

1. Visit https://github.com/CARV-ICS-FORTH/frisbee.

2. Click the Fork button and clone your fork.

2. Set up the Kubernetes Custom Resource API Reference Docs generator

1. Visit https://github.com/ahmetb/gen-crd-api-reference-docs.
2. Clone to repository locally.
3. Run go build from the root of the repository to generate the gen-crd-api-reference-docs binary executable.

3. Generate the API reference docs

From the root of the osm repository, use the gen-crd-api-reference-docs binary to generate custom API reference documentation based on the Go API definititions present within the osm repository.

For example, to generate API reference docs for the Scenario custom API defined in /api/v1alpha1/:

<path to api doc generator repo>/gen-crd-api-reference-docs -config `pwd`/docs/api_reference/config.json \
    -api-dir "github.com/carv-ics-forth/frisbee/api/v1alpha1" \
    -template-dir
    <full path to api doc generator repo>/template/ \
        -out-file `pwd`/site/docs/api_reference/config/v1alpha1.md
        ```


        ## 4. Customize the generated doc for the website

        [Frisbee's website](https://frisbee.dev/) is built using Hugo and requires every page to have a [Front
        Matter](https://gohugo.io/content-management/front-matter/) defined.

        Add the `Front Matter` to the generated docs so they render correctly on the website.

        For example, a `Front Matter` looks as follows:
        ```
        ---
        title: "Policy v1alpha1 API Reference"
        description: "Policy v1alpha1 API reference documentation."
        type: docs
        ---
        ```

        Add `_index.md` files to intermediary directories if necessary.


        ## 5. Create a pull request in the [Frisbee](https://github.com/CARV-ICS-FORTH/frisbee) repository

        Commit the generated API reference documentation and create a pull request in
        [Frisbee](https://github.com/CARV-ICS-FORTH/frisbee) repository.