.. 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.
..
################
CMinx Background
################

This page is meant to provide historical background about documenting CMake
modules and the creation of the CMinx project.

*********************
The Official Solution
*********************

A user, ``tjwrona1992``, asked on
`StackOverflow <https://stackoverflow.com/q/54660549>`_ how to get their
custom CMake module's documentation to show up using the ``cmake --help-module``
command. According to their self
`answer <https://stackoverflow.com/a/54671996>`_, they received the following
email reply from Brad King (a CMake developer):

.. code-block:: none

   There is no way to do this. The only reason --help-module exists at all is
   because prior to 3.0 the documentation was generated by the CMake binary
   itself, and people were used to the option being available. It is only for
   builtin modules and only available for legacy reasons, and may one day go
   away in favor of the man pages and html docs.

   The online docs, like those at https://cmake.org/cmake/help/v3.14 do publish
   a /objects.inv to support intersphinx:

   http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

   This was done on request of some users so I haven't looked into how that
   works, but one should be able to use sphinx to generate one's own
   documentation and still cross-reference CMake's online docs.

   If you get that working we'd welcome a MR to add docs describing how,
   perhaps in

   https://gitlab.kitware.com/cmake/cmake/blob/master/Help/dev/documentation.rst

The question was asked (and answered) in 2019, suggesting that as of 2019 the
official way to write documentation for a CMake module was via Sphinx. It should
be noted that this solution requires you to write the entirety of the
documentation manually (*i.e.*, there is no tool which will extract the
signatures of the functions, the variable names, *etc.*).

***********************
Sphinx Domain Solutions
***********************

Sphinx domains are a way to package up language-specific directives, and roles.

Sphinx's (Unofficial) CMake Domain
==================================

`link <https://github.com/sphinx-contrib/cmakedomain>`__

Started (and finished) on 10/21/2013, this is the official (unofficial) CMake
domain for Sphinx. The actual domain is pretty bare bones providing:

- syntax highlighting for code blocks,
- a directive for documenting a macro, and
- a directive for documenting a variable

What makes this Sphinx's official (unofficial) CMake domain is that it is
available from the `sphinx_contrib <https://github.com/sphinx-contrib>`_
organization, which is an organization run by Sphinx for unofficial Sphinx
extensions.

As of 10/25/2021 the repo:

- has no release information,
- was last committed to on 10/21/2013,
- has 1 watcher (**not** the author),
- 0 stars, and
- 1 fork

In summary, it feels safe to say that this repo has been abandoned.

scikit-build Modern CMake Domain
================================

`link <https://github.com/scikit-build/moderncmakedomain>`__

Started on 10/14/2018 by GitHub user ``bruxisma``, and acquired by scikit-build
in August of 20201, this project hosts a mirror of the CMake domain Kitware
uses
`internally <https://github.com/Kitware/CMake/tree/master/Utilities/Sphinx>`__.

It contains support for documenting:

- variables,
- functions,
- environment variables, and
- ``autodoc`` style extractor

Of note they also maintain a pypi package which makes it easy to include in your
Sphinx setup.

As of 10/25/2021 the repo:

- is in v3.19,
- was last committed to on 8/15/2021,
- has 1 watcher (the author),
- 9 stars, and
- 3 forks



MarcoKoch CMake Domain
======================

`link <https://github.com/MarcoKoch/sphinx-cmake_domain>`__

Started on 7/7/2020, and developed seemingly independent of scikit-build's CMake
domain. Supports:

- variables,
- macros,
- functions,
- modules, and
- targets

As of 10/25/2021 the repo:

- is in a beta state,
- was last committed to on 9/6/2020,
- has 1 watcher (the author),
- 0 stars, and
- 0 forks

In summary this project also seems to be abandoned, but given that it's being
run by a solo developer, it's also possible that it's on the back-burner for
the moment.

*****
CMinx
*****

Started 8/26/2019. CMinx is envisioned as a Doxygen-like solution to
documenting CMake modules. This means that CMinx is run on your source directory
and in return generates the reST files for you.
