Giters

ahmetb / gen-crd-api-reference-docs

API Reference Docs generator for Kubernetes CRDs (used by Knative, Kubeflow and others)

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Option to generate AsciiDoc output

djencks opened this issue · comments

commented

For Apache Camel-K I've modified this project, adding an option to generate AsciiDoc output rather than html. The current results can be seen here:

https://camel.apache.org/camel-k/next/apis/camel-k.html
https://camel.apache.org/camel-k/next/apis/kamelets.html

The code modifications are:

  • a config flag to indicate AsciiDoc output
  • some escaping of comment content to avoid interference with Asciidoc table syntax, attribute syntax, and highlighting syntax
  • more AsciiDoc-friendly ID names (this is currently always-on, not under control of the flag)
  • a method to escape link text, that can be called from templates
  • use of text/Template rather than html/Template, controlled by the flag. There is probably a better way than I found to implement this, but as a Go beginner I wasn't able to find it. Advice here would be greatly appreciated.

I also have two sets of templates:

  • one is pretty much a translation of the html template to AsciiDoc
  • one (used for camel-k) is adapted for use in Antora, with one package per page.

If there's interest in bringing these capabilities into the project, I'd like to start discussing what would be needed to do so. In particular...

  • What testing against existing uses would be appropriate?
  • Where could one or both sets of AsciiDoc templates go?

Note that #11 includes a separate function that can be called from a template that also produces more AsciiDoc-friendly IDs.