make authorship code more general purpose

machinaeXphilip · Apr 29, 2019 · 323d635 · 323d635
1 parent 6539ffe
commit 323d635
Show file tree

Hide file tree

Showing 58 changed files with 109 additions and 93 deletions.
diff --git a/STYLE.md b/STYLE.md
@@ -139,7 +139,7 @@ At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergr
 License
 =======
 
-All relevant legal information can be found here 
+All relevant legal information can be found here
 
   * http://www.loremipsum.com/legal/privacy
 
@@ -221,7 +221,7 @@ Updates
 
 Tested with Loremipsum 1.22.1, Uberspace 7.1.1
 
-.. authors::
+.. author_list::
 
 ```
 

diff --git a/authorship/README.md b/authorship/README.md
@@ -9,7 +9,7 @@ of author names.
 ## Usage
 
 Use the ``.. author:: Author Name <email or url>`` directive to add information
-to a document. With ``.. authors::`` you can add a paragraph, that list all
+to a document. With ``.. author_list::`` you can add a paragraph, that list all
 authors that are set for a document, like this::
 
     Written by: author1 <mail@some.org>, author2 <site.org>

diff --git a/authorship/authorship/__init__.py b/authorship/authorship/__init__.py
@@ -29,48 +29,82 @@ def comma_list(nodes_):
     return elements[:-1]
 
 
-class Author(SphinxDirective):
+class ListItem(SphinxDirective):
     """
-    Store author information in the environment (``authors``).
+    Store a list of things (e.g. authors, tags) in the environment of each
+    document.
 
-    Append given author info to the list for the current document.
-
-    From rst markup like::
+    Usage::
 
         .. author:: YourName <YourURL/YourMail>
 
     """
     required_arguments = 1
     final_argument_whitespace = True
 
+    marker_list_name = None
+
     def run(self):
+        assert self.marker_list_name
+
         env = self.state.document.settings.env
+        l = getattr(env, self.marker_list_name)
 
-        env.authors.setdefault(env.docname, [])
-        env.authors[env.docname].append(self.arguments[0])
+        l.setdefault(env.docname, [])
+        l[env.docname].append(self.arguments[0])
 
         return []
 
 
-class Authors(SphinxDirective):
+class DocumentListDisplay(SphinxDirective):
     """
-    Output the list of authors for the document.
+    Output the list of items (e.g. authors, tags) for the document.
 
     Like: `Written by: author1 <mail@some.org>, author2 <site.org>`
 
     From rst markup like::
 
-        .. authors::
+        .. author_list::
 
     """
+
+    marker_list_name = None
+    prefix_text = ''
+
     def run(self):
         env = self.state.document.settings.env
-        authors = env.authors.get(env.docname, [])
+        items = getattr(env, self.marker_list_name).get(env.docname, [])
+
+        if items:
+            return [nodes.Text(self.prefix_text)] + comma_list(nodes.Text(a) for a in items) + [nodes.raw('', '<br>', format='html')]
+        else:
+            return []
+
+
+def add_list_type(app, name, prefix=''):
+    list_name = name + '_list'
+
+    class ListItemImpl(ListItem):
+        marker_list_name = list_name
 
-        if not authors:
-            return [nodes.Text('Written by: Uberspace')]
+    class DocumentListDisplayImpl(DocumentListDisplay):
+        marker_list_name = list_name
+        prefix_text = prefix
 
-        return [nodes.Text('Written by: ')] + comma_list(nodes.Text(a) for a in authors)
+    def init_list(app):
+        """Initialize environment."""
+        setattr(app.builder.env, list_name, {})
+
+    def purge(app, env, docname):
+        """Remove possible stale info for updated documents."""
+        if hasattr(env, list_name):
+            getattr(env, list_name).pop(docname, None)
+
+    directives.register_directive(name, ListItemImpl)
+    directives.register_directive(list_name, DocumentListDisplayImpl)
+
+    app.connect('builder-inited', init_list)
+    app.connect('env-purge-doc', purge)
 
 
 class allauthors(nodes.General, nodes.Element):
@@ -91,25 +125,12 @@ def run(self):
         return [allauthors('')]
 
 
-def builder_inited(app):
-    """Initialize environment."""
-    app.builder.env.authors = {}
-
-
-def purge_authors(app, env, docname):
-    """Remove possible stale info for updated documents."""
-    if not hasattr(env, 'authors'):
-        return
-
-    env.authors.pop(docname, None)
-
-
 def process_authorlists(app, doctree, fromdocname):
     """Build list of authors sorted by contribution count."""
     env = app.builder.env
-    authors = set(itertools.chain(*[authors for authors in env.authors.values()]))
+    authors = set(itertools.chain(*[authors for authors in env.author_list.values()]))
     guides_by_author = {
-        a: set(g for g, guide_authors in env.authors.items() if a in guide_authors)
+        a: set(g for g, guide_authors in env.author_list.items() if a in guide_authors)
         for a in authors
     }
     count_by_author = {a: len(guides_by_author[a]) for a in authors}
@@ -157,14 +178,9 @@ def process_authorlists(app, doctree, fromdocname):
 
 
 def setup(app):
+    add_list_type(app, 'author', 'Written by: ')
     app.add_node(allauthors)
-
-    directives.register_directive('author', Author)
-    directives.register_directive('authors', Authors)
     directives.register_directive('allauthors', AllAuthors)
-
-    app.connect('builder-inited', builder_inited)
-    app.connect('env-purge-doc', purge_authors)
     app.connect('doctree-resolved', process_authorlists)
 
     return {

diff --git a/source/guide_akaunting.rst b/source/guide_akaunting.rst
@@ -131,4 +131,4 @@ You can update the installation in the update wizzard which you can find in the
 
 Tested with Akaunting 1.2.16, Uberspace 7.1.13
 
-.. authors::
+.. author_list::
diff --git a/source/guide_autossh.rst b/source/guide_autossh.rst
@@ -119,4 +119,4 @@ That's it, you have successfully configured an automatically launching port forw
 
 .. _autossh: http://www.harding.motd.ca/autossh/
 
-.. authors::
+.. author_list::
diff --git a/source/guide_babybuddy.rst b/source/guide_babybuddy.rst
@@ -302,4 +302,4 @@ Point your browser to https://isabell.uber.space and log in with the default cre
 
 ----
 
-.. authors::
+.. author_list::
diff --git a/source/guide_bludit.rst b/source/guide_bludit.rst
@@ -291,4 +291,4 @@ When you forgot the admin password, you can reset it manually.
 
 Tested with Bludit 3.8.0 "APA" (3.8.1 "APA" for update), Uberspace 7.2.2.2
 
-.. authors::
+.. author_list::
diff --git a/source/guide_bookstack.rst b/source/guide_bookstack.rst
@@ -178,4 +178,4 @@ After updating your installation you should clean the cache to prevent errors.
 
 Tested with BookStack 0.24.1 Beta, Uberspace 7.1.15
 
-.. authors::
+.. author_list::
diff --git a/source/guide_buildbot.rst b/source/guide_buildbot.rst
@@ -286,4 +286,4 @@ Congratulations! You now have an operational BuildBot_ installation on your Uber
 .. _BuildBot: https://buildbot.net/
 .. _git: https://git-scm.com/
 
-.. authors::
+.. author_list::
diff --git a/source/guide_codimd.rst b/source/guide_codimd.rst
@@ -370,4 +370,4 @@ Manual derived from `this blog <https://w.h8.lv/s/how_to_install_hackmd_on_ubers
 
 Tested with CodiMD 1.2.1, Uberspace 7.1.13
 
-.. authors::
+.. author_list::
diff --git a/source/guide_contao.rst b/source/guide_contao.rst
@@ -187,4 +187,4 @@ Alternatively, the update can also be performed via the `Contao Manager`_ which
 
 Tested with Contao 4.6.10 / Uberspace 7.1.18.0
 
-.. authors::
+.. author_list::
diff --git a/source/guide_cryptpad.rst b/source/guide_cryptpad.rst
@@ -163,4 +163,4 @@ Then you need to restart the service, so the new code is used by the webserver:
 
 Tested with Cryptpad 2.19.0 and Uberspace 7.2.4.0
 
-.. authors::
+.. author_list::
diff --git a/source/guide_django.rst b/source/guide_django.rst
@@ -164,4 +164,4 @@ Change all default passwords. Look at folder permissions. Don't get hacked!
 
 Tested with Django 2.0.5, Uberspace 7.1.6
 
-.. authors::
+.. author_list::
diff --git a/source/guide_dokuwiki.rst b/source/guide_dokuwiki.rst
@@ -105,4 +105,4 @@ Your first plugin you have to install, is the upgrade_ plugin. With this plugin
 
 Tested with DokuWiki 2018-04-22b "Greebo", Uberspace 7.2.1.0
 
-.. authors::
+.. author_list::
diff --git a/source/guide_embetty.rst b/source/guide_embetty.rst
@@ -138,4 +138,4 @@ Use ``npm`` to update Embetty:
 
 Tested with Embetty 1.0.0-beta.6, Uberspace 7.1.7.0
 
-.. authors::
+.. author_list::
diff --git a/source/guide_eqdkp-plus.rst b/source/guide_eqdkp-plus.rst
@@ -84,4 +84,4 @@ The easiest way to update EQdkp Plus is to use the web updater provided in the a
 
 Tested with EQdkp Plus 2.3.0.26, Uberspace 7.1.3
 
-.. authors::
+.. author_list::
diff --git a/source/guide_etherpad.rst b/source/guide_etherpad.rst
@@ -220,4 +220,4 @@ It might take a few minutes before your Etherpad comes back online because ``npm
 
 Tested with Etherpad Lite 1.7.0 and Uberspace 7.1.15.0
 
-.. authors::
+.. author_list::
diff --git a/source/guide_flatboard.rst b/source/guide_flatboard.rst
@@ -188,4 +188,4 @@ Delete the ``theme/YourTheme/cache/`` folder. In this example ``bootstrap`` them
 
 Tested with Flatboard 2.1 "PIÉMONT", Uberspace 7.2.2.2
 
-.. authors::
+.. author_list::
diff --git a/source/guide_freshrss.rst b/source/guide_freshrss.rst
@@ -131,4 +131,4 @@ This will overwrite any changed files while keeping your current configuration.
 
 Tested with FreshRSS 1.11.2, Uberspace 7.1.12.0
 
-.. authors::
+.. author_list::
diff --git a/source/guide_ghost.rst b/source/guide_ghost.rst
@@ -231,4 +231,4 @@ If it's not in state RUNNING, check your configuration.
 
 Tested with Ghost 2.0.0, Uberspace 7.1.11
 
-.. authors::
+.. author_list::
diff --git a/source/guide_gitea.rst b/source/guide_gitea.rst
@@ -167,4 +167,4 @@ version is available, stop daemon by ``supervisorctl stop gitea`` and repeat the
 
 Tested with Gitea 1.7.2, Uberspace 7.1.16
 
-.. authors::
+.. author_list::
diff --git a/source/guide_grav.rst b/source/guide_grav.rst
@@ -129,4 +129,4 @@ After updating the Grav core use the ``update`` command to update all plugins an
 
 Tested with Grav 1.5.2, Uberspace 7.1.13
 
-.. authors::
+.. author_list::
diff --git a/source/guide_gsales2.rst b/source/guide_gsales2.rst
@@ -167,4 +167,4 @@ A more detailed update instruction can be found on the `gsales website <gsalesup
 
 Tested with GSALES 2 Revision #1123 for PHP 7.1, Uberspace 7.1.16
 
-.. authors::
+.. author_list::
diff --git a/source/guide_hugo.rst b/source/guide_hugo.rst
@@ -172,4 +172,4 @@ If there is a new version available, update the ``hugo`` binary in ``~/bin`` (re
 
 Tested with Hugo 0.54, Uberspace 7.2.1.0
 
-.. authors::
+.. author_list::
diff --git a/source/guide_ioncube.rst b/source/guide_ioncube.rst
@@ -131,4 +131,4 @@ Changes to the PHP configuration will take effect after reloading PHP:
 
 Tested with IonCube 10.2.7, Uberspace 7.1.16
 
-.. authors::
+.. author_list::
diff --git a/source/guide_jekyll.rst b/source/guide_jekyll.rst
@@ -207,4 +207,4 @@ Since Jekyll is a ruby gem, you can update Jekyll and every gem needed by your w
 
 Tested with Ruby 2.5.3, Jekyll 3.8.5, Uberspace 7.2.2
 
-.. authors::
+.. author_list::
diff --git a/source/guide_jingo.rst b/source/guide_jingo.rst
@@ -233,4 +233,4 @@ In the end you need to restart the service daemon, so the new code is used by th
 
 Tested with Jingo 1.8.5, Uberspace 7.1.1
 
-.. authors::
+.. author_list::
diff --git a/source/guide_joomla.rst b/source/guide_joomla.rst
@@ -91,4 +91,4 @@ The easiest way to update Joomla! is to use the web updater provided in the admi
 
 Tested with Joomla! 3.8.12, Uberspace 7.1.12
 
-.. authors::
+.. author_list::
diff --git a/source/guide_kanboard.rst b/source/guide_kanboard.rst
@@ -216,4 +216,4 @@ Check the `Kanboard documentation`_ if the configuration changed between ``confi
 
 Tested with Kanboard 1.2.6, Uberspace 7.1.14.0
 
-.. authors::
+.. author_list::
diff --git a/source/guide_kirby.rst b/source/guide_kirby.rst
@@ -140,4 +140,4 @@ If you've enabled the cache, you might need to empty the page cache directory to
 
 Tested with Kirby 3.0.0 and Uberspace 7.2.1
 
-.. authors::
+.. author_list::
diff --git a/source/guide_limesurvey.rst b/source/guide_limesurvey.rst
@@ -152,5 +152,5 @@ When a new version is released, copy the download link and download it as above,
 
 Tested with LimeSurvey 3.14.11+180926, Uberspace 7.1.13.0
 
-.. authors::
+.. author_list::
 
diff --git a/source/guide_lychee.rst b/source/guide_lychee.rst
@@ -85,4 +85,4 @@ If a new version is available, ``cd`` to your Lychee folder and do a simple ``gi
 
 Tested with Lychee 3.1.6, Uberspace 7.1.1
 
-.. authors::
+.. author_list::
diff --git a/source/guide_mailman-3.rst b/source/guide_mailman-3.rst
@@ -410,4 +410,4 @@ Tested with Django 2.1.8, HyperKitty 1.2.2, Mailman 3.2.2, Postorius 1.2.4 and u
 .. _SASS: https://sass-lang.com/
 
 
-.. authors::
+.. author_list::
diff --git a/source/guide_mailman.rst b/source/guide_mailman.rst
@@ -272,4 +272,4 @@ This guide is based on the `official Mailman 2.1 installation instructions <http
 .. _documentation: https://www.gnu.org/software/mailman/mailman-install.txt
 
 
-.. authors::
+.. author_list::
diff --git a/source/guide_matomo.rst b/source/guide_matomo.rst
@@ -162,4 +162,4 @@ The easiest way to update Matomo is to use the web updater provided in the admin
 
 Tested with Matomo 3.5.0, Uberspace 7.1.3
 
-.. authors::
+.. author_list::
diff --git a/source/guide_miniflux.rst b/source/guide_miniflux.rst
@@ -237,4 +237,4 @@ Check the `Miniflux`_ website for news and/or breaking changes.
 
 Tested with Miniflux 2.0.12, Uberspace 7.1.15.0
 
-.. authors::
+.. author_list::
diff --git a/source/guide_minim.rst b/source/guide_minim.rst
@@ -109,4 +109,4 @@ If everything works alright you can delete the ``config-new`` directory.
 
 Tested with minim 0.9.4, Uberspace 7.2.4
 
-.. authors::
+.. author_list::
diff --git a/source/guide_mongodb.rst b/source/guide_mongodb.rst
@@ -225,5 +225,5 @@ Restart your MongoDB and login to check the version.
 
 Tested with MongoDB 4.0.5, Uberspace 7.2.1.0
 
-.. authors::
+.. author_list::
 
diff --git a/source/guide_neos.rst b/source/guide_neos.rst
@@ -143,4 +143,4 @@ By using composer, you can update an existing installation to a specific version
 
 Tested with Neos 4.1.7 and Uberspace 7.1.15
 
-.. authors::
+.. author_list::
diff --git a/source/guide_nextcloud.rst b/source/guide_nextcloud.rst
@@ -164,4 +164,4 @@ In most cases this happens due to wrong `SELinux labels`_ which can be fixed wit
 
 Tested with Nextcloud 13.0.1, Uberspace 7.1.3
 
-.. authors::
+.. author_list::
diff --git a/source/guide_octobercms.rst b/source/guide_octobercms.rst
@@ -133,4 +133,4 @@ To update October and your installed plugins you can use the ``october:update``
 
 Tested with OctoberCMS 1.0.443, Uberspace 7.1.14
 
-.. authors::
+.. author_list::
Original file line number	Diff line number	Diff line change
Expand Up		@@ -131,4 +131,4 @@ You can update the installation in the update wizzard which you can find in the

		Tested with Akaunting 1.2.16, Uberspace 7.1.13

		.. authors::
		.. author_list::
Original file line number	Diff line number	Diff line change
Expand Up		@@ -119,4 +119,4 @@ That's it, you have successfully configured an automatically launching port forw

		.. _autossh: http://www.harding.motd.ca/autossh/

		.. authors::
		.. author_list::
Original file line number	Diff line number	Diff line change
Expand Up		@@ -302,4 +302,4 @@ Point your browser to https://isabell.uber.space and log in with the default cre

		----

		.. authors::
		.. author_list::
Original file line number	Diff line number	Diff line change
Expand Up		@@ -291,4 +291,4 @@ When you forgot the admin password, you can reset it manually.

		Tested with Bludit 3.8.0 "APA" (3.8.1 "APA" for update), Uberspace 7.2.2.2

		.. authors::
		.. author_list::
Original file line number	Diff line number	Diff line change
Expand Up		@@ -178,4 +178,4 @@ After updating your installation you should clean the cache to prevent errors.

		Tested with BookStack 0.24.1 Beta, Uberspace 7.1.15

		.. authors::
		.. author_list::
Original file line number	Diff line number	Diff line change
Expand Up		@@ -370,4 +370,4 @@ Manual derived from `this blog <https://w.h8.lv/s/how_to_install_hackmd_on_ubers

		Tested with CodiMD 1.2.1, Uberspace 7.1.13

		.. authors::
		.. author_list::
Original file line number	Diff line number	Diff line change
Expand Up		@@ -187,4 +187,4 @@ Alternatively, the update can also be performed via the `Contao Manager`_ which

		Tested with Contao 4.6.10 / Uberspace 7.1.18.0

		.. authors::
		.. author_list::
Original file line number	Diff line number	Diff line change
Expand Up		@@ -163,4 +163,4 @@ Then you need to restart the service, so the new code is used by the webserver:

		Tested with Cryptpad 2.19.0 and Uberspace 7.2.4.0

		.. authors::
		.. author_list::
Original file line number	Diff line number	Diff line change
Expand Up		@@ -164,4 +164,4 @@ Change all default passwords. Look at folder permissions. Don't get hacked!

		Tested with Django 2.0.5, Uberspace 7.1.6

		.. authors::
		.. author_list::
Original file line number	Diff line number	Diff line change
Expand Up		@@ -105,4 +105,4 @@ Your first plugin you have to install, is the upgrade_ plugin. With this plugin

		Tested with DokuWiki 2018-04-22b "Greebo", Uberspace 7.2.1.0

		.. authors::
		.. author_list::