From 5b16129f198169ce30344746ea911ce1016e509e Mon Sep 17 00:00:00 2001
From: Arthur Zamarin <arthurzam@gentoo.org>
Date: Tue, 19 Apr 2022 20:40:59 +0300
Subject: Add documentation for configuration

Signed-off-by: Arthur Zamarin <arthurzam@gentoo.org>
---
 doc/conf.py        |  2 +-
 doc/man/config.rst | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/man/pkgdev.rst |  2 ++
 3 files changed, 53 insertions(+), 1 deletion(-)
 create mode 100644 doc/man/config.rst

(limited to 'doc')

diff --git a/doc/conf.py b/doc/conf.py
index bfcce72..65e2969 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -63,7 +63,7 @@ master_doc = 'index'
 # 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
diff --git a/doc/man/config.rst b/doc/man/config.rst
new file mode 100644
index 0000000..dbed14c
--- /dev/null
+++ b/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 =
diff --git a/doc/man/pkgdev.rst b/doc/man/pkgdev.rst
index 92b3749..29ca259 100644
--- a/doc/man/pkgdev.rst
+++ b/doc/man/pkgdev.rst
@@ -7,6 +7,8 @@ pkgdev
 .. include:: pkgdev/_options.rst
 .. include:: pkgdev/_subcommands.rst
 
+.. include:: config.rst
+
 Reporting Bugs
 ==============
 
-- 
cgit v1.2.3-65-gdbad