Giter Club home page Giter Club logo

gen-crd-api-reference-docs's Introduction

Kubernetes Custom Resource API Reference Docs generator

If you have a project that is providing Custom Resource Definitions and wanted to generate API Reference Docs like this this tool is for you.

Alternatives

This project has inspired creation of the following projects:

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.

Current Users

Also some forks:

  • elastic/crd-ref-docs: A fresh re-implementation inspired by this project that supports AsciiDoc. Used by Elastic Cloud on Kubernetes API reference docs.

Why

Normally you would want to use the same docs generator as Kubernetes API reference, but here's why I wrote a different parser/generator:

  1. Today, Kubernetes API does not provide OpenAPI specs for CRDs (e.g. Knative), therefore the gen-apidocs generator used by Kubernetes won't work.

  2. Even when Kubernetes API starts providing OpenAPI specs for CRDs, your CRD must have a validation schema (e.g. Knative API doesn't!)

  3. Kubernetes gen-apidocs parser relies on running a kube-apiserver and calling /apis endpoint to get OpenAPI specs to generate docs. This tool doesn't need that!

How

This is a custom API reference docs generator that uses the k8s.io/gengo project to parse types and generate API documentation from it.

Capabilities of this tool include:

  • Doesn't depend on OpenAPI specs, or kube-apiserver, or a running cluster.
  • Relies only on the Go source code (pkg/apis/**/*.go) to parse API types.
  • Can link to other sites for external APIs. For example, if your types have a reference to Kubernetes core/v1.PodSpec, you can link to it.
  • Configurable settings to hide certain fields or types entirely from the generated output.
  • Either output to a file or start a live http-server (for rapid iteration).
  • Supports markdown rendering from godoc type, package and field comments.

Try it out

  1. Clone this repository.

  2. Make sure you have go1.11+ installed. Then run go build, you should get a gen-crd-api-reference-docs binary executable in the current directory.

  3. Clone a Knative repository, set GOPATH correctly, and call the compiled binary within that directory.

    # go into a repository root with GOPATH set. (I use my own script
    # goclone(1) to have a separate GOPATH for each repo I clone.)
    $ goclone knative/build
    
    $ /path/to/gen-crd-api-reference-docs \
        -config "/path/to/example-config.json" \
        -api-dir "github.com/knative/build/pkg/apis/build/v1alpha1" \
        -out-file docs.html
  4. Visit docs.html to view the results.


This is not an official Google project. See LICENSE.

gen-crd-api-reference-docs's People

Contributors

ahmetb avatar lucacome avatar theunrepentantgeek avatar alanconway avatar alculquicondor avatar bandesz avatar davidebianchi avatar erikgb avatar fpetkovski avatar grantr avatar super-harsh avatar ialidzhikov avatar munnerz avatar jpeach avatar julz avatar mamachanko avatar squakez avatar rbino avatar richardsliu avatar tamalsaha avatar dependabot[bot] avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.