Generates documentation of all cmake build options for a cmake based project directly into the project's README

This action is for projects which provide a cmake build. Usually, the cmake build can be controlled by several options which are passed to the cmake command. The options are specified in the CMakeLists.txt file using cmake's option or cmake's set as for example:

option(MYLIB_BUILD_TESTS "Whether to build the tests for the project." OFF)
option(MYLIB_SOME_OTHER_OPT "This controls some other stuff." ON)

When these options are defined, the name, the default value and the description are already given. Documenting these options in the project's README would lead to duplication and superfluous work. This action will scan the CMakeLists.txt of the project using cmake -LH -N and generate a markdown table of all options containing the name, the default value and the description. Then the action puts this table directly to the project's README site in a specified section. For the examples above, the table will look like this:

Required The directory where the CMakeLists.txt is located from which the options are documented. Should be set after a call to actions/checkout.

Specify a filter for cmake options to process. For getting options like MYLIB_SOME_OPT, set filter to "MYLIB". If empty, no filter is applied. Default "".

Markdown specifier for the heading of the section which contains the documentation of cmake build options. Default "#".

Title of the section which contains the documentation of cmake build options. Default "Build Options". The action will replace the complete content in this section so that only the table of options should be present in this section.

Filename of the README file relative to source_dir. Default: "README.md"

Options which are passed to the cmake configure call. Format: OPT1=VAL1 OPT2=VAL2 ... Default: ""

Normally, the usage consists of three steps:

• You have to checkout the repository first by using for example actions/checkout.
• The you can generate the cmake options documentation with this action.
• Finally, you have to commit and push the changes. Here, you can use EndBug/add-and-commit.

uses: actions/checkout@v3

#Optionally install dependencies for the project so that cmake's configure step will run successfully.

uses: cpp977/GenCMakeDoc@v1
with:
    source_dir: $GITHUB_WORKSPACE
    option_filter: MYLIB
    
uses: EndBug/add-and-commit@v8
with:
    message: 'Updated documentation for cmake build parameters.'
    committer_name: GitHub Actions
    committer_email: [email protected]