website/gen-api-reference

This folder contains scripts that automatically generate API reference pages for Kubeflow.

Generating API References for Custom Resources

The tool used here can be found at https://github.com/ahmetb/gen-crd-api-reference-docs.

Prerequisites

• Clone this repository (website)
• Clone the repository for which you are generating reference (e.g. kubeflow/tf-operator).

Installation

1. Download the tool from https://github.com/ahmetb/gen-crd-api-reference-docs/releases.

2. Extract the tool to a local directory, for example:

tar -xvf gen-crd-api-reference-docs_linux_amd64.tar.gz -C gen-crd-api-reference-docs

Usage

1. Open up gen-tfjob-api.sh script.

2. Set the GEN_DOCS variable to where you have gen-crd-api-reference-docs extracted.

3. Set the WEBSITE_ROOT variable to where your website repository is cloned. For example:

   WEBSITE_ROOT=$GOPATH/src/github.com/kubeflow/website
   

4. Go to the directory where your API repository is cloned. The tool assumes that you are at the root of the repo, and that your GOPATH is set properly. For example:

   cd $GOPATH/src/github.com/kubeflow/tf-operator/
   

5. Run the gen-tfjob-api.sh script.

6. Run git diff to verify the changes.

7. Create a PR to merge your changes.

Generating the Pipelines API Reference Page

Use these instructions to generate an updated copy of the Pipelines API Reference.

Prerequisites

• Clone the kubeflow/pipelines repository.

• Install npm.

• Install bootprint and html-inline using the following command.

  npm install -g bootprint
  npm install -g bootprint-openapi
  npm install -g html-inline
  

Usage

1. Run the following command to generate the updated documentation.

   bootprint openapi <swagger file> <target directory>
   

   For example:

   bootprint openapi C:\path\to\pipelines\backend\api\swagger\kfp_api_single_file.swagger.json C:\path\to\target\directory
   

2. From the target directory, run the following command to combine the html and css files, naming the output file kubeflow-pipeline-api-spec.html.

   html-inline -i <input file> -o <output file>
   

   For example:

   html-inline -i index.html -o kubeflow-pipeline-api-spec.html
   

3. In a fork of the kubeflow/website repository, overwrite content/docs/components/pipelines/reference/api/kubeflow-pipeline-api-spec.html with the new copy and submit a pull request. Refer to the kubeflow/website readme for more detailed instructions.