Use CMakePP Org Documentation CI and Docs Cleanup (#77)

* Update badges

* Add CMinx config file

* Add place for API docs in documentation source

* Switch to reusable CMakePP org deploy_docs workflow

* Enable api documentation generation

* Committing license headers

* Specify cmake source dir for api doc generation

* Switch to using existing API generation method

* Remove prefixes from parameter documentation

* Fix missed parameters and add parameters back that should not have been removed

---------

Co-authored-by: cmakepp[bot] <cmakepp[bot]@github.com>

.github/workflows/deploy_docs.yml

@@ -0,0 +1,33 @@
+# Copyright 2021 CMakePP
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+name: Build and Deploy Documentation
+
+on:
+  pull_request:
+    types:
+      - closed
+
+  # Allows manual triggering with the "Run workflow" button
+  workflow_dispatch:
+
+jobs:
+  Build-Documentation:
+    if: github.event.pull_request.merged == true
+    uses: CMakePP/.github/.github/workflows/deploy_docs_master.yaml@main
+    with:
+      docs_dir: 'docs'
+      python_version: '3.10'
+    secrets:
+      token: ${{ secrets.GITHUB_TOKEN }}

README.rst

@@ -16,27 +16,27 @@
 CMakeTest
 =========
 
+.. image:: https://github.com/CMakePP/CMakeTest/workflows/CMakeTest%20Unit%20Tests/badge.svg
+   :target: https://github.com/CMakePP/CMakeTest/workflows/CMakeTest%20Unit%20Tests/badge.svg
 
-.. image:: https://github.com/CMakePP/CMakeTest/workflows/CMakeTest%20CI/badge.svg
-   :target: https://github.com/CMakePP/CMakeTest/workflows/CMakeTest%20CI/badge.svg
-   :alt: 
+.. image:: https://github.com/CMakePP/CMakeTest/workflows/deploy_docs.yml/badge.svg?branch=master
+   :target: https://github.com/CMakePP/CMakeTest/workflows/deploy_docs.yml/badge.svg?branch=master
 
-
-CMake ships with ``ctest`` which helps integrate your project's tests into your
-project's build system. ``ctest``\ , is a powerful solution for managing your
+CMake ships with CTest_ which helps integrate your project's tests into your
+project's build system. CTest is a powerful solution for managing your
 project's tests, but it is designed to be decoupled from the framework used to
-actually test the code. Thus for CMake development purposes we still need a
+actually test the code. Thus, for CMake development purposes we still need a
 testing framework to ensure our CMake modules behave correctly. That is where
 CMakeTest comes in.
 
 CMakeTest is modeled after the Catch2 testing framework for C++. CMakeTest is a
 CMake module, written 100% in CMake. Unit testing with CMakeTest relies on the
-use of ``ct_add_test`` and ``ct_add_section`` special declarations, followed by ``function``
-blocks. Within these blocks users write their unit tests in native CMake;
-no need for ugly escapes or workarounds. The user then relies on assertions
-provided by CMakeTest to ensure that the program has the expected state. For
-example we can ensure that a CMake code sets a particular variable using
-``ct_assert_equal``. This looks like:
+use of ``ct_add_test`` and ``ct_add_section`` special declarations, followed by
+``function`` blocks. Within these blocks users write their unit tests in native
+CMake; no need for ugly escapes or workarounds. The user then relies on
+assertions provided by CMakeTest to ensure that the program has the expected
+state. For example we can ensure that a CMake code sets a particular variable
+using ``ct_assert_equal``. This looks like:
 
 .. code-block:: .cmake
 
@@ -49,6 +49,7 @@ example we can ensure that a CMake code sets a particular variable using
 
 Installation
 ------------
+
 CMakeTest can be installed via :code:`FetchContent` or by manually placing the
 :code:`cmake_test` directory on your :code:`CMAKE_MODULES_PATH`.
 
@@ -95,4 +96,9 @@ The following CMake code allows one to install CMakeTest via FetchContent:
 
 Documentation and Tutorials
 ---------------------------
+
 Documentation can be found `here <https://cmakepp.github.io/CMakeTest/>`_
+
+.. References
+
+.. _CTest: https://cmake.org/cmake/help/latest/manual/ctest.1.html

cmake_test/add_dir.cmake

@@ -20,8 +20,8 @@ include_guard()
 # with CTest. The configured templates will be executed seperately via CTest during the Test phase, and each *.cmake
 # file found in the specified directory is assumed to contain CMakeTest tests.
 #
-# :param _ad_dir: The directory to search for *.cmake files. Subdirectories will be recursively searched.
-# :type _ad_dir: path
+# :param dir: The directory to search for *.cmake files. Subdirectories will be recursively searched.
+# :type dir: path
 #
 # **Keyword Arguments**
 #

cmake_test/asserts/defined.cmake

@@ -20,8 +20,8 @@ include_guard()
 # assert that the variable is set to any particular value. If the variable is
 # not defined it will raise an error.
 #
-# :param _ad_var: The identifier to check for defined-ness.
-# :type _ad_var: Identifier
+# :param var: The identifier to check for defined-ness.
+# :type var: Identifier
 #]]
 function(ct_assert_defined _ad_var)
     if(NOT DEFINED ${_ad_var})
@@ -34,8 +34,8 @@ endfunction()
 # This function can be used to assert that a variable is not defined. If the
 # variable is actually defined this function will raise an error.
 #
-# :param _and_var: The identifier to check for defined-ness.
-# :type _and_var: Identifier
+# :param var: The identifier to check for defined-ness.
+# :type var: Identifier
 #]]
 function(ct_assert_not_defined _and_var)
     if(DEFINED ${_and_var})

cmake_test/asserts/equal.cmake

@@ -20,10 +20,10 @@ include_guard()
 #  specific contents. If the identifier is not set to the specified contents a
 #  fatal error will be raised.
 #
-#  :param _ae_var: The identifier whose contents are in question.
-#  :type _ae_var: Identifier
-#  :param _ae_contents: What the identifier should be set to.
-#  :type _ae_contents: String
+#  :param var: The identifier whose contents are in question.
+#  :type var: Identifier
+#  :param contents: What the identifier should be set to.
+#  :type contents: String
 #]]
 function(ct_assert_equal _ae_var _ae_contents)
     if(NOT "${${_ae_var}}" STREQUAL "${_ae_contents}")
@@ -41,10 +41,10 @@ endfunction()
 # other than the specified contents. If the identifier is set to the specified
 # contents a fatal error will be raised.
 #
-# :param _ane_var: The identifier whose contents are in question.
-# :type _ane_var: Identifier
-# :param _ane_contents: What the identifier should not be set to.
-# :type _ane_contents: String
+# :param var: The identifier whose contents are in question.
+# :type var: Identifier
+# :param contents: What the identifier should not be set to.
+# :type contents: String
 #]]
 function(ct_assert_not_equal _ane_var _ane_contents)
     if("${${_ane_var}}" STREQUAL "${_ane_contents}")

cmake_test/asserts/file_contains.cmake

@@ -20,10 +20,10 @@ include(cmake_test/asserts/file_exists)
 # Asserts that the file at the specified path contains the specified text.
 # Will return if the file does not exist, the assertion failure will be logged as a fatal error.
 #
-# :param _afc_file: The file to check
-# :type _afc_file: path
-# :param _afc_text: The text to check for
-# :type _afc_text: string
+# :param file: The file to check
+# :type file: path
+# :param text: The text to check for
+# :type text: string
 #]]
 function(ct_assert_file_contains _afc_file _afc_text)
     # Ensure the file exists
@@ -48,10 +48,10 @@ endfunction()
 #
 # Will return if the file does not exist, the assertion failure will be logged as a fatal error.
 #
-# :param _afdnc_file: The file to check
-# :type _afdnc_file: path
-# :param _afdnc_text: The text to check for
-# :type _afdnc_text: string
+# :param file: The file to check
+# :type file: path
+# :param text: The text to check for
+# :type text: string
 #]]
 function(ct_assert_file_does_not_contain _afdnc_file _afdnc_text)
     # Ensure the file exists
@@ -77,13 +77,13 @@ endfunction()
 #
 # Will return if the file does not exist, the assertion failure will be logged as a fatal error.
 #
-# :param _fc_result: Name to use for the variable which will hold the result.
-# :type _fc_result: bool
-# :param _fc_file: The file to check.
-# :type _fc_file: string
-# :param _fc_text: The text to check for.
-# :type _fc_text: string
-# :returns: ``_fc_result`` will be set to ``TRUE`` if file contains the text
+# :param result: Name to use for the variable which will hold the result.
+# :type result: bool
+# :param file: The file to check.
+# :type file: string
+# :param text: The text to check for.
+# :type text: string
+# :returns: ``result`` will be set to ``TRUE`` if file contains the text
 #           and ``FALSE`` if it does not.
 # :rtype: bool
 #]]

cmake_test/asserts/file_exists.cmake

@@ -16,8 +16,8 @@ include_guard()
 
 #[[[ Assert that the file at the provided path exists.
 #
-# :param _afe_path: The path to check
-# :type _afe_path: Path
+# :param path: The path to check
+# :type path: Path
 #]]
 function(ct_assert_file_exists _afe_path)
     if(NOT EXISTS "${_afe_path}")
@@ -29,8 +29,8 @@ endfunction()
 
 #[[[ Assert that a file does not exist at the provided path.
 #
-# :param _afdne_path: The path to check
-# :type _afdne_path: Path
+# :param path: The path to check
+# :type path: Path
 #]]
 function(ct_assert_file_does_not_exist _afdne_path)
     if(EXISTS "${_afdne_path}" AND NOT IS_DIRECTORY "${_afdne_path}")

cmake_test/asserts/library_exists.cmake

@@ -18,8 +18,8 @@ include_guard()
 #
 # Asserts that the target exists and is a library.
 #
-# :param _ale_name: The name of the library
-# :type _afe_path: string
+# :param name: The name of the library
+# :type path: string
 #]]
 function(ct_assert_library_target_exists _ale_name)
     # Check that the target exists and it is a library
@@ -35,8 +35,8 @@ endfunction()
 #
 # Asserts that the target does not exist or is not a library.
 #
-# :param _aldne_name: The name of the library
-# :type _aldne_name: string
+# :param name: The name of the library
+# :type name: string
 #]]
 function(ct_assert_library_does_not_exist _aldne_name)
     # Check that the target does not exist or is not a library
@@ -52,11 +52,11 @@ endfunction()
 # target is of type ``STATIC_LIBRARY``, ``MODULE_LIBRARY``, or
 # ``SHARED_LIBRARY`` and then returns an integer indicating what it found.
 #
-# :param _lte_result: Name to use for the variable which will hold the result.
-# :type _lte_result: int
-# :param _lte_name: The target name to check.
-# :type _lte_name: string
-# :returns: ``_lte_result`` will be set to ``0`` if the target is a library,
+# :param result: Name to use for the variable which will hold the result.
+# :type result: int
+# :param name: The target name to check.
+# :type name: string
+# :returns: ``result`` will be set to ``0`` if the target is a library,
             ``1`` if the target is not a library, and ``2`` if target does not
             exist.
 # :rtype: int

cmake_test/asserts/list.cmake

@@ -22,8 +22,8 @@ include_guard()
 # function will not consider such strings lists. If the identifier is not a list
 # an error will be raised.
 #
-# :param _anl_var: The identifier we want to know the list-ness of.
-# :type _anl_var: Identifier
+# :param var: The identifier we want to know the list-ness of.
+# :type var: Identifier
 #]]
 function(ct_assert_list _al_var)
     list(LENGTH ${_al_var} _al_length)
@@ -40,8 +40,8 @@ endfunction()
 # function will not consider such strings lists. If the provided string is a
 # list this function will raise an error.
 #
-# :param _anl_var: The identifier we want to know the list-ness of.
-# :type _anl_var: Identifier
+# :param var: The identifier we want to know the list-ness of.
+# :type var: Identifier
 #]]
 function(ct_assert_not_list _anl_var)
     list(LENGTH ${_anl_var} _anl_length)

cmake_test/asserts/prints.cmake

@@ -24,8 +24,8 @@ include_guard()
 # If the previously printed message does not exactly match the expected message,
 # this function will treat the expected message as a regex to check if it matches.
 #
-# :param _ap_msg: The message expected to have been printed, either exact match or regex.
-# :type _ap_msg: String
+# :param msg: The message expected to have been printed, either exact match or regex.
+# :type msg: String
 #]]
 function(ct_assert_prints _ap_msg)
     cpp_get_global(_ap_last_msg CT_LAST_MESSAGE)

cmake_test/asserts/string.cmake

@@ -21,8 +21,8 @@ include_guard()
 # raise an error if the provided identifier is not a string. Consequentially,
 # this function is more-or-less equivalent to ct_assert_not_list.
 #
-# :param _as_var: The identifier we want the stringy-ness of.
-# :type _as_var: Identifier
+# :param var: The identifier we want the stringy-ness of.
+# :type var: Identifier
 #]]
 function(ct_assert_string _as_var)
     list(LENGTH ${_as_var} _as_length)
@@ -38,8 +38,8 @@ endfunction()
 # raise an error if the provided identifier is a string. Consequentially, this
 # function is more-or-less equivalent to ct_assert_list.
 #
-# :param _ans_var: The identifier we want the stringy-ness of.
-# :type _ans_var: Identifier
+# :param var: The identifier we want the stringy-ness of.
+# :type var: Identifier
 #]]
 function(ct_assert_not_string _ans_var)
     list(LENGTH ${_ans_var} _ans_length)

cmake_test/asserts/target_exists.cmake

@@ -16,8 +16,8 @@ include_guard()
 
 #[[[ Assert that a target exists.
 #
-# :param _ate_name: The name of the target
-# :type _ate_name: String
+# :param name: The name of the target
+# :type name: String
 #]]
 function(ct_assert_target_exists _ate_name)
     # Check if the target exists, if not throw an error
@@ -28,8 +28,8 @@ endfunction()
 
 #[[[ Assert that a target does not exist.
 #
-# :param _ate_name: The name of the target
-# :type _ate_name: String
+# :param name: The name of the target
+# :type name: String
 #]]
 function(ct_assert_target_does_not_exist _atdne_name)
     # Check if the target exists, if it does, throw an error