Add config file docs for lemon24#177.

CHANGES.rst

@@ -18,6 +18,8 @@ Unreleased
   any local feed path
   (in 2.0, local file parsing will be disabled by default).
   (:issue:`155`)
+* Support loading CLI and web application settings from a
+  :doc:`configuration file <config>`. (:issue:`177`)
 * Fail fast for feeds that return HTTP 4xx or 5xx status codes,
   instead of (likely) failing later with an ambiguous XML parsing error.
   The cause of the raised :exc:`ParseError` is now an instance of

docs/app.rst

@@ -21,8 +21,9 @@ Serving the web application
 
 *reader* exposes a standard WSGI application as ``reader._app.wsgi:app``.
 See the `Flask documentation`_ for more details on how to deploy it.
-The path to the reader database can be configured through the ``READER_DB``
-environment variable.
+The path to the reader database can be configured through the
+:doc:`config file <config>`
+or the ``READER_DB`` environment variable.
 
 .. warning::
 
@@ -38,7 +39,7 @@ An example uWSGI configuration file (probably not idiomatic, from `here`_)::
     mount = /reader=reader._app.wsgi:app
     plugin = python3
     virtualenv = /apps/reader/
-    env = READER_DB=/data/www-data/reader.sqlite
+    env = READER_CONFIG=/apps/reader/reader.yaml
 
 
 You can also run the web application with the ``serve`` command.
@@ -50,7 +51,7 @@ If running on a personal computer, you can use cron to run ``serve`` at boot::
     @reboot     sleep 60; reader serve -p 8080 2>&1 ) >>"/tmp/$LOGNAME.reader.serve.boot.log"
 
 
-.. _here: https://github.com/lemon24/owncloud/blob/936b0aa6015eb8b4a42e37ff7dc8df2bae87263d/reader.yaml#L79
+.. _here: https://github.com/lemon24/owncloud/blob/b6a6ba28f84fa40a1a822c200c9e245bad84600b/reader.yaml#L77
 .. _Flask documentation: http://flask.pocoo.org/docs/1.0/deploying/
 .. _Werkzeug's development server: http://werkzeug.pocoo.org/docs/0.14/serving/#werkzeug.serving.run_simple
 

docs/config.rst

@@ -0,0 +1,37 @@
+
+Configuration
+=============
+
+Both the :doc:`CLI <cli>` and the :doc:`web application <app>` can
+be configured from a file.
+
+.. warning::
+
+    The configuration file format is not stable yet
+    and might change without any notice.
+
+.. note::
+
+    Configuration file loading dependencies get installed automatically when
+    installing the CLI or the web application
+    :ref:`extras <Optional dependencies>`.
+
+
+The configuration file path can be specified either through the ``--config``
+CLI option or through the ``READER_CONFIG`` environment variable
+(also usable with the web application).
+
+The config file is split in contexts;
+this allows having a set of global defaults
+and overriding them with CLI- or web-app-specific values.
+Use the ``config dump --merge`` command
+to see the final configuration for each context.
+
+The older ``READER_DB``, ``READER_PLUGIN``, and ``READER_APP_PLUGIN``
+environment variables always *replace* the corresponding config values,
+so they should be used only for debugging.
+
+The following example shows the config file structure
+and the options currently available:
+
+.. literalinclude:: ../examples/config.yaml

docs/index.rst

@@ -34,6 +34,7 @@ User’s guide
     fts
     cli
     app
+    config
     plugins
 
 

examples/config.yaml

@@ -1,32 +1,76 @@
-reader:
-    # make_reader() keyword arguments
+# Contexts are values of the top level map.
+# There are 3 known contexts: default, cli, and app.
+#
+# The default context can also be implicit: top level keys that don't
+# correspond to a known context are assumed to belong to the default context.
+#
+# Thus, the following are equivalent:
+#
+#   default:
+#       reader: ...
+#       something else: ...
+#
+#   ---
+#
+#   reader: ...
+#   something else: ...
+#
+# However, mixing them is an error:
+#
+#   default:
+#       reader: ...
+#   something else: ...
 
-    # url: db.sqlite
 
-    feed_root: /path/to/feeds
+# default context.
+#
+# Provides default settings for the other contexts.
+
+default:
+    # The reader section contains make_reader() keyword arguments:
+    reader:
+        url: /path/to/db.sqlite
+        feed_root: /path/to/feeds
+
+        # Additionally, it's possible to specify reader plugins, as a
+        #   <plugin import path>: <plugin options>
+        # map; options are ignored at the moment.
+        # Note that unlike other settings, plugins are merged, not replaced.
+        plugins:
+            reader._plugins.tumblr_gdpr:tumblr_gdpr:
+            reader._plugins.cloudflare_ua_fix:init:
 
-    # reader plugins
-    # <plugin import path>: <plugin options>
-    # options are ignored at the moment
-    plugins:
-        'reader._plugins.regex_mark_as_read:regex_mark_as_read':
-        'reader._plugins.feed_entry_dedupe:feed_entry_dedupe':
+
+# CLI context.
 
 cli:
+    # When using the CLI, we want to use some additional reader plugins.
+    reader:
+        plugins:
+            reader._plugins.regex_mark_as_read:regex_mark_as_read:
+            reader._plugins.feed_entry_dedupe:feed_entry_dedupe:
+
+    # The cli context also allows changing the CLI defaults.
     defaults:
-        # defaults for various CLI options, used as context default_map
-        # https://click.palletsprojects.com/en/7.x/commands/#overriding-defaults
+        # Note that while the --db and --plugin CLI options could appear here,
+        # doing it isn't very usful, since the CLI values (including defaults)
+        # always override the corresponding config file values.
 
+        # Options that can be passed multiple times take a list of values:
         # --plugin reader._plugins.enclosure_dedupe:enclosure_dedupe
-        plugin: [reader._plugins.enclosure_dedupe:enclosure_dedupe]
+        # plugin: [reader._plugins.enclosure_dedupe:enclosure_dedupe]
+
+        # Subcommand defaults can be given as nested maps:
 
         # add --update
         add:
+            # Flags take a boolean value:
             update: yes
 
         # update --workers 10 -vv
         update:
             workers: 10
+            # Flags that can be repeated take an integer:
             verbose: 2
 
         search:
@@ -38,10 +82,19 @@ cli:
         serve:
             port: 8888
 
+
+# Web application context.
+#
+# Used for both the serve command (`python -m reader serve`)
+# and when using the WSGI application (reader._app.wsgi:app) directly.
+
 app:
-    # app plugins
-    # <plugin import path>: <plugin options>
-    # options are ignored at the moment
+    # When using the web app, we want to use an additional reader plugin.
+    reader:
+        plugins:
+            reader._plugins.enclosure_dedupe:enclosure_dedupe:
+
+    # ... and some app plugins.
     plugins:
-        'reader._plugins.enclosure_tags:init':
-        'reader._plugins.preview_feed_list:init':
+        reader._plugins.enclosure_tags:init:
+        reader._plugins.preview_feed_list:init:

src/reader/_app/cli.py

@@ -12,7 +12,7 @@
     '--plugin',
     multiple=True,
     envvar=reader._APP_PLUGIN_ENVVAR,
-    help="Import path to a plug-in. Can be passed multiple times.",
+    help="Import path to a web app plug-in. Can be passed multiple times.",
 )
 @click.option('-v', '--verbose', count=True)
 def serve(config, host, port, plugin, verbose):

src/reader/_cli.py

@@ -177,7 +177,7 @@ def wrapper(*args, **kwargs):
     '--plugin',
     multiple=True,
     envvar=reader._PLUGIN_ENVVAR,
-    help="Import path to a plug-in. Can be passed multiple times.",
+    help="Import path to a reader plug-in. Can be passed multiple times.",
 )
 @config_option(
     '--config',