Option and code to generate AsciiDoc friendly output #45
Conversation
main.go Outdated
| // anchorIDForLocalType returns the #anchor string for the local type | ||
| func anchorIDForLocalType(t *types.Type, typePkgMap map[*types.Type]*apiPackage) string { | ||
| return fmt.Sprintf("%s.%s", apiGroupForType(t, typePkgMap), t.Name.Name) | ||
| return sanitizeId(fmt.Sprintf("%s.%s", apiGroupForType(t, typePkgMap), t.Name.Name)) |
There was a problem hiding this comment.
this is a breaking change as I understand it, hence not quite desirable
There was a problem hiding this comment.
I wasn't sure if you'd consider this a breaking change: I have no problem changing it. I see three options:
- introduce a
sanitizeIdfunction called from templates, similar to theasciiDocAttributeEscapemethod I introduced. This is certainly the least complex and most flexible, but increases the API exposed to templates. - sanitize ids based on the
asciiDocflag. This will probably end up with the most complex code, and will be the least flexible: perhaps users wanting html generation will want to have simplified IDs. - introduce a
sanitizeIdflag.
I lean towards the first solution, exposing a sanitizeId function to templates. What is your preference?
There was a problem hiding this comment.
I went ahead and pushed a commit to expose a sanitizeId method. I had to add a tryDereference to anchorIDForLocalType: I think exposing this to templates without the dereference was a bug.
Travis was using Go 1.11: I updated to 1.12 to allow use of strings.ReplaceAll. I'm not sure if there are other more modern API usages. Is updating the Go version OK?
| Hi @ahmetb, this is important for us. Is there anything else we can do to get it merged? |
| I am confused about the contents in the change. It offers an asciidoc config option but there's no asciidoc related code. Is this simply "disable markdown rendering"? I am not willing to support AsciiDoc if it warrants a separate template. Many projects use md/html (see README) and this can become too much hassle to support properly. Feel free to fork this tool as you see fit. I maintain this at a personal capacity anyway. |
| @djencks is the source available for the version that you forked for the Camel-K docs? I'm interested in trying this tool out for our project. |
| @JakeSCahill Sure, the appropriate branch in my fork is https://github.com/djencks/gen-crd-api-reference-docs/tree/main-asciidoc. I haven't updated it lately, and it appears to be behind the original project. I haven't looked to see if I should merge in the updates. Discussing that on my fork would be more appropriate than here. |
4 participants
See #44
This does not currently include the two sets of AsciiDoc templates, as I'm not sure where they should go.
As noted in the issue, there is likely a better way to switch between text/Template and html/Template.
This is what I'm using for generating the Camel-K docs, and it's WIP, not a final proposal.