search

princjef / gomarkdoc

Generate markdown documentation for Go (golang) code
MIT License
380 stars 60 forks source link

[Question/Guidance] Support for asciidoctor #23

Closed mariotoffia closed 3 years ago

mariotoffia commented 4 years ago

Hi, I use your tool to generate markdown and another tool to convert markdown to asciidoctor. I'm in a multi lang environment where we use asciidoctor for all documentation including code.

Can you give me a little aid to get me started to create that? Or isn't that possible within the current architecture?

Cheers, Mario :)

princjef commented 4 years ago

Hi Mario, glad you're finding it useful :)

Is the question about how support can be added directly within this tool for producing asciidoctor documentation as an output? If so, it's definitely a possibility. The output format is managed by two things:

  1. The Format that you use. This is where the details of the markup language used are really expressed. I'm not familiar with asciidoctor's syntax, but I'm guessing it's probably different enough from the three markdown formats implemented (see the structs documented here) to warrant a separate format implementation. This is selected via the --format option, but is not customizable outside of choosing which implementation you want to use.

  2. The templates that structure those components into the overall documentation. The templates are user-configurable, but the default implementations can be found here. They're designed to be generic enough that they should work for most markup formats with an appropriate formatter implementation, but I'm open to the idea of different templates being used depending on format type if needs dictate.

If your goal is direct support for asciidoctor, the best bet is probably to add a new formatter to the package. I will happily accept Pull Requests for adding asciidoctor support if you're interested in trying to add it.

mariotoffia commented 4 years ago

@princjef Thanks a lot for your good explanations & the nice library! :) I'm currently trying to create a formatter. ASCIIDOC is quite much more complex but I strive to keep it simple stupid. However, I probably need to not escape lots of texts since I need to be able to create tables, sequence diagrams, flowcharts etc. via asciidoctor and mermaid et.al. We're using kroki to generate such diagrams (we're using a local docker - but it is quite possible to use the online version - takes a few more seconds to do so :)).

I've forked and committing into my fork. When I've got something that may work - I'll ping you and if you have the time to have a look before creating the PR to polish it up :)

Cheers, Mario :)

mariotoffia commented 3 years ago

Hi @princjef - thanks for all the support you've given me. I've done a shot at a formatter but I realized that markdown and asciidoc is too different beasts and hence I've started a separate project that generates asciidoc from go code.

Again, thanks for you support!

Cheers, Mario