Examples for generating docs in a bunch of languages

[alexeagle]

Markdown files often want to reference code. By running the language-specific docgen tools, the documentation depgraph can express that a markdown file "depends" on the output of some other actions, which could be individual code API docs, or a directory tree.

I think rules_lint has shown a good pattern for "run tools in all language ecosystems" without incurring much extra complexity in the repo.

[alexeagle]

Note, we'll have an uphill battle because mkdocs acts like a build system; plugins are typically spawning "actions" themselves, for example https://github.com/JakubAndrysek/mkdocs-typedoc/blob/8552f568152f48cd790b414d502ffa14193e4dd5/typedoc/plugin.py#L71-L93

So if we just let developers follow mkdoc documentation, they will loose Bazel advantages like incrementality and hermeticity.

[jacobshirley]

Thanks for the PRs for integrating with other languages. That’s a good point and it’s probably something I should add to the documentation, to use mkdocs plugins wisely as they are not always hermetic. I found this exact issue with their git history plugin, where it needed the .git tree but I didn’t seem to like a symlinked version. Hence the git_ rules here