add public function to generate docs and remove old files

[glours]

Since we're using the alpha command in Compose, we need to remove sub commands which may either be remove or promote as official commands.

See docker/compose#11155 as example

[codecov-commenter]

Codecov Report

❌ Patch coverage is 0% with 26 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
clidocstool.go	0.00%	26 Missing ⚠️

📢 Thoughts on this report? Let us know!

[glours]

@crazy-max@thaJeztah sorry to ping you but I can't add reviewers in this repo

[thaJeztah]

👋 sorry, saw the PR yesterday, but didn't have time to comment.

I'm ever-so-slightly wondering what the best approach is for these cases, although not "strongly" attached (this repository is a tool/utility and not a polished end-product, so "whatever works, even if quirky, or opinionated" is probably "fine").

Effectively, it's similar to, e.g., go mod vendor, which can result in updated files, new files, but also files being removed; we do that in a container in various repositories, and it works®.

I guess the difference would be that go mod vendor only acts on files and directories that it owns (i.e., nobody should make manual changes to the vendor/ directory). For docs, it's possible for both generated and manually maintained files to be in in the same directory; so I'm wondering if that's the issue you ran into (if not, then perhaps the same approach as our vendor steps would work, which effectively does an rsync between a "fresh vendor' and "actual vendor").

My concern is somewhat (but again: it's a quirky tool, so "whatever works") that we wouldn't be able to tell if the generator "OWNS" a file just by looking at its name; I could have a manually maintained docker_foo.md, and the tool wouldn't know "was that created by an older version of me?" or "was this a file someone else created?"

[thaJeztah]

@crazy-max any good suggestions?

(I'm not blocking this PR though if this is the best solution)

[crazy-max]

Would have been better with a variadic opt on GenAllTree instead of new public func but sounds good for now. Otherwise yeah if source and dest collide it's a bit tricky to figure out what should be removed.

[glours]

@crazy-max I created a new public function to avoid mis-usage of the original GenAllTree 😅
I'm fine to pass an Option structure to GenAllTree for activating the delete process