Add option to append to existing output files if non-API documentation content exists

[jdpedrie]

Hi, first of all I love this project. I'm super excited to find a godoc style generator that works for private projects.

I integrated the generator into my project for work, but found that outputting to README.md would clobber any existing README data, so the initial solution is to send output to a separate file: gomarkdoc --output '{{.Dir}}/DOCUMENTATION.md' ./....

This works fine, but visibility is lower. I'd love for this tool to detect an existing README.md file, and append documentation to the end, rather than overriding the existing content. Ideally it could detect the comment at the start of the generated documentation, split the file contents, and replace the existing documentation on regeneration.

[princjef]

Thanks for the suggestion @jdpedrie! I think this would be a great addition to the tool. Based on what I've seen in other tools I would think a comment marker like this would be reasonable:

<!-- gomarkdoc:embed -->

Then when the documentation gets inserted, that would get replaced with:

<!-- gomarkdoc:embed:start -->

The generated documentation...

<!-- gomarkdoc:embed:end -->

The tool would be designed to work with either the individual comment or the pair, replacing any text in between the start and end markers in variation 2.

Thoughts?

[jdpedrie]

Hey @princjef, thanks for the reply!

I think your suggestion makes sense in cases where a file which would be modified already exists. For instance, a package with a README.md file should probably specify the embed location. Perhaps that, combined with creating new files when an existing one does not exist, would be a good solution?

In my project (a fairly large monorepo), for instance, we have a number of packages which do not have READMEs.

[princjef]

This has been released in https://github.com/princjef/gomarkdoc/releases/tag/v0.3.1

Take it for a spin and let me know if you run into any issues or have any additional thoughts!