cminx-auto-update-action

A GitHub Action to automatically update CMakePP repositories' gh-pages branch with autogenerated documentation.

Getting Started

First, your repository must have a top-level CMakeLists.txt. This file must use CMinx as the documentation generation tool, and it must call CMinx when the BUILD_DOCS variable is set to "ON". An example snippet is shown below:

option(BUILD_DOCS "Whether documentation targets should be added" OFF)
set(PROJECT_SRC_FILES "") #Set this variable to where your source files that you want documentation for are, relative to your project's top-level directory

if(BUILD_DOCS)
    include("${PROJECT_SOURCE_DIR}/cmake/get_cminx.cmake")
    include(cminx)



    cminx_gen_rst("${CMAKE_CURRENT_SOURCE_DIR}/${PROJECT_SRC_FILES}/" "${CMAKE_CURRENT_SOURCE_DIR}/docs/source/developer/")

    cminx_add_docs_target("${CMAKE_CURRENT_SOURCE_DIR}/docs" "${CMAKE_CURRENT_BINARY_DIR}/docs" html)
endif()

CMinx can either be included in your project's repository or pulled at build time, but the latter is the recommended strategy.

Next, add a workflow file to your repository and add this job:

autodoc:
    runs-on: ubuntu-18.04
    name: autodoc-gen
    steps:
      - uses: CMakePP/cminx-auto-update-action@v1
        with:
          push: false

Set the workflow to only run when pushes are made to main or master, instead of pushes to every branch. Push your new workflow and observe the Github Actions logs.

Make sure that the logs look correct and you have it configured correctly.

If everything looks right, go into the workflow file you created earlier and change push: false to push: true. That will tell the action it has permission to push its changes to the gh-pages branch.

Push a commit to the main branch and watch as your gh-pages is automatically updated.

Available Options

This action has multiple configuration options, listed below:

• repo: The repository this action should pull and generate documentation for. Default is ${{ github.repository }}. Intended for local testing purposes only.
• docs-branch: The branch generated documentation should be pushed to. Default is gh-pages.
• ssh-key: Key to use with git, if set this action will use SSH instead of HTTPS+token. Default is unset.
• github-token: Token to be used with HTTPS. Default is ${{ github.token }}.
• push: Boolean whether or not to push updated docs to docs-branch. Required for safety reasons, default is false. Anything other than YAML truthy values is considered false.