See #2898 Generate CRD API docs as AsciiDoc

[djencks]

See #2898.

This presumably needs more work.

• I forked the github.com/ahmetb/gen-crd-api-reference-docs to github.com/djencks/gen-crd-api-reference-docs. I plan to submit a PR but it would be great to get some code review, this is my first foray into go.
• I changed how the generator is installed to usego run. I think this is a good idea in any case, it will work on any system and doesn't need WGET which I can't get to work on my mac.
• The templates render OK but produce a lot of unneeded whitespace and the lack of indentation makes them hard to read. I expect to contribute AsciiDoc generating templates back upstream.

[oscerd]

cc @squakez @astefanutti @nicolaferraro

[djencks]

Preview at https://pr-761--camel.netlify.app/camel-k/next/apis/camel.html

[squakez]

Great job @djencks !!
I only wonder if we can have a better format of the right side menu.

[djencks]

The RHS menu is a consequence of the generated sections from the templates. Can you suggest how you would like it better organized?

I don't understand the reason some embedded members result in a link to a separate section and some result in a nested table. I think nested tables are generally a confusing way to present information and wonder if we should change the templates to always result in a link. What do you think?

[djencks]

I also wonder if it would be a good idea to move all the kamelets documentation to the kamelets subproject, including the kamelets API.

[djencks]

I rearranged the templates a bit so that the RHS menu makes more sense, and each package is on a separate page. Hopefully the preview will build and show the result. There's at least one link that doesn't quite work as expected due to the go array notation [] conflicting with AsciiDoc xref syntax. I think this is fixable.

There are perhaps 4 xrefs from the kamelets api page to the camel-k api page. I wonder how appropriate this is since the idea seems to be to make kamelets rather independent of camel-k. Would it be a better idea to duplicate the common types in both packages?

Before I fixed the references the errors were:

W0123 22:12:45.509224   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.SourceSpec
W0123 22:12:45.509278   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.Template
W0123 22:12:45.509306   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.Flow
W0123 22:12:45.509601   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.IntegrationSpec
W0123 22:12:45.510674   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.RawMessage
W0123 22:12:45.511144   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.RawMessage
W0123 22:12:45.511339   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.RawMessage
W0123 22:12:45.511459   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.RawMessage
W0123 22:12:45.511851   32245 main.go:459] not found external link source for type encoding/json.Number
W0123 22:12:45.511897   32245 main.go:459] not found external link source for type encoding/json.Number
W0123 22:12:45.512027   32245 main.go:459] not found external link source for type encoding/json.Number
W0123 22:12:45.513153   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.IntegrationSpec
W0123 22:12:45.514135   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.SourceSpec
W0123 22:12:45.514165   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.Template
W0123 22:12:45.514199   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.Flow

The encoding/json.Number errors were already present and I don't know how to fix them.

[djencks]

I rearranged the templates a bit so that the RHS menu makes more sense, and each package is on a separate page. Hopefully the preview will build and show the result. There's at least one link that doesn't quite work as expected due to the go array notation [] conflicting with AsciiDoc xref syntax. I think this is fixable.

There are perhaps 4 xrefs from the kamelets api page to the camel-k api page. I wonder how appropriate this is since the idea seems to be to make kamelets rather independent of camel-k. Would it be a better idea to duplicate the common types in both packages?

Before I fixed the references the errors were:

W0123 22:12:45.509224   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.SourceSpec
W0123 22:12:45.509278   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.Template
W0123 22:12:45.509306   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.Flow
W0123 22:12:45.509601   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.IntegrationSpec
W0123 22:12:45.510674   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.RawMessage
W0123 22:12:45.511144   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.RawMessage
W0123 22:12:45.511339   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.RawMessage
W0123 22:12:45.511459   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.RawMessage
W0123 22:12:45.511851   32245 main.go:459] not found external link source for type encoding/json.Number
W0123 22:12:45.511897   32245 main.go:459] not found external link source for type encoding/json.Number
W0123 22:12:45.512027   32245 main.go:459] not found external link source for type encoding/json.Number
W0123 22:12:45.513153   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.IntegrationSpec
W0123 22:12:45.514135   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.SourceSpec
W0123 22:12:45.514165   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.Template
W0123 22:12:45.514199   32245 main.go:459] not found external link source for type github.com/apache/camel-k/pkg/apis/camel/v1.Flow

The encoding/json.Number errors were already present and I don't know how to fix them.

[squakez]

I could not see any new preview after your last changes to see how they appears now :(

[djencks]

There are links from the kamelets page to the camel-k page:

Under https://pr-761--camel.netlify.app/camel-k/next/apis/kamelets.html#_camel_apache_org_v1alpha1_KameletSpec (and the embedded table earlier):

SourceSpec
Template
Flow (deprecated)

Under https://pr-761--camel.netlify.app/camel-k/next/apis/kamelets.html#_camel_apache_org_v1alpha1_KameletBindingSpec (and earlier embedded table)

IntegrationSpec

Can we remove the deprecated Flow and copy the SourceSpec and IntegrationSpec to v1alpha1 and move Template to v1alpha1?

I wonder if there's an error around RawMessage. There's a RawMessage type in both v1 and v1alpha1.

These use v1.RawMessage:
kamelet_binding_types.go EndpointProperties (66)
error_handler_types.go ErrorHandlerSpec (37), ErrorHandlerParameters (42), BeanProperties (47)

This uses v1alpha1.RawMessage:
jsonschema_types.go JSON (106)

Can these all use the v1alpha1 RawMessage?

[djencks]

I'd like to prepare a version without nested tables. I guess the practical way to do this is to have both versions on the same generated page.

[squakez]

I'd like to prepare a version without nested tables. I guess the practical way to do this is to have both versions on the same generated page.

I agree, we should get rid off those nested tables. I also suggest to try to find a way to only show the "resource types" on the right side menu, hiding (only from the menu) the "internal types". We may even try removing that menu at all, we don't have a very long API (at least, the main types).

About moving stuff between versions, it's not doable. We may have some duplicated stuff, due to the fact that each version should be independent (cannot declare both v1 and v1alpha).

[djencks]

I've fixed all the problems I'm aware of in the generator and simplified the templates a bit and like the results. With luck we'll have a preview shortly. I think all the links from kamelets (v1alpha1) to camel-k (v1) work and look correct now.

I don't think it's a good idea to hide the "internal types", why do you think we should?
To do it we'd have to put them one section level deeper.

[squakez]

I don't think it's a good idea to hide the "internal types", why do you think we should?

For simplicity while browsing the API list not to overwhelm visually. However, that's not very important, let's wait for the final result in the preview.

[djencks]

I did a full build for other reasons and discovered the typo fixes propagate to several other files.
I like the preview at https://pr-761--camel.netlify.app/camel-k/next/apis/camel-k.html and https://pr-761--camel.netlify.app/camel-k/next/apis/kamelets.html and think we should merge this (after I squash everything to fewer commits) and improve things from there. We also need to decide if this should be back ported to earlier versions: I'd suggest at least to 1.7.x, and I'm happy to back port it to the other two also.

[squakez]

Looks good for me either. Thanks for taking care of it!