From: Vladimír Vondruš <mosra@centrum.cz>
Date: Wed, 28 Aug 2019 14:02:33 +0000 (+0200)
Subject: m.sphinx: don't overwrite the docs gathered so far.
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=4df93d4d47611a066e89d39b6caca662918f66b2;p=blog.git

m.sphinx: don't overwrite the docs gathered so far.

This won't work well when more plugins are involved or the directives are
used to parse docstrings. Also updated the plugin docs to not suggest this
practice.
---

diff --git a/doc/documentation/python.rst b/doc/documentation/python.rst
index 767cd45c..f135fad9 100644
--- a/doc/documentation/python.rst
+++ b/doc/documentation/python.rst
@@ -780,14 +780,15 @@ the first level is a name and second level are key/value pairs of the actual
 HTML documentation content. Plugins that parse extra documentation inputs (such
 as `m.sphinx`_) are supposed to add to the dict, which is then used to fill the
 actual documentation contents. The following corresponds to the documentation
-source shown in the `External documentation content`_ section below.
+source shown in the `External documentation content`_ section below. Note that
+the dict can already have existing entries added from elsewhere, so it's
+important to avoid fully overwriting it:
 
 .. code:: py
 
-    class_doc_contents['mymodule.sub.Class'] = {
-        'summary': "A pretty class",
-        'details': "This class is *pretty*."
-    }
+    docs = class_doc_contents.setdefault('mymodule.sub.Class', {})
+    docs['summary'] = "A pretty class"
+    docs['details'] = "This class is *pretty*."
 
 The :py:`hooks_post_crawl`, :py:`hooks_pre_page` and :py:`hooks_post_run`
 variables are lists of functions. Plugins that need to do something at specific
diff --git a/plugins/m/sphinx.py b/plugins/m/sphinx.py
index 75489a94..1d6eee56 100755
--- a/plugins/m/sphinx.py
+++ b/plugins/m/sphinx.py
@@ -55,10 +55,11 @@ class PyModule(rst.Directive):
     option_spec = {'summary': directives.unchanged}
 
     def run(self):
-        module_doc_output[self.arguments[0]] = {
-            'summary': self.options.get('summary'),
-            'content': '\n'.join(self.content)
-        }
+        output = module_doc_output.setdefault(self.arguments[0], {})
+        if self.options.get('summary'):
+            output['summary'] = self.options['summary']
+        if self.content:
+            output['content'] = '\n'.join(self.content)
         return []
 
 class PyClass(rst.Directive):
@@ -68,10 +69,11 @@ class PyClass(rst.Directive):
     option_spec = {'summary': directives.unchanged}
 
     def run(self):
-        class_doc_output[self.arguments[0]] = {
-            'summary': self.options.get('summary'),
-            'content': '\n'.join(self.content) if self.content else None
-        }
+        output = class_doc_output.setdefault(self.arguments[0], {})
+        if self.options.get('summary'):
+            output['summary'] = self.options['summary']
+        if self.content:
+            output['content'] = '\n'.join(self.content)
         return []
 
 class PyEnum(rst.Directive):
@@ -81,10 +83,11 @@ class PyEnum(rst.Directive):
     option_spec = {'summary': directives.unchanged}
 
     def run(self):
-        enum_doc_output[self.arguments[0]] = {
-            'summary': self.options.get('summary'),
-            'content': '\n'.join(self.content) if self.content else None
-        }
+        output = enum_doc_output.setdefault(self.arguments[0], {})
+        if self.options.get('summary'):
+            output['summary'] = self.options['summary']
+        if self.content:
+            output['content'] = '\n'.join(self.content)
         return []
 
 # List option (allowing multiple arguments). See _docutils_assemble_option_dict
@@ -108,12 +111,15 @@ class PyFunction(rst.Directive):
             if name in params: raise KeyError("duplicate param {}".format(name))
             params[name] = content
 
-        function_doc_output[self.arguments[0]] = {
-            'summary': self.options.get('summary'),
-            'params': params,
-            'return': self.options.get('return'),
-            'content': '\n'.join(self.content) if self.content else None
-        }
+        output = function_doc_output.setdefault(self.arguments[0], {})
+        if self.options.get('summary'):
+            output['summary'] = self.options['summary']
+        if params:
+            output['params'] = params
+        if self.options.get('return'):
+            output['return'] = self.options['return']
+        if self.content:
+            output['content'] = '\n'.join(self.content)
         return []
 
 class PyProperty(rst.Directive):
@@ -123,10 +129,11 @@ class PyProperty(rst.Directive):
     option_spec = {'summary': directives.unchanged}
 
     def run(self):
-        property_doc_output[self.arguments[0]] = {
-            'summary': self.options.get('summary'),
-            'content': '\n'.join(self.content) if self.content else None
-        }
+        output = property_doc_output.setdefault(self.arguments[0], {})
+        if self.options.get('summary'):
+            output['summary'] = self.options['summary']
+        if self.content:
+            output['content'] = '\n'.join(self.content)
         return []
 
 class PyData(rst.Directive):
@@ -136,10 +143,11 @@ class PyData(rst.Directive):
     option_spec = {'summary': directives.unchanged}
 
     def run(self):
-        data_doc_output[self.arguments[0]] = {
-            'summary': self.options.get('summary'),
-            'content': '\n'.join(self.content) if self.content else None
-        }
+        output = data_doc_output.setdefault(self.arguments[0], {})
+        if self.options.get('summary'):
+            output['summary'] = self.options['summary']
+        if self.content:
+            output['content'] = '\n'.join(self.content)
         return []
 
 # Modified from abbr / gh / gl / ... to add support for queries and hashes