Move changes into their own section. (#38)

thunderbird · Dec 18, 2020 · 14588ff · 14588ff
1 parent 9b8e521
commit 14588ff
Show file tree

Hide file tree

Showing 15 changed files with 117 additions and 67 deletions.
diff --git a/browserAction.rst b/browserAction.rst
@@ -550,7 +550,7 @@ Information sent when a browser action is clicked.
 External Types
 ==============
 
-These following types are not defined by this Thunderbird WebExtension API, but by the underlying Mozilla WebExtension code base.
+The following types are not defined by this API, but by the underlying Mozilla WebExtension code base. They are included here, because there is no other public documentation available.
 
 .. _browserAction.ThemeIcons:
 

diff --git a/composeAction.rst b/composeAction.rst
@@ -556,7 +556,7 @@ Information sent when a compose action is clicked.
 External Types
 ==============
 
-These following types are not defined by this Thunderbird WebExtension API, but by the underlying Mozilla WebExtension code base.
+The following types are not defined by this API, but by the underlying Mozilla WebExtension code base. They are included here, because there is no other public documentation available.
 
 .. _composeAction.ThemeIcons:
 

diff --git a/composeScripts.rst b/composeScripts.rst
@@ -108,7 +108,7 @@ Details of a compose script registered programmatically
 External Types
 ==============
 
-These following types are not defined by this Thunderbird WebExtension API, but by the underlying Mozilla WebExtension code base.
+The following types are not defined by this API, but by the underlying Mozilla WebExtension code base. They are included here, because there is no other public documentation available.
 
 .. _composeScripts.extensionTypes.ExtensionFileOrCode:
 

diff --git a/mailTabs.rst b/mailTabs.rst
@@ -383,7 +383,9 @@ Fired when the displayed folder changes in any mail tab.
    .. api-member::
       :name: ``tab``
       :type: (:ref:`tabs.Tab`)
-      :annotation: -- [Changed in TB 76, previously just the tab's ID]
+      :annotation: 
+
+      *Changed in TB 76: previously just the tab's ID*
 
 
    .. api-member::
@@ -413,7 +415,9 @@ Fired when the selected messages change in any mail tab.
    .. api-member::
       :name: ``tab``
       :type: (:ref:`tabs.Tab`)
-      :annotation: -- [Changed in TB 76, previously just the tab's ID]
+      :annotation: 
+
+      *Changed in TB 76: previously just the tab's ID*
 
 
    .. api-member::

diff --git a/menus.rst b/menus.rst
@@ -541,7 +541,7 @@ ContextType
 
 .. api-section-annotation-hack:: 
 
-The different contexts a menu can appear in. Specifying ``all``        is equivalent to the combination of all other contexts except for ``tab``.
+The different contexts a menu can appear in. Specifying ``all`` is equivalent to the combination of all other contexts except for ``tab``.
 
 .. api-header::
    :label: `string`

diff --git a/messageDisplay.rst b/messageDisplay.rst
@@ -105,7 +105,9 @@ Fired when a message is displayed, whether in a 3-pane tab, a message tab, or a
    .. api-member::
       :name: ``tab``
       :type: (:ref:`tabs.Tab`)
-      :annotation: -- [Changed in TB 76, previously just the tab's ID]
+      :annotation: 
+
+      *Changed in TB 76: previously just the tab's ID*
 
 
    .. api-member::

diff --git a/messageDisplayAction.rst b/messageDisplayAction.rst
@@ -548,7 +548,7 @@ Information sent when a message display action is clicked.
 External Types
 ==============
 
-These following types are not defined by this Thunderbird WebExtension API, but by the underlying Mozilla WebExtension code base.
+The following types are not defined by this API, but by the underlying Mozilla WebExtension code base. They are included here, because there is no other public documentation available.
 
 .. _messageDisplayAction.ThemeIcons:
 

diff --git a/messageDisplayScripts.rst b/messageDisplayScripts.rst
@@ -109,7 +109,7 @@ Details of a message display script registered programmatically
 External Types
 ==============
 
-These following types are not defined by this Thunderbird WebExtension API, but by the underlying Mozilla WebExtension code base.
+The following types are not defined by this API, but by the underlying Mozilla WebExtension code base. They are included here, because there is no other public documentation available.
 
 .. _messageDisplayScripts.extensionTypes.ExtensionFileOrCode:
 

diff --git a/overlay/mailTabs.json b/overlay/mailTabs.json
@@ -24,7 +24,9 @@
         "parameters": [
           {
             "name": "tab",
-            "changed": "76, previously just the tab's ID"
+            "changed": {
+              "76": "previously just the tab's ID"
+              }
           }
         ]
       },
@@ -33,7 +35,9 @@
         "parameters": [
           {
             "name": "tab",
-            "changed": "76, previously just the tab's ID"
+            "changed": {
+              "76": "previously just the tab's ID"
+              }
           }
         ]
       }

diff --git a/overlay/messageDisplay.json b/overlay/messageDisplay.json
@@ -27,7 +27,9 @@
         "parameters": [
           {
             "name": "tab",
-            "changed": "76, previously just the tab's ID"
+            "changed": {
+              "76": "previously just the tab's ID"
+              }
           }
         ]
       },

diff --git a/overlay/tabs.json b/overlay/tabs.json
@@ -4,15 +4,21 @@
     "functions": [
       {
         "name": "executeScript",
-        "changed": "77: with the \"compose\" permission, this now works in the document of email messages during composition."
+        "changed": {
+          "77": "With the \"compose\" permission, this now works in the document of email messages during composition."
+        }
       },
       {
         "name": "insertCSS",
-        "changed": "77: with the \"compose\" permission, this now works in the document of email messages during composition."
+        "changed": {
+          "77": "With the \"compose\" permission, this now works in the document of email messages during composition."
+        }
       },
       {
         "name": "removeCSS",
-        "changed": "77: with the \"compose\" permission, this now works in the document of email messages during composition."
+        "changed": {
+          "77": "With the \"compose\" permission, this now works in the document of email messages during composition."
+        }
       },
       {
         "name": "connect",

diff --git a/overlay/windows.json b/overlay/windows.json
@@ -2,21 +2,6 @@
   {
     "namespace": "windows",
     "functions": [
-      {
-        "name": "getAll",
-        "parameters": [
-          {
-            "name": "getInfo",
-            "properties": {
-              "populate": {
-                "type": "boolean",
-                "optional": true,
-                "description": "If true, each :ref:`windows.Window` object will have a ``tabs`` property that contains a list of the :ref:`tabs.Tab` objects for that window. The ``Tab`` objects only contain the ``url``, ``title`` and ``favIconUrl`` properties if the extension's manifest file includes the ``tabs`` permission."
-              }
-            }
-          }
-        ]
-      },
       {
         "name": "openDefaultBrowser",
         "added": "84",

diff --git a/tabs.rst b/tabs.rst
@@ -587,10 +587,19 @@ Closes one or more tabs.
 executeScript([tabId], details)
 -------------------------------
 
-.. api-section-annotation-hack:: -- [Changed in TB 77: with the "compose" permission, this now works in the document of email messages during composition.]
+.. api-section-annotation-hack:: 
 
 Injects JavaScript code into a page. For details, see the `programmatic injection <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts>`_ section of the content scripts doc.
 
+.. api-header::
+   :label: API changes
+
+
+   .. api-member::
+      :name: Thunderbird 77
+
+      With the "compose" permission, this now works in the document of email messages during composition.
+
 .. api-header::
    :label: Parameters
 
@@ -630,10 +639,19 @@ Injects JavaScript code into a page. For details, see the `programmatic injectio
 insertCSS([tabId], details)
 ---------------------------
 
-.. api-section-annotation-hack:: -- [Changed in TB 77: with the "compose" permission, this now works in the document of email messages during composition.]
+.. api-section-annotation-hack:: 
 
 Injects CSS into a page. For details, see the `programmatic injection <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts>`_ section of the content scripts doc.
 
+.. api-header::
+   :label: API changes
+
+
+   .. api-member::
+      :name: Thunderbird 77
+
+      With the "compose" permission, this now works in the document of email messages during composition.
+
 .. api-header::
    :label: Parameters
 
@@ -659,10 +677,19 @@ Injects CSS into a page. For details, see the `programmatic injection <https://d
 removeCSS([tabId], details)
 ---------------------------
 
-.. api-section-annotation-hack:: -- [Changed in TB 77: with the "compose" permission, this now works in the document of email messages during composition.]
+.. api-section-annotation-hack:: 
 
 Removes injected CSS from a page. For details, see the `programmatic injection <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts>`_ section of the content scripts doc.
 
+.. api-header::
+   :label: API changes
+
+
+   .. api-member::
+      :name: Thunderbird 77
+
+      With the "compose" permission, this now works in the document of email messages during composition.
+
 .. api-header::
    :label: Parameters
 

diff --git a/update-docs.py b/update-docs.py
@@ -97,7 +97,6 @@ def link_ref(ref):
         if additional_type['id'] == ref:
             if not ref in additional_type_used:
                 additional_type_used.append(ref)
-            #print("- adding : " + ref)
             return ":ref:`%s.%s`" % (current_namespace_name, ref)
 
     for moz_namespace in ["extension.", "extensionTypes."]:
@@ -113,14 +112,22 @@ def link_ref(ref):
 
 
 def format_addition(obj):
-    if "changed" in obj:
-        return "-- [Changed in TB %s]" % obj["changed"]
     if "backported" in obj:
         return "-- [Added in TB %s, backported to TB %s]" % (obj["added"], obj["backported"])
     if "added" in obj:
         return "-- [Added in TB %s]" % obj["added"]
     return ""
 
+def format_changes(obj, inline = False):
+    lines = []
+    if "changed" in obj:
+        for k, v in obj['changed'].items():
+            if inline:
+                lines.append("*Changed in TB " + k + ": " + v + "*")
+            else:
+                lines.extend(api_member(name="Thunderbird " + k, description=[v]))
+    return lines
+
 def get_api_member_parts(name, value):
     parts = {
         "name" : "",
@@ -153,7 +160,12 @@ def get_api_member_parts(name, value):
         parts['type'] = type_string % " or ".join(choices)
 
     if "description" in value:
-        parts['description'] = ["", replace_code(value["description"])]
+        parts['description'].append("")
+        parts['description'].append(replace_code(value["description"]))
+
+    if "changed" in value:
+        parts['description'].append("")
+        parts['description'].extend(format_changes(value, inline=True))
 
     parts['enum'].extend(format_enum(name, value))
 
@@ -176,16 +188,15 @@ def format_enum(name, value):
 
     for enum_value in value.get("enum"):
         enum_lines.append(".. api-member::")
-        enum_lines.append("   :name: ``" + enum_value + "``");
+        enum_lines.append("   :name: ``" + enum_value + "``")
         if "enumChanges" in value:
             changes = value.get("enumChanges")
             if enum_value in changes:
                 enum_lines.append("   :annotation: " + format_addition(changes.get(enum_value)))
         enum_lines.append("")
 
     return enum_lines
-
-
+
 def format_object(name, obj, print_description_only = False, print_enum_only = False):
     global unique_id
     # enums have been moved inline and are no longer referenced
@@ -343,6 +354,23 @@ def header_3(string, label=None, info=""):
         "",
     ]
 
+def api_member(name=None, type=None, annotation=None, description=None):
+    lines = [
+        "",
+        ".. api-member::",
+    ]    
+    if name:
+        lines.append("   :name: " + name)
+    if type:
+        lines.append("   :type: " + type)
+    if annotation:
+        lines.append("   :annotation: " + annotation)
+    if description:
+        lines.append("")
+        for line in description:
+            lines.append("   " + line)
+    return lines
+
 def api_entry(label, content = [], annotation=None):
     lines = [
         "",
@@ -407,6 +435,9 @@ def format_namespace(namespace, manifest_namespace=None):
             if "description" in function:
                 lines.append(replace_code(function["description"]))
                 lines.append("")
+
+            if "changed" in function:
+                lines.extend(api_entry("API changes", format_changes(function)))
 
             if len(function.get("parameters", [])) > 0:
                 content = []
@@ -448,6 +479,9 @@ def format_namespace(namespace, manifest_namespace=None):
                 lines.append(replace_code(event["description"]))
                 lines.append("")
 
+            if "changed" in event:
+                lines.extend(api_entry("API changes", format_changes(event)))
+
             if len(event.get("parameters", [])):
                 content = []
                 for param in event["parameters"]:
@@ -477,7 +511,7 @@ def format_namespace(namespace, manifest_namespace=None):
             typegroup = additional_type_defs
             type_header.append("")
             type_header.extend(header_2("External Types", "api-main-section"))
-            type_header.append("These following types are not defined by this Thunderbird WebExtension API, but by the underlying Mozilla WebExtension code base.")
+            type_header.append("The following types are not defined by this API, but by the underlying Mozilla WebExtension code base. They are included here, because there is no other public documentation available.")
             type_header.append("")
 
 
@@ -498,11 +532,14 @@ def format_namespace(namespace, manifest_namespace=None):
                 type_lines.append(replace_code(type_["description"]))
                 type_lines.append("")
 
+            if "changed" in type_:
+                lines.extend(api_entry("API changes", format_changes(type_)))
+
             if "type" in type_:
                 if (type_["type"] == "object" and
                         "isInstanceOf" not in type_ and
                         ("properties" in type_ or "functions" in type_)):
-                    content = [];
+                    content = []
                     if "properties" in type_:
                         items = sorted(type_["properties"].items())
                         for [key, value] in items:
@@ -606,9 +643,9 @@ def format_manifest_namespace(manifest):
             for choice in type_["choices"]:
                 for value in choice["enum"]:
                     permission_lines.append(".. api-member::")
-                    permission_lines.append("   :name: ``" + value + "``");
+                    permission_lines.append("   :name: ``" + value + "``")
                     if value in permission_strings:
-                        permission_lines.append("");
+                        permission_lines.append("")
                         permission_lines.append("   " + permission_strings[value])               
 
     if len(permission_lines) > 0:
@@ -664,6 +701,7 @@ def format_manifest_namespace(manifest):
     for filename in sorted(files):
 
         with open(os.path.join(src_dir, filename + ".json")) as fp_input:
+            print("Reading file: " + filename + ".json")
             content = fp_input.read()
             content = re.sub(r"(^|\n)//.*", "", content)
             document = json.loads(content)