Add documentation for configuration

Signed-off-by: Arthur Zamarin <arthurzam@gentoo.org>

Author: arthurzam

doc/conf.py

@@ -63,7 +63,7 @@
 # General information about the project.
 project = pkgdist.MODULE_NAME
 authors = ''
-copyright = '2021, pkgdev contributors'
+copyright = '2021-2022, pkgdev contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

doc/man/config.rst

@@ -0,0 +1,50 @@
+Config file support
+===================
+
+Config files are supported by most subcommands of ``pkgdev`` from any of three
+locations. Listed in order of increasing precedence these include the
+following:
+
+- system config -- /etc/pkgdev/pkgdev.conf
+- user config -- ~/.config/pkgdev/pkgdev.conf
+- custom config -- specified via the --config option
+
+Any settings from a config file with higher precedence will override matching
+settings from a config file with a lower precedence, e.g. user settings
+override system settings. Note that command line options override any matching
+config file setting.
+
+In terms of file structure, basic INI formatting is required and allows
+creating a default section (DEFAULT) for system-wide settings or repo-specific
+sections. The INI key-value pairs directly relate to the available
+long-options supported by the various prefixed by the subcommand name and their
+related values. To find all possible configuration options, run:
+``pkgdev {subcommand} --help``. See the following examples for config settings:
+
+- Run ``pkgcheck scan`` before committing and asks for confirmation (instead of
+  aborting) when creating commits with QA errors::
+
+    [DEFAULT]
+    commit.scan = true
+    commit.ask = true
+
+- Allow pushing commits with QA errors, but only for the 'gentoo' repository::
+
+    [gentoo]
+    push.ask = true
+
+- When committing, stage all files in current working directory (note that this
+  option doesn't expect value, therefore no value is defined post equal sign)::
+
+    [DEFAULT]
+    commit.all =
+
+- All previous config settings combined::
+
+    [DEFAULT]
+    commit.scan = true
+    commit.ask = true
+    commit.all =
+
+    [gentoo]
+    push.ask =

doc/man/pkgdev.rst

@@ -7,6 +7,8 @@ pkgdev
 .. include:: pkgdev/_options.rst
 .. include:: pkgdev/_subcommands.rst
 
+.. include:: config.rst
+
 Reporting Bugs
 ==============
 

src/pkgdev/scripts/pkgdev_commit.py

@@ -103,7 +103,7 @@ def __call__(self, parser, namespace, value, option_string=None):
         out if any failures are found.
     """)
 commit_opts.add_argument(
-    '-A', '--ask', action='store_true',
+    '-A', '--ask', nargs='?', const=True, action=arghparse.StoreBool,
     help='confirm creating commit with QA errors',
     docs="""
         When running with the -s/--scan option enabled, ``pkgdev commit`` will

src/pkgdev/scripts/pkgdev_push.py

@@ -2,6 +2,7 @@
 import shlex
 
 from pkgcheck import reporters, scan
+from snakeoil.cli import arghparse
 from snakeoil.cli.input import userquery
 
 from .. import cli, git
@@ -26,7 +27,7 @@ def parse_known_args(self, args=None, namespace=None):
 push.add_argument('--pkgcheck-scan', help=argparse.SUPPRESS)
 push_opts = push.add_argument_group('push options')
 push_opts.add_argument(
-    '-A', '--ask', action='store_true',
+    '-A', '--ask', nargs='?', const=True, action=arghparse.StoreBool,
     help='confirm pushing commits with QA errors')
 push_opts.add_argument(
     '-n', '--dry-run', action='store_true',