update docs for config file (#118)

* update docs for config file

* Committing license headers

* adds autonomicperfectionist suggestions

* more Branden edits.

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

docs/source/config.rst

@@ -0,0 +1,117 @@
+.. 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-

docs/source/developer/dependencies.rst

@@ -72,13 +72,16 @@ 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.
+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.
+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

docs/source/index.rst

@@ -36,6 +36,7 @@ Table Of Contents
 
    installation
    quickstart
+   config
    documenting/index
    full_example
    usage

docs/source/usage.rst

@@ -16,26 +16,48 @@
 Usage
 #####
 
-For each CMake function or variable that you would like to document, prepend it 
-with a block doc-comment. A block doc-comment begins with :code:`#[[[` and ends 
+For each CMake function or variable that you would like to document, prepend it
+with a block doc-comment. A block doc-comment begins with :code:`#[[[` and ends
 with :code:`#]]`.
 
-Then run :code:`cminx` on your CMake files, outputting to a directory of your 
+Then run :code:`cminx` on your CMake files, outputting to a directory of your
 choosing. The help text is printed below for reference::
 
-   Usage: cminx [-h] [-o OUTPUT] [-r] file [file ...]
+   usage: cminx [-h] [-o OUTPUT.DIRECTORY] [-r] [-p RST.PREFIX] [-s SETTINGS]
+                [-e INPUT.EXCLUDE_FILTERS] [--version]
+                files [files ...]
+
+   Automatic documentation generator for CMake files. This program generates
+   Sphinx-compatible RST documents, which are incompatible with standard
+   docutils. Config files are searched for according to operating-system-
+   dependent directories, such as $XDG_CONFIG_HOME/cminx on Linux. Additional
+   config files can be specified with the -s option.
 
    positional arguments:
-      file                 CMake file to generate documentation for. If 
-                           directory, will generate documentation for all 
-                           *.cmake files (case-insensitive)
+      files             CMake file to generate documentation for. If
+                        directory, will generate documentation for all *.cmake
+                        files (case-insensitive)
 
-   optional arguments:
-     -h, --help            show this help message and exit
-     -o OUTPUT, --output OUTPUT
-                           Directory to output generated RST to. If not 
-                           specified will print to standard output. Output files 
-                           will have the original filename with the cmake 
-                           extension replaced by .rst
-     -r, --recursive       If specified, will generate documentation for all
-                           subdirectories of specified directory recursively
+   options:
+      -h, --help            show this help message and exit
+      -o OUTPUT.DIRECTORY, --output OUTPUT.DIRECTORY
+                            Directory to output generated RST to. If not specified
+                            will print to standard output. Output files will have
+                            the original filename with the cmake extension
+                            replaced by .rst
+      -r, --recursive       If specified, will generate documentation for all
+                            subdirectories of specified directory recursively. If
+                            the prefix is not specified, it will be set to the
+                            last element of the input path.
+      -p RST.PREFIX, --prefix RST.PREFIX
+                            If specified, all output files will have headers
+                            generated as if the prefix was the top level package.
+      -s SETTINGS, --settings SETTINGS
+                           Load settings from the specified YAML file. Parameters
+                           specified by this file will override defaults, and
+                           command-line arguments will override both.
+      -e INPUT.EXCLUDE_FILTERS, --exclude INPUT.EXCLUDE_FILTERS
+                           Exclude some files from documentation. Supports shell-
+                           style glob syntax, relative paths are resolved with
+                           respect to the current working directory.
+      --version            show program's version number and exit