diff --git a/docs/source/config.rst b/docs/source/config.rst
new file mode 100644
index 00000000..4910c9e7
--- /dev/null
+++ b/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 `__ files. Under the hood,
+CMinx relies on the
+`Confuse `__ 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 `__ 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
+
+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', ])
+
+(in both code examples ```` 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 `__
+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-
diff --git a/docs/source/developer/dependencies.rst b/docs/source/developer/dependencies.rst
index 5c8eddfb..b25618fc 100644
--- a/docs/source/developer/dependencies.rst
+++ b/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 `_ for more details.
+search system configuration paths such as ``/etc/cminx/`` and
+``~/.config/cminx/`` for `config.yaml` files.
+See `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
diff --git a/docs/source/index.rst b/docs/source/index.rst
index a30b1150..70ace3ba 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -36,6 +36,7 @@ Table Of Contents
installation
quickstart
+ config
documenting/index
full_example
usage
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index 6e784612..5d5da88e 100644
--- a/docs/source/usage.rst
+++ b/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
\ No newline at end of file
+ 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