.. 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 Dependencies
##################

This page describes the packages that CMinx depends on, the supported versions,
and also why we depend on these packages.

*****
CMake
*****

The dependency on CMake has been thrust upon us by the problem scope. Namely, in
order to extract documentation from CMake scripts, and to integrate well with
existing CMake workflows, CMinx needs to know about CMake.

The minimum version of CMake required by CMinx is 3.14 on account of needing the
``FetchContent_MakeAvailable`` command.

******
Python
******

CMinx is a tool meant to be run on existing CMake infrastructure in order to
generate human-readable documentation. Conceptually this is a parsing
exercise. Python is an ideal language for writing CMinx on account of its
developer-friendly nature, and the large number of already-existing open-source
packages. In particular, Python packages already exist for a number of parsing
and documentation related scenarios. Using these packages will increase the
robustness of CMinx, while also cutting down on development time.

Arguably, the main drawback of Python programs are that they tend to be slower
than their compiled language analogs. However, we do not envision CMinx being
used in performance critical situations. Moreover, we anticipate that I/O will
dominate CMinx's operation. Point being, we anticipate Python to be fast enough
for our purposes.

As of 2020, Python 2 is no longer supported, and we have opted to write CMinx in
Python 3 for future compatibility purposes. CMinx uses a ``main`` signature
(in ``cminx/__init__.py``) which is incompatible with Python versions less than
3.9.

******
Antlr4
******

Antlr is arguably the de facto tool for generating language parsers. CMinx is
ultimately a CMake parser (with the ability to recognize some CMake extensions).
We use Antlr to generate the core of CMinx.

The files generated by Antlr live in ``cminx/parser``. These files were
generated by Antlr version 4.7.2 and are version-locked to 4.7.2. In turn, CMinx
requires Antlr version 4.7.2 exactly. In the future this restriction could be
lifted by having the parser be generated as part of the build process.

*******
Confuse
*******

Confuse is a Python library for managing YAML configuration files. CMinx uses
it to load default configuration values from ``cminx/config_default.yml`` and
search system configuration paths such as ``/etc/cminx/`` and
``~/.config/cminx/`` for `config.yaml` files.
See `Search Paths <https://confuse.readthedocs.io/en/latest/usage.html#search-paths>`_
for more details.


Confuse also supports checking the configuration files for malformed or incorrect entries using templating. Templating is accomplished in the ``cminx.config`` module.

As of writing, cminx uses the latest version of Confuse, version 1.7.0. Later
versions with the same major version should continue to work.

********
PathSpec
********

PathSpec is a Python library for matching file paths against ``.gitignore``-style filters.
CMinx uses PathSpec to determine whether files in the input path (or in subdirectories thereof)
are supposed to be excluded. CMinx's usage of PathSpec is confined to ``cminx/__init__.py``, in
``cminx.document()``.

As of writing, CMinx uses the latest version of PathSpec, version 0.9.0.


##########################
CMinx Testing Dependencies
##########################

To facilitate testing of CMinx we use a couple of additional packages beyond
those needed to simply build CMinx; they are described in this section.

********
coverage
********

Coverage.py is used to measure the code coverage of our Python test suite.

********
docutils
********

docutils is used to help test the generated restructured text files.

After some manual testing it appears that any version of ``docutils`` newer than
0.10 will work. Older versions of ``docutils`` do not appear to be compatible
with Python 3. The version of ``docutils`` used by CMinx is really only relevant
for CI, and if developers want to locally test CMinx. As such our CI coverage
does not exhaustively consider multiple versions of ``docutils``.

******
pytest
******

Used to run the Python test suite.

**********
pytest-cov
**********

A plugin for `pytest` which aids in generating coverage reports for the Python
test suite.

################################
CMinx Documentation Dependencies
################################

Building CMinx's documentation requires additional packages beyond those needed
to build CMinx itself; they are described in this section.

******
sphinx
******

Sphinx is a widely used tool for generating static websites.

Under normal circumstances we expect the version of ``sphinx`` used by CMinx to
only be relevant  to CI and have opted to let pip install what
ever version it wants. Should the automatically installed version ever end up
not being compatible with our documentation, then we will pin the version.

****************
sphinx_rtd_theme
****************

The Read-the-Docs Sphinx theme is one of the most full-featured Sphinx themes
around. Of the themes perused, no other theme generated documentation for CMinx
which looked as nice. It is probably possible to extend other themes to achieve
similar effects, but for simplicity we opted to use the already available
Read-the-Docs theme.

Like the ``sphinx`` dependency, under normal circumstances we expect the version
of the ``sphinx_rtd_theme`` used by CMinx to only be relevant to CI and have
opted to provide no guidance to pip.
