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