From 949dd6d2a14f11036d251ef7d11607a214389d17 Mon Sep 17 00:00:00 2001
From: Lars-Dominik Braun <lars@6xq.net>
Date: Mon, 29 Jul 2019 15:34:50 +0200
Subject: doc: Auto-generate list of supported click selectors

Using shinx plugin. Also improve click selector descriptions for this
purpose.
---
 doc/_ext/clicklist.py | 45 +++++++++++++++++++++++++++++++++++++++++++++
 doc/conf.py           |  3 +++
 doc/index.rst         |  4 +++-
 doc/plugins.rst       | 16 ++++++++++++++++
 4 files changed, 67 insertions(+), 1 deletion(-)
 create mode 100644 doc/_ext/clicklist.py
 create mode 100644 doc/plugins.rst

(limited to 'doc')

diff --git a/doc/_ext/clicklist.py b/doc/_ext/clicklist.py
new file mode 100644
index 0000000..a69452c
--- /dev/null
+++ b/doc/_ext/clicklist.py
@@ -0,0 +1,45 @@
+"""
+Render click.yaml config file into human-readable list of supported sites
+"""
+
+import pkg_resources, yaml
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from yarl import URL
+
+class ClickList (Directive):
+    def run(self):
+        # XXX: do this once only
+        fd = pkg_resources.resource_stream ('crocoite', 'data/click.yaml')
+        config = list (yaml.safe_load_all (fd))
+
+        l = nodes.definition_list ()
+        for site in config:
+            urls = set ()
+            v = nodes.definition ()
+            vl = nodes.bullet_list ()
+            v += vl
+            for s in site['selector']:
+                i = nodes.list_item ()
+                i += nodes.paragraph (text=s['description'])
+                vl += i
+                urls.update (map (lambda x: URL(x).with_path ('/'), s.get ('urls', [])))
+
+            item = nodes.definition_list_item ()
+            term = ', '.join (map (lambda x: x.host, urls)) if urls else site['match']
+            k = nodes.term (text=term)
+            item += k
+
+            item += v
+            l += item
+        return [l]
+
+def setup(app):
+    app.add_directive ("clicklist", ClickList)
+
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
+
diff --git a/doc/conf.py b/doc/conf.py
index 26747b4..8336c27 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -1,4 +1,5 @@
 # -*- coding: utf-8 -*-
+import os, sys
 
 # -- Project information -----------------------------------------------------
 
@@ -8,9 +9,11 @@ author = 'crocoite contributors'
 
 # -- General configuration ---------------------------------------------------
 
+sys.path.append(os.path.abspath("./_ext"))
 extensions = [
     'sphinx.ext.viewcode',
     'sphinx.ext.autodoc',
+    'clicklist',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/doc/index.rst b/doc/index.rst
index 39c2f73..53f5f77 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -11,6 +11,7 @@ Chrome`_.
    :hidden:
 
    usage.rst
+   plugins.rst
    rationale.rst
    develop.rst
    related.rst
@@ -24,7 +25,7 @@ Google Chrome-powered
 WARC output
     Includes all network requests made by the browser
 Site interaction
-    Auto-expand on-click content, infinite-scrolling
+    :ref:`Auto-expand on-click content <click>`, infinite-scrolling
 DOM snapshot
     Contains the page’s state, renderable without JavaScript
 Image screenshot
@@ -32,3 +33,4 @@ Image screenshot
 Machine-readable interface
     Easy integration into custom tools/scripts
 
+
diff --git a/doc/plugins.rst b/doc/plugins.rst
new file mode 100644
index 0000000..062e1bf
--- /dev/null
+++ b/doc/plugins.rst
@@ -0,0 +1,16 @@
+Plugins
+=======
+
+crocoite comes with plug-ins that modify loaded sites’ or interact with them.
+
+.. _click:
+
+click
+-----
+
+The following sites are currently supported. Note this is an ongoing
+battle against layout changes and thus older software versions will stop
+working very soon.
+
+.. clicklist::
+
-- 
cgit v1.2.3