Implement readthedocs

[Snell1224]

This PR includes all LDMS-related documentation and Read the Docs (RTD) configuration files, such as .rst files, conf.py, Makefile, and others. It also adds a GitHub Actions workflow, "Build and Trigger Read the Docs", which automates the generation and updating of documentation whenever changes are made to specific files in the docs/ directory.

A couple things to note:

1. RTD Webhook Secret: Someone with admin access to the LDMS repository will need to add a RTD_WEBHOOK_SECRET in the repository's settings. This secret allows GitHub Actions to trigger a build on the Read the Docs site (e.g., LDMS Documentation).
   • NOTE: I’m happy to set this up if I can be temporarily granted admin privileges.
2. .man to .rst Conversion Fixes: Modifications were made to .man pages to resolve errors encountered during the man2rst conversion process.
3. Makefile Updates: The Makefile.am has been updated to generate .man pages from the .rst files (located under docs/man/) within the LDMS build directory.
4. Next Steps: If there are no issues, I’ll apply the same structure and formatting to PRs for the remaining OVIS subprojects.

GITHUB ACTIONS WORKFLOW:

1. Trigger Conditions

• Runs on push or pull_request events when changes occur in:
• The docs/ directory or rst files.

2. Job1: generate-rst

• Checkout the repository and set up Python 3.8.
• Install dependencies like pandoc for file conversion.
• Convert .man files to .rst format, if CONVERT_MAN_PAGES is set to true.
  - Note: This is a temporary step during the transition from .man to .rst documentation. If developers continue to add .man files, they can easily be converted by enabling CONVERT_MAN_PAGES.
• Update index.rst files dynamically to reflect added/removed or modified .rst files.
• Commit and push changes back to the repository if any documentation files were modified.

3. Job2: build-docs

• Depends on the completion of generate-rst.
• Prepares the repository for Read the Docs to build the updated documentation.

[morrone]

This looks like a good start!

If we are going to have all of the rst files checked into the tree, then I think we need to remove the man files. We don't want to have to deal with keeping two different formats of the same documentation updated. On or the other should be auto-generated. I'd vote for switching to rst.

I'm not at all a fan of sprinkling index.rst files throughout the tree. I don't think the documentation and man pages would necessarily need to mimic the code tree structure, especially for man pages. I think we should have co-located high level files that contain the document structure, and has pointers to the various documents it links to.

If we move to .rst files and delete the .man files, then we need to make rst2man a requirement in configure.ac. We probably need to iterate a bit on tree structure.

[Snell1224]

@morrone Thanks for reviewing this! I've updated the branch with the suggested changes but haven’t modified the tree structure under docs/man/ yet. It seems that most of us are on board with transitioning to .rst, and I agree that we should discuss the best way to organize these documents (maybe during the next LDMS UG meeting) before removing any existing .man files. @tom95858, do you have any other thoughts or suggestions?

[baallan]

I have no strong feelings about summary and umbrella documentation locations, but the .rst file(s) specific to a plugin should live in the directory with the plugin. This allows the contributor of a plugin to work in a clearly defined sandbox.

[morrone]

I have no strong feelings about summary and umbrella documentation locations, but the .rst file(s) specific to a plugin should live in the directory with the plugin. This allows the contributor of a plugin to work in a clearly defined sandbox.

I agree. I just want to get rid of the "index.rst" files that are strewn throughout, not the content rst files (which would be the man page source as well.

[baallan]

We might also take this opportunity to put some consistency in place wrt man page naming and to drop/change the 'plugin' prefix on our plugin man pages. As complex tooling manuals go, the pattern for git man page naming is one of the least unpleasant I've run into in quite a while.
Ideally 'man ldms' gets you an index page.

We could, if people riot, keep the old aliases for plugin man pages.

[morrone]

We might also take this opportunity to put some consistency in place wrt man page naming and to drop/change the 'plugin' prefix on our plugin man pages.

I completely agree! They should all have a better prefix like "ldmsd_", "ldmsd_plugin_", whatever. "Plugin_" is just too generic for installing globally on a system.

[baallan]

I would like all the following to return something sensible (note the lack of a pedantic plugin type namespacing):

man ldms   (index)
man ldms-plugins (plugin index: covers auth, zap, sampler, store, and stream plugin lists; possibly also list man pages for C multi-instance plugin apis)
man ldms-meminfo (the meminfo plugin man page)
man ldms-munge (the munge auth plugin man page)

and I would eventually like

man ldms-genders

to return:

 It's gone. Muahahahaha!