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 767cd45c6c424ea1e80d2b7f86695187e522eec5..f135fad959e7d5cd72e215ec637fa19bb1ab5a40 100644 (file)
--- 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 75489a94ff006d53cf22720ee6fd2a98eba4332d..1d6eee56b9c4c8aedfcc6664b4552bce2ffad959 100755 (executable)
--- 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