CMake Module for Generating PluginPlay Module Docs

[ryanmrichard]

This PR starts some CMake infrastructure for making it easy to generate module documentation as part of CI. I'm probably not going to have time to return to this for a bit, but @zachcran if you have some spare cycles this should be pretty easy for you as it's just an extension of the documentation infrastructure you put in place previously.

The planned API will look something like:

include(make_module_docs)
plugin_play_generate_module_docs_from_name(
        ${CMAKE_PROJECT_NAME}
        "${CMAKE_CURRENT_LIST_DIR}/docs/source/module_apis"
    )

I'm not thrilled with putting generated files in the version-controlled documentation source (see the second TODO). Long term, when PluginPlay is installable, I'd like find_package(pluginplay) to make the plugin_play_generate_module_docs* functions available rather than the user having to include(make_module_docs).

TODO

• Fix directory setup. I biffed something, but when I run the resulting executable with remove_all/create_directory lines uncommented I erased the executable...
• Is there a way to actually run Sphinx on the resulting files even though they're not the top-level documentation? I'm hoping this can be done similar to how we do Doxygen (basically in docs/source/index.rst we include a hyperlink to where we will put the resulting HTML).
• Finish documenting the CMake module with CMinx style comments
• Better generated index.rst #205

[zachcran]

I'll take a crack at getting this up and running.

For Task 2, my initial thought is that it is possible to point Sphinx at the generated files, especially since the generated documentation is already in rst format. You should just be able to add it to a TOC in an index file somewhere. Sphinx will generate HTML to display the documentation if it exists or a blank page (or 404 error, probably) if the files don't. However, we'll need to make sure that these documentation files is generated before Sphinx is run.

[ryanmrichard]

For Task 2, my initial thought is that it is possible to point Sphinx at the generated files, especially since the generated documentation is already in rst format. You should just be able to add it to a TOC in an index file somewhere. Sphinx will generate HTML to display the documentation if it exists or a blank page (or 404 error, probably) if the files don't. However, we'll need to make sure that these documentation files is generated before Sphinx is run.

If I'm understanding you correctly you're thinking:

• Add CMake function plugin_play_generate_module_docs_from_name to CMakeLists.txt
• Set output of said function to docs/source/module_api (or some other subdirectory of the documentation source)
• Configure and build project
• run resulting executable (which generates module docs)
• run sphinx on documentation source (which now includes module docs)
• publish resulting HTML to GitHub Pages

While that should work, putting generated files in the documentation source is frowned upon (you're supposed to keep the source pristine). That said, I just looked at how we build the Doxygen docs and it looks like we do a similar thing (I thought we did everything in the build dir for that, but it looks like we actually move the resulting HTML to the documentation source directory so Sphinx can link it in). I guess it's fine for now.

[zachcran]

In that case, I think we can generate the RST files somewhere else, run Sphinx on it separately, and put the built HTML in the build directory of the main documentation. It is a minor deviation from what we do now, but it shouldn't be too bad. It may require a bit more thought after the holidays, but I think we could just give Sphinx the build and source directories as command line arguments to set this up. I'm not sure how the Doxygen is set up, but maybe I can fix that quickly as well.

[zachcran]

• Fix directory setup. I biffed something, but when I run the resulting executable with remove_all/create_directory lines uncommented I erased the executable...

@ryanmrichard When I uncommented the remove_all/create_directory lines and tried using the generated_module_docs executable that I generated in the SCF repo, the executable was not erased and the files appeared to be created properly. Which repo were you testing this in and what did your CMakeLists.txt looked like?

[ryanmrichard]

• Fix directory setup. I biffed something, but when I run the resulting executable with remove_all/create_directory lines uncommented I erased the executable...

@ryanmrichard When I uncommented the remove_all/create_directory lines and tried using the generated_module_docs executable that I generated in the SCF repo, the executable was not erased and the files appeared to be created properly. Which repo were you testing this in and what did your CMakeLists.txt looked like?

I was working on it in GhostFragment. If it works for SCF that's fine. I probably messed something up on my end then.

[zachcran]

I wanted to note that this is still in progress. It has been 95% of the way there for a long time now, but build issues keep preventing me from doing the final round of testing and doc formatting fixes needed. I think I have NWX building again, so I will try to have this done in the next couple weeks.

[zachcran]

Is this good to close? #253 completes most of this and the last task has its own issue to work from.