Update plugin/config docs and experimental plugin entry points. #395

Author: lemon24

docs/app.rst

@@ -40,11 +40,11 @@ An example uWSGI configuration file (probably not idiomatic, from `here`_)::
     mount = /reader=reader._app.wsgi:app
     plugin = python3
     virtualenv = /apps/reader/
-    env = READER_CONFIG=/apps/reader/reader.yaml
+    env = READER_CONFIG=/apps/reader/reader.toml
 
 
-You can also run the web application with the ``serve`` command.
-``serve`` uses `Werkzeug's development server`_,
+You can also run the web application with the ``web run`` command.
+``web run`` uses `Werkzeug's development server`_,
 so it probably won't scale well past a single user.
 
 .. note::
@@ -53,14 +53,16 @@ so it probably won't scale well past a single user.
     you may want to configure your web server to not send a ``Referer`` header
     (by setting ``Referrer-Policy`` header to ``same-origin``
     for all responses; `nginx example`_).
-    The ``serve`` command does it by default.
+    The ``web run`` command does it by default.
 
 
-If running on a personal computer, you can use cron to run ``serve`` at boot::
+If running on a personal computer, you can use cron to run ``web run`` at boot::
 
-    @reboot     sleep 60; reader serve -p 8080 2>&1 ) >>"/tmp/$LOGNAME.reader.serve.boot.log"
+    @reboot     sleep 60; reader web run -p 8080 2>&1 ) >>"/tmp/$LOGNAME.reader.web.run.boot.log"
 
 
+.. FIXME link to new config
+
 .. _here: https://github.com/lemon24/owncloud/blob/b6a6ba28f84fa40a1a822c200c9e245bad84600b/reader.yaml#L77
 .. _nginx example: https://github.com/lemon24/owncloud/commit/39c5311d9c0973642d3a7dec73369b3607828fdd#diff-4486765de09ef22bfc83d68c7350a8088db6f2ba35f152f49ee36c8ec5aef03d
 .. _Flask documentation: http://flask.pocoo.org/docs/1.0/deploying/

docs/cli.rst

@@ -2,18 +2,12 @@
 Command-line interface
 ======================
 
-*reader* comes with a command-line interface
-that exposes basic management functionality.
-
-
-.. warning::
-
-    The CLI is is not fully stable,
-    see the :ref:`roadmap <cli roadmap>` for details.
+*reader* comes with a CLI
+that exposes management functionality.
 
 .. note::
 
-    The command-line interface is optional, use the ``cli`` extra to install
+    The CLI is optional, use the ``cli`` extra to install
     its :ref:`dependencies <Optional dependencies>`.
 
 Most commands need a database to work. The following are equivalent:

docs/config.rst

@@ -3,12 +3,7 @@ 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.
+be configured from a TOML file.
 
 .. note::
 
@@ -21,17 +16,15 @@ 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 configuration file matches the shape of the :doc:`CLI <cli>`
+(the ``reader`` section has options for the ``reader`` command,
+the ``reader.update`` section has options for the ``reader update`` command, etc.).
+In general, option names match those in the CLI
+(``--feed-root`` -> ``feed_root``);
+options that can be passed multiple times in the CLI
+are pluralized in the config
+(``--cli-plugin`` -> ``cli_plugins``).
 
-The following example shows the config file structure
-and the options currently available:
+Example:
 
 .. literalinclude:: ../examples/config.toml

docs/guide.rst

@@ -747,8 +747,8 @@ Plugins
 To use a built-in plugin, pass the plugin name to :func:`make_reader`::
 
     >>> reader = make_reader("db.sqlite", plugins=[
-    ...     "reader.enclosure_dedupe",
-    ...     "reader.entry_dedupe",
+    ...     ".enclosure_dedupe",
+    ...     ".entry_dedupe",
     ... ])
 
 

docs/plugins.rst

@@ -100,30 +100,23 @@ You can still find the code on GitHub:
 Loading plugins from the CLI and the web application
 ----------------------------------------------------
 
-There is experimental support of plugins in the CLI and the web application.
-
-.. warning::
-
-    The plugin system/hooks are not stable yet and may change without any notice.
-
-
-To load plugins, set the ``READER_PLUGIN`` environment variable to the plugin
+To load plugins, set the ``READER_PLUGINS`` environment variable to the plugin
 entry point (e.g. ``package.module:entry_point``); multiple entry points should
-be separated by one space::
+be separated by space::
 
-    READER_PLUGIN='first.plugin:entry_point second_plugin:main' \
+    READER_PLUGINS='first.plugin:entry_point second_plugin' \
     python -m reader some-command
 
-For `built-in plugins`_, it is enough to use the plugin name (``reader.XYZ``).
+For `built-in plugins`_, it is enough to use the plugin name (``.plugin``).
 
 .. note::
 
     :func:`make_reader` ignores the plugin environment variables.
 
 
-To load web application plugins, set the ``READER_APP_PLUGIN`` environment variable.
+To load web application plugins, set the ``READER_WEB_PLUGINS`` environment variable.
 To load CLI plugins (that customize the CLI),
-set the ``READER_CLI_PLUGIN`` environment variable.
+set the ``READER_CLI_PLUGINS`` environment variable.
 
 
 

examples/config.toml

@@ -8,7 +8,7 @@ feed_root = "/path/to/feeds"
 # Options that can be passed multiple times take a list of values
 # (unlike other settings, plugins are merged with commandline options).
 plugins = [
-    "reader._plugins.sqlite_releases:init",
+    "reader._plugins.sqlite_releases",
     ".ua_fallback",
 ]
 

src/reader/_plugins/cli_status.py

@@ -16,7 +16,7 @@
 
 To load::
 
-    READER_CLI_PLUGIN='reader._plugins.cli_status.init_cli' \\
+    READER_CLI_PLUGINS='reader._plugins.cli_status' \\
     python -m reader ...
 
 """

src/reader/_plugins/legacy/enclosure_tags.py

@@ -19,7 +19,7 @@
 
 To load::
 
-    READER_APP_PLUGIN='reader._plugins.legacy.enclosure_tags:init' \\
+    READER_WEB_PLUGINS='reader._plugins.legacy.enclosure_tags' \\
     python -m reader serve
 
 Implemented for :issue:`50`.
@@ -163,6 +163,6 @@ def enclosure_tags_filter(enclosure, entry, feed_tags):
     return [('with tags', url_for('enclosure_tags.enclosure_tags', **args))]
 
 
-def init(app):
+def init_app(app):
     app.register_blueprint(blueprint)
     app.reader_additional_enclosure_links.append(enclosure_tags_filter)

src/reader/_plugins/legacy/preview_feed_list.py

@@ -14,7 +14,7 @@
 
 To load::
 
-    READER_APP_PLUGIN='reader._plugins.legacy.preview_feed_list:init' \\
+    READER_WEB_PLUGINS='reader._plugins.legacy.preview_feed_list' \\
     python -m reader serve
 
 Implemented for https://github.com/lemon24/reader/issues/150.
@@ -154,5 +154,5 @@ def handle_parse_error_i_guess(error):
     return redirect(url_for('preview_feed_list.feed_list', url=parse_error.url))
 
 
-def init(app):
+def init_app(app):
     app.register_blueprint(blueprint)

src/reader/_plugins/legacy/share.py

@@ -6,7 +6,7 @@
 
 To load::
 
-    READER_APP_PLUGIN='reader._plugins.legacy.share:init' \\
+    READER_WEB_PLUGINS='reader._plugins.legacy.share' \\
     python -m reader serve
 
 """
@@ -49,5 +49,5 @@ def share(entry):
         yield name, url
 
 
-def init(app):
+def init_app(app):
     app.reader_additional_links.append(share)