Move how-to to examples

thunderbird · Jan 11, 2024 · 1967881 · 1967881
1 parent 0a71580
commit 1967881
Show file tree

Hide file tree

Showing 44 changed files with 173 additions and 159 deletions.
diff --git a/accounts.rst b/accounts.rst
@@ -12,7 +12,7 @@
 
   ≡ Related information
 
-  * :doc:`/how-to/eventListeners`
+  * :doc:`/examples/eventListeners`
 
 ============
 accounts API

diff --git a/addressBooks.provider.rst b/addressBooks.provider.rst
@@ -9,8 +9,8 @@
 
   ≡ Related information
 
-  * :doc:`/how-to/contacts`
-  * :doc:`/how-to/eventListeners`
+  * :doc:`/examples/contacts`
+  * :doc:`/examples/eventListeners`
 
 =========================
 addressBooks.provider API

diff --git a/addressBooks.rst b/addressBooks.rst
@@ -11,8 +11,8 @@
 
   ≡ Related information
 
-  * :doc:`/how-to/contacts`
-  * :doc:`/how-to/eventListeners`
+  * :doc:`/examples/contacts`
+  * :doc:`/examples/eventListeners`
 
   ≡ Related examples on Github
 

diff --git a/changes/esr78.rst b/changes/esr78.rst
@@ -94,7 +94,7 @@ compose API
   serialise the document back to a string before calling setComposeDetails. `Here's a sample
   extension.`__
 
-  __ https://github.com/thunderbird/sample-extensions/tree/master/composeBody
+  __ https://github.com/thunderbird/sample-extensions/tree/master/manifest_v2/composeBody
 
 messages API
 ============

diff --git a/cloudFile.rst b/cloudFile.rst
@@ -11,7 +11,7 @@
 
   ≡ Related information
 
-  * :doc:`/how-to/eventListeners`
+  * :doc:`/examples/eventListeners`
 
   ≡ Related examples on Github
 

diff --git a/commands.rst b/commands.rst
@@ -11,7 +11,7 @@
 
   ≡ Related information
 
-  * :doc:`/how-to/eventListeners`
+  * :doc:`/examples/eventListeners`
 
 ============
 commands API

diff --git a/compose.rst b/compose.rst
@@ -11,7 +11,7 @@
 
   ≡ Related information
 
-  * :doc:`/how-to/eventListeners`
+  * :doc:`/examples/eventListeners`
 
   ≡ Related examples on Github
 

diff --git a/composeAction.rst b/composeAction.rst
@@ -12,7 +12,7 @@
 
   ≡ Related information
 
-  * :doc:`/how-to/eventListeners`
+  * :doc:`/examples/eventListeners`
 
 =================
 composeAction API

diff --git a/contacts.rst b/contacts.rst
@@ -6,13 +6,14 @@
   * `Functions`_
   * `Events`_
   * `Types`_
+  * `Examples`_
 
   .. include:: /overlay/developer-resources.rst
 
   ≡ Related information
 
-  * :doc:`/how-to/contacts`
-  * :doc:`/how-to/eventListeners`
+  * :doc:`/examples/contacts`
+  * :doc:`/examples/eventListeners`
 
   ≡ Related examples on Github
 
@@ -507,7 +508,7 @@ ContactProperties
 
 .. api-section-annotation-hack:: 
 
-A set of individual properties for a particular contact, and its vCard string. Further information can be found in :ref:`howto_contacts`.
+A set of individual properties for a particular contact, and its vCard string. Further information can be found in :doc:`/examples/contacts`.
 
 .. api-header::
    :label: object
@@ -594,3 +595,12 @@ Object defining a query for :ref:`contacts.quickSearch`.
 
       One or more space-separated terms to search for.
 
+
+
+.. rst-class:: examples
+
+Examples
+========
+
+
+.. include:: /examples/contacts.rst
diff --git a/how-to/contacts.rst → examples/contacts.rst b/how-to/contacts.rst → examples/contacts.rst
@@ -1,5 +1,3 @@
-.. _howto_contacts:
-
 ===========================
 Working with vCard contacts
 ===========================

diff --git a/how-to/eventListeners.rst → examples/eventListeners.rst b/how-to/eventListeners.rst → examples/eventListeners.rst
diff --git a/how-to/messageLists.rst → examples/messageLists.rst b/how-to/messageLists.rst → examples/messageLists.rst
diff --git a/experiments/contribute.rst b/experiments/contribute.rst
@@ -0,0 +1,8 @@
+Getting your API added to Thunderbird
+=====================================
+
+If you think your API would be useful to other extensions, consider having it added to Thunderbird.
+`File a bug in the Extensions API component`__ and add your schema and implementation files as
+attachments.
+
+__ https://bugzilla.mozilla.org/enter_bug.cgi?product=Thunderbird&component=Add-Ons%3A%20Extensions%20API
diff --git a/experiments/folders_and_messages.rst b/experiments/folders_and_messages.rst
@@ -0,0 +1,26 @@
+Using folder and message types
+==============================
+
+The built-in schema define some common objects that you may wish to return, namely
+:ref:`MailFolder <folders.MailFolder>`, :ref:`MessageHeader <messages.MessageHeader>`,
+and :ref:`MessageList <messages.MessageList>`.
+
+To use these types, interact with the ``folderManager`` or ``messageManager`` objects which are
+members of the ``context.extension`` object passed to ``getAPI``:
+
+.. code-block:: javascript
+
+  // Get an nsIMsgFolder from a MailFolder:
+  let realFolder = context.extension.folderManager.get(accountId, path);
+
+  // Get a MailFolder from an nsIMsgFolder:
+  context.extension.folderManager.convert(realFolder);
+
+  // Get an nsIMsgDBHdr from a MessageHeader:
+  let realMessage = context.extension.messageManager.get(messageId);
+
+  // Get a MessageHeader from an nsIMsgDBHdr:
+  context.extension.messageManager.convert(realMessage);
+
+  // Start a MessageList from an array or enumerator of nsIMsgDBHdr:
+  context.extension.messageManager.startMessageList(realFolder.messages);
diff --git a/experiments/generator.rst b/experiments/generator.rst
@@ -0,0 +1,8 @@
+The Experiment API generator
+============================
+
+Try the `Experiment API generator`__ to quickly get started making a WebExtension Experiment API. It
+doesn't cover all the possibilities, but should be useful for most use-cases or learning how
+things work.
+
+__ https://darktrojan.github.io/generator/generator.html
diff --git a/how-to/experiments.rst → experiments/introduction.rst b/how-to/experiments.rst → experiments/introduction.rst
@@ -1,44 +1,43 @@
-========================
-WebExtension Experiments
-========================
+Introduction to Experiment APIs
+===============================
 
-A WebExtension experiment is an additional API that is shipped with your WebExtension. It allows
+A WebExtension Experiment API is an additional API that is shipped with your WebExtension. It allows
 your extension to interact with Thunderbird, much like earlier types of extension did. If you find
-the built-in Thunderbird APIs can do 80% of what you want to achieve, then WebExtension experiments
-are for you.
+the built-in Thunderbird APIs can do 80% of what you want to achieve, then WebExtension Experiment
+APIs are for you.
 
 .. note::
 
-  Firefox does not allow WebExtension experiments on release or beta versions. Thunderbird does.
-
-Adding an experiment to your extension
-======================================
+  Firefox does not allow WebExtension Experiment APIs on release or beta versions. Thunderbird does.
 
 The full code of this example is `on GitHub`__.
 
-__ https://github.com/thunderbird/sample-extensions/tree/master/experiment
+__ https://github.com/thunderbird/sample-extensions/tree/master/manifest_v2/experiment
 
 .. note::
 
   This is a very cut-down example. You may find the `Firefox documentation`__ helpful, particularly
   the pages on `API schemas`__, `implementing a function`__, and `implementing an event`__.
 
+  There is also a detailed introduction at `developer.thunderbird.net`__.
+
 __ https://firefox-source-docs.mozilla.org/toolkit/components/extensions/webextensions/index.html
 __ https://firefox-source-docs.mozilla.org/toolkit/components/extensions/webextensions/schema.html
 __ https://firefox-source-docs.mozilla.org/toolkit/components/extensions/webextensions/functions.html
 __ https://firefox-source-docs.mozilla.org/toolkit/components/extensions/webextensions/events.html
+__ https://developer.thunderbird.net/add-ons/mailextensions/experiments
 
 Extension manifest
 ------------------
 
-Experimental APIs are declared in the experiment_apis property in a WebExtension’s manifest.json
+Experiment APIs are declared in the experiment_apis property in a WebExtension’s manifest.json
 file. For example:
 
 .. code-block:: json
 
   {
     "manifest_version": 2,
-    "name": "Extension containing an experimental API",
+    "name": "Extension containing an Experiment API",
     "experiment_apis": {
       "myapi": {
         "schema": "schema.json",
@@ -148,90 +147,4 @@ extension calls ``browser.myapi.onToolbarClick.removeListener``, or shuts down.
         }
       }
     }
-  };
-
-Using folder and message types
-------------------------------
-
-The built-in schema define some common objects that you may wish to return, namely
-:ref:`MailFolder <folders.MailFolder>`, :ref:`MessageHeader <messages.MessageHeader>`,
-and :ref:`MessageList <messages.MessageList>`.
-
-To use these types, interact with the ``folderManager`` or ``messageManager`` objects which are
-members of the ``context.extension`` object passed to ``getAPI``:
-
-.. code-block:: javascript
-
-  // Get an nsIMsgFolder from a MailFolder:
-  let realFolder = context.extension.folderManager.get(accountId, path);
-
-  // Get a MailFolder from an nsIMsgFolder:
-  context.extension.folderManager.convert(realFolder);
-
-  // Get an nsIMsgDBHdr from a MessageHeader:
-  let realMessage = context.extension.messageManager.get(messageId);
-
-  // Get a MessageHeader from an nsIMsgDBHdr:
-  context.extension.messageManager.convert(realMessage);
-
-  // Start a MessageList from an array or enumerator of nsIMsgDBHdr:
-  context.extension.messageManager.startMessageList(realFolder.messages);
-
-Using tabs and windows
-----------------------
-
-To access tabs or windows using the ID values from the built-in APIs, use the ``tabManager`` or
-``windowManager`` objects. These are have functions similar to, but not the same as, the APIs:
-
-.. code-block:: javascript
-
-  // Get a real tab from a tab ID:
-  let tabObject = context.extension.tabManager.get(tabId);
-  let realTab = tabObject.nativeTab;
-  let realTabWindow = tabObject.window;
-
-  // Get a tab ID from a real tab:
-  context.extension.tabManager.getWrapper(realTab).id;
-
-  // Query tabs: (note this returns a Generator, not an array like the API)
-  context.extension.tabManager.query(queryInfo);
-
-"Tabs" are a bit weird. For a tab on the main Thunderbird window, the ``nativeTab`` property is
-the ``tabInfo`` object you'd get from that window's ``<tabmail>``. For a tab *not* on the main
-window, e.g. a "tab" representing the message composition window, both ``nativeTab`` and ``window``
-properties refer to the window itself.
-
-.. code-block:: javascript
-
-  // Get a real window from a window ID:
-  let windowObject = context.extension.windowManager.get(windowId);
-  let realWindow = windowObject.window;
-
-  // Get a window ID from a real window:
-  context.extension.windowManager.getWrapper(realWindow).id;
-
-  // Get all windows: (note this returns a Generator, not an array like the API)
-  context.extension.windowManager.getAll();
-
-For more things you could use on ``tabObject`` or ``windowObject`` in the examples above, see
-`the Tab, TabMailTab, and Window classes in the source code`__.
-
-__ https://hg.mozilla.org/releases/comm-esr78/file/tip/mail/components/extensions/parent/ext-mail.js#l763
-
-Experiment API Generator
-========================
-
-Try the `Experiment Generator`__ to quickly get started making a WebExtension experiment. It
-doesn't cover all the possibilities, but should be useful for most use-cases or learning how
-things work.
-
-__ https://darktrojan.github.io/generator/generator.html
-
-Getting your API added to Thunderbird
-=====================================
-
-If you think your API would be useful to other extensions, consider having it added to Thunderbird.
-`File a bug in the Extensions API component`__ and add your schema and implementation files as
-attachments.
-
-__ https://bugzilla.mozilla.org/enter_bug.cgi?product=Thunderbird&component=Add-Ons%3A%20Extensions%20API
+  };
diff --git a/experiments/tabs_and_windows.rst b/experiments/tabs_and_windows.rst
@@ -0,0 +1,40 @@
+Using tabs and windows
+======================
+
+To access tabs or windows using the ID values from the built-in APIs, use the ``tabManager`` or
+``windowManager`` objects. These are have functions similar to, but not the same as, the APIs:
+
+.. code-block:: javascript
+
+  // Get a real tab from a tab ID:
+  let tabObject = context.extension.tabManager.get(tabId);
+  let realTab = tabObject.nativeTab;
+  let realTabWindow = tabObject.window;
+
+  // Get a tab ID from a real tab:
+  context.extension.tabManager.getWrapper(realTab).id;
+
+  // Query tabs: (note this returns a Generator, not an array like the API)
+  context.extension.tabManager.query(queryInfo);
+
+"Tabs" are a bit weird. For a tab on the main Thunderbird window, the ``nativeTab`` property is
+the ``tabInfo`` object you'd get from that window's ``<tabmail>``. For a tab *not* on the main
+window, e.g. a "tab" representing the message composition window, both ``nativeTab`` and ``window``
+properties refer to the window itself.
+
+.. code-block:: javascript
+
+  // Get a real window from a window ID:
+  let windowObject = context.extension.windowManager.get(windowId);
+  let realWindow = windowObject.window;
+
+  // Get a window ID from a real window:
+  context.extension.windowManager.getWrapper(realWindow).id;
+
+  // Get all windows: (note this returns a Generator, not an array like the API)
+  context.extension.windowManager.getAll();
+
+For more things you could use on ``tabObject`` or ``windowObject`` in the examples above, see
+`the Tab, TabMailTab, and Window classes in the source code`__.
+
+__ https://hg.mozilla.org/releases/comm-esr78/file/tip/mail/components/extensions/parent/ext-mail.js#l763
diff --git a/folders.rst b/folders.rst
@@ -11,7 +11,7 @@
 
   ≡ Related information
 
-  * :doc:`/how-to/eventListeners`
+  * :doc:`/examples/eventListeners`
 
 ===========
 folders API

diff --git a/identities.rst b/identities.rst
@@ -11,7 +11,7 @@
 
   ≡ Related information
 
-  * :doc:`/how-to/eventListeners`
+  * :doc:`/examples/eventListeners`
 
 ==============
 identities API