search

CMakePP / CMinx

Generates API documentation for CMake functions and macros
https://cmakepp.github.io/CMinx/
Apache License 2.0
14 stars 5 forks source link

Define CMake target instead of running CMinx during configuration stage #108

Open peanutfun opened 2 years ago

peanutfun commented 2 years ago

Is your feature request related to a problem? Please describe. CMinx currently offers two types of installation: One via pip, which effectively only installs the cminx script, and one via CMake, which also installs the CMake modules. If CMinx is used in a downstream project, one can use the cminx_gen_rst function from the installed CMake module to generate the CMake documentation for said project. However, this function works at "configure time", i.e., when CMake is executed. I think this works agains the notion of a "build". Building a documentation is a typical task once configuration of a project is complete. In particular, it's only done on request by the user, to keep configuration as quick as possible.

Describe the solution you'd like I propose that the function cminx_gen_rst does not run the cminx command immediately but uses add_custom_command or add_custom_target to define a CMake target that then runs cminx. After configuring the project, users can then decide to build the "CMinx target", and are able to use this target as dependency for their typical doc targets.

Describe alternatives you've considered None.

Additional context None.

ryanmrichard commented 2 years ago

I think you can make an argument either way (for the configure or the build phase). We've been treating running CMinx as akin to generating files (which in my experience is usually done during the configure phase), and then the "build" was actually creating the static website (usually by running Sphinx, but we have users that do other things). The CMinx CMake module used to have functionality for making a docs target that ran Sphinx on the generated files, but it was sort of a pain to maintain because you then had to make CMake aware of any other documentation you had (and its dependencies) so that coherent documentation was generated. In the end, this meant we had a function which needed a lot of configuration logic to more or less make a target to call make html and we opted to drop the function.

Getting back to the issue, I think we can add an option to the cminx_gen_rst which controls whether the files are generated in the configure or the build phase.

ryanmrichard commented 2 years ago

Looking at this a bit more I'd have to break the cminx_gen_rst API to add an option for toggling a target. So I don't want to go that route. I think a better option is to write a new function which relies on a target. Users can then use the function they prefer.

That said, the CMakePP team's cycles are spread a bit thin at the moment, so I don't want to prioritize this issue unless it's affecting users. So, @peanutfun is this issue purely academic, or is this something that is (or will be) affecting your project(s)?

peanutfun commented 2 years ago

No, this does not affect my projects, it's mainly a suggestion. Feel free to give this issue a low priority.