.. Copyright 2022 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.

#################
Configuring CMinx
#################

By default the reST files generated by CMinx are to the authors' liking. We
realize that preferences will vary from user to user and have thus attempted
to expose as many customization points as possible. :ref:`default_config` lists
all currently recognized CMinx options and their default values. Users
can provide configuration files which set values for one or more of these
options in order to override the default values.

************************
About Configuration File
************************

Configuration files are `YAML <https://yaml.org/>`__ files. Under the hood,
CMinx relies on the
`Confuse <https://confit.readthedocs.io/en/latest/#>`__ library for locating,
loading, and managing the configuration file. Users can directly provide
CMinx with the path to their configuration file or place their configuration
file in one of the paths searched by Confuse (*e.g.*, ``/etc/cminx/`` or
``~/.config/cminx/``). See
`here <https://confuse.readthedocs.io/en/latest/usage.html#search-paths>`__ for
more details regarding how Confuse locates configuration files.

For organizational and namespacing purposes we have partitioned the
options recognized by CMinx into four categories:

1. ``input``.   Affects which files and file parts CMinx will parse.
2. ``output``.  Affects how CMinx outputs results.
3. ``logging``. Options pertaining to CMinx's log messages. See
   :ref:`logging_options` for more details.
4. ``rst``.     Used to control the formatting of the generated reST.

****************************
Writing a Configuration File
****************************

One of the first things CMinx does when it is run is to load the default
values for all options. If a user provides a configuration file, the
configuration file will be used to override initially loaded default values.
Hence, user configuration files only need to include options with non-default
values (listing options with defaulted values will not hurt anything though).
For example, by default CMinx will generate API documentation for all functions,
regardless of whether they are documented or not (if they are not documented
the generated documentation is little more than the signature). Let's say we
do not want CMinx to generate documentation for undocumented functions. In this
case, we create a file ``config.yaml`` and put the following in it:

.. code-block:: yaml

   input:
     include_undocumented_function: false

Assuming ``config.yaml`` lives in the directory we are invoking CMinx from, we
then run:

.. code-block:: terminal

   cminx -s config.yaml <other options>

If the user is calling CMinx from Python then the configuration file is passed
directly to the ``main`` function like:

.. code-block:: Python

   import cminx
   cminx.main(['-s', 'config.yaml', <other options>])

(in both code examples ``<other options>`` should be replaced with any
additional command line options the user wants to pass to CMinx).


.. _logging_options:

*******************
Logging Options
*******************
In CMinx's configuration files, there is a `logging` section. This section is
special in that it forwards all options inside of it to the Python
``logging.config`` module. This means that users can configure the Python
logging system, and thus CMinx's logging settings, directly from a standard
config file.

See
`here <https://docs.python.org/3/library/logging.config.html#logging-config-dictschema>`__
for all valid logging configuration options. The YAML examples present within
will work as long as they are within the ``logging`` section of the config file.
See :ref:`default_config` for an example of a basic logging configuration.


.. _default_config:

**************************
Default Configuration File
**************************

The following lists all configuration options recognized by the current version
of CMinx and the default values for those options.

.. literalinclude:: ../../src/cminx/config_default.yaml
   :language: yaml
   :lines: 15-
