Stop storing generated docs in git

[andygrove]

What is the problem the feature request solves?

Rather than updating parts of configs.md in-place as part of the build, it would be better not to store the generated content in git and instead only generate the dynamic parts as part of the publishing process. We publish the documentation on all merges to main.

Describe the potential solution

We could rename configs.md to configs_template.md and update GenerateDocs to read from configs_template.md and write to configs.md. We could also add a .gitignore file for the generated configs.md to prevent it from being checked in.

One issue with this approach (and the reason we switched to the current approach) is that contributors would often make changes to the wrong file, only to lose their work after running make.

Another issue is that it complicates publishing the user guide for multiple Comet versions. We currently rely on the final content being checked in. If we move to this approach, we would need to rebuild content for older versions as well, which would require building from source for each version whenever we publish the documentation.

Additional context

No response

[andygrove]

Some notes on the current implementation.

We currently publish the documentation site on all merges to main. We use rsync with a --delete flag to remove all content before publishing the current content. This means that all content for older releases is removed and needs to be republished. The scripts do this by cloning recent release branches and copying the markdown files from those branches into the current working tree.

The scripts also dynamically update the markdown content for older releases to add warnings that this is out-of-date documentation, with links to the content for the latest official release.

HTML is generated from the markdown content and pushed to the asf-site branch, which then gets published by GitHub Pages.