Bug 1595953 - Connect UITour-lib.js docs to sphinx-js to publish on firefox-source-docs. r=markh
authorMatthew Noorenberghe <mozilla@noorenberghe.ca>
Wed, 13 Nov 2019 02:40:03 +0000
changeset 501690 ef26ae2ee4c22fc88d6590244862066f1974c6ce
parent 501689 519ad74e9d7be8ea39e7c451cc346e04b7f7adb3
child 501691 17e7f137067f89c0d82cada3af77b1bc5161c547
push id114172
push userdluca@mozilla.com
push dateTue, 19 Nov 2019 11:31:10 +0000
treeherdermozilla-inbound@b5c5ba07d3db [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersmarkh
bugs1595953
milestone72.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1595953 - Connect UITour-lib.js docs to sphinx-js to publish on firefox-source-docs. r=markh Differential Revision: https://phabricator.services.mozilla.com/D52772
browser/components/uitour/UITour-lib.js
browser/components/uitour/docs/UITour-lib.rst
browser/components/uitour/docs/index.rst
browser/components/uitour/moz.build
browser/docs/index.rst
tools/docs/conf.py
--- a/browser/components/uitour/UITour-lib.js
+++ b/browser/components/uitour/UITour-lib.js
@@ -14,20 +14,19 @@ if (typeof Mozilla == "undefined") {
 
   // create namespace
   if (typeof Mozilla.UITour == "undefined") {
     /**
      * Library that exposes an event-based Web API for communicating with the
      * desktop browser chrome. It can be used for tasks such as opening menu
      * panels and highlighting the position of buttons in the toolbar.
      *
-     * <p>For security/privacy reasons `Mozilla.UITour` will only work on a list of allowed
+     * For security/privacy reasons `Mozilla.UITour` will only work on a list of allowed
      * secure origins. The list of allowed origins can be found in
-     * {@link https://dxr.mozilla.org/mozilla-central/source/browser/app/permissions|
-     * browser/app/permissions}.</p>
+     * https://searchfox.org/mozilla-central/source/browser/app/permissions.
      *
      * @since 29
      * @namespace
      */
     Mozilla.UITour = {};
   }
 
   function _sendEvent(action, data) {
@@ -83,53 +82,61 @@ if (typeof Mozilla == "undefined") {
 
   Mozilla.UITour.CONFIGNAME_SYNC = "sync";
   Mozilla.UITour.CONFIGNAME_AVAILABLETARGETS = "availableTargets";
 
   /**
    * @typedef {String} Mozilla.UITour.Target
    *
    * @summary Not all targets are available at all times because they may not be visible
-   * or UITour doesn't not how to automatically make them visible. Use
-   * <code>`Mozilla.UITour.getConfiguration('availableTargets', callback)`</code> to determine
-   * which ones are available at a given time.
+   * or UITour doesn't not how to automatically make them visible. Use the
+   * following to determine which ones are available at a given time::
+   *
+   * .. code-block:: javascript
+   *
+   *    Mozilla.UITour.getConfiguration('availableTargets', callback)
+   *
    * @see Mozilla.UITour.getConfiguration
    * @see Mozilla.UITour.showHighlight
    * @see Mozilla.UITour.showInfo
    *
-   * @description Valid values:<ul>
-   * <li>accountStatus
-   * <li>addons
-   * <li>appMenu
-   * <li>backForward
-   * <li>bookmarks
-   * <li>customize
-   * <li>devtools
-   * <li>forget
-   * <li>help
-   * <li>home
-   * <li>library
-   * <li>pageActionButton
-   * <li>pageAction-bookmark
-   * <li>pageAction-copyURL
-   * <li>pageAction-emailLink
-   * <li>pageAction-sendToDevice
-   * <li>pocket
-   * <li>privateWindow
-   * <li>quit
-   * <li>readerMode-urlBar
-   * <li>screenshots
-   * <li>search
-   * <li>searchIcon
-   * <li>selectedTabIcon
-   * <li>urlbar
-   * </ul>
+   * @description Valid values:
+   *
+   * - accountStatus
+   * - addons
+   * - appMenu
+   * - backForward
+   * - bookmarks
+   * - customize
+   * - devtools
+   * - forget
+   * - help
+   * - home
+   * - library
+   * - pageActionButton
+   * - pageAction-bookmark
+   * - pageAction-copyURL
+   * - pageAction-emailLink
+   * - pageAction-sendToDevice
+   * - pocket
+   * - privateWindow
+   * - quit
+   * - readerMode-urlBar
+   * - screenshots
+   * - search
+   * - searchIcon
+   * - selectedTabIcon
+   * - urlbar
    *
    * Generate using the following in the Browser Console:
-   * <code>`[...UITour.targets.keys()].join("\n* &lt;li&gt;")`</code>
+   *
+   * .. code-block:: javascript
+   *
+   *    [...UITour.targets.keys()].join("\n* - ")
+   *
    */
 
   /**
    * Ensure the browser is ready to handle this document as a tour.
    *
    * @param {Function} [callback] Callback to call if UITour is working for the document.
    * @since 35
    */
@@ -162,17 +169,17 @@ if (typeof Mozilla == "undefined") {
         "mozUITourNotification",
         _notificationListener
       );
     }
   };
 
   /**
    * Register an identifier to use in
-   * {@link https://wiki.mozilla.org/Telemetry|Telemetry}. `pageID` must be a
+   * `Telemetry <https://wiki.mozilla.org/Telemetry>`_. `pageID` must be a
    * string unique to the page/tour.
    *
    * @example
    * Mozilla.UITour.registerPageID('firstrun-page-firefox-29');
    *
    * @param {string} pageID Unique identifier for the page/tour.
    * @memberof Mozilla.UITour
    */
@@ -181,25 +188,29 @@ if (typeof Mozilla == "undefined") {
       pageID,
     });
   };
 
   /**
    * @typedef {String} Mozilla.UITour.HighlightEffect
    *
    * Specifies the effect/animation to use when highlighting UI elements.
-   * @description Valid values:<ul>
-   * <li>random
-   * <li>wobble
-   * <li>zoom
-   * <li>color
-   * </ul>
+   * @description Valid values:
+   *
+   * - random
+   * - wobble
+   * - zoom
+   * - color
    *
    * Generate using the following in the Browser Console:
-   * <code>[...UITour.highlightEffects].join("\n* &lt;li&gt;")</code>
+   *
+   * .. code-block:: javascript
+   *
+   *    [...UITour.highlightEffects].join("\n* - ")
+   *
    * @see Mozilla.UITour.showHighlight
    */
 
   /**
    * Visually highlight a UI widget.
    *
    * @see Mozilla.UITour.hideHighlight
    * @example Mozilla.UITour.showHighlight('appMenu', 'wobble');
@@ -306,21 +317,21 @@ if (typeof Mozilla == "undefined") {
    * @see Mozilla.UITour.showInfo
    */
   Mozilla.UITour.hideInfo = function() {
     _sendEvent("hideInfo");
   };
 
   /**
    * @typedef {String} Mozilla.UITour.MenuName
-   * Valid values:<ul>
-   * <li>appMenu
-   * <li>bookmarks
-   * <li>pocket
-   * </ul>
+   * Valid values:
+   *
+   * - appMenu
+   * - bookmarks
+   * - pocket
    *
    * @see Mozilla.UITour.showMenu
    * @see Mozilla.UITour.hideMenu
    * @see Mozilla.UITour.openSearchPanel
    */
 
   /**
    * Open the named application menu.
@@ -374,44 +385,47 @@ if (typeof Mozilla == "undefined") {
    * @since 70
    */
   Mozilla.UITour.showProtectionReport = function() {
     _sendEvent("showProtectionReport");
   };
 
   /**
    * @typedef Mozilla.UITour.ConfigurationName
-   * @description Valid values:<ul>
-   * <li>{@link Mozilla.UITour.Configuration.AppInfo|appinfo}</li>
-   * <li>{@link Mozilla.UITour.Configuration.CanReset|canReset}</li>
-   * <li>{@link Mozilla.UITour.Configuration.AvailableTargets|availableTargets}</li>
-   * <li>{@link Mozilla.UITour.Configuration.Search|search}</li>
-   * <li>{@link Mozilla.UITour.Configuration.Search|selectedSearchEngine}
-   * - DEPRECATED, use 'search'</li>
-   * <li>{@link Mozilla.UITour.Configuration.Sync|sync}</li>
-   * - DEPRECATED, use 'fxa'</li>
-   * <li>{@link Mozilla.UITour.Configuration.FxA|fxa}</li>
-   * </ul>
+   * @description Valid values:
+   *
+   * - :js:func:`appinfo <Mozilla.UITour.Configuration.AppInfo>`
+   * - :js:func:`canReset <Mozilla.UITour.Configuration.CanReset>`
+   * - :js:func:`availableTargets <Mozilla.UITour.Configuration.AvailableTargets>`
+   * - :js:func:`search <Mozilla.UITour.Configuration.Search>`
+   * - :js:func:`selectedSearchEngine <Mozilla.UITour.Configuration.Search>`
+   *   DEPRECATED, use 'search'
+   * - :js:func:`sync <Mozilla.UITour.Configuration.Sync>`
+   *   DEPRECATED, use 'fxa'
+   * - :js:func:`fxa <Mozilla.UITour.Configuration.FxA>`
+   *
    */
 
   /**
    * @namespace Mozilla.UITour.Configuration
    * @see Mozilla.UITour.getConfiguration
    * @see Mozilla.UITour.ConfigurationName
    */
 
   /**
-   * Indicate whether a user can refresh their Firefox profile via {@link Mozilla.UITour.resetFirefox}.
-   * @typedef {Boolean} Mozilla.UITour.Configuration.CanReset
+   * @typedef {boolean} Mozilla.UITour.Configuration.CanReset
+   *
+   * @description Indicate whether a user can refresh their Firefox profile via :js:func:`Mozilla.UITour.resetFirefox`.
+   *
    * @see Mozilla.UITour.resetFirefox
    * @since 48
    */
 
   /**
-   * @typedef {Object} Mozilla.UITour.Configuration.AppInfo
+   * @typedef {object} Mozilla.UITour.Configuration.AppInfo
    * @property {Boolean} canSetDefaultBrowserInBackground - Whether the application can be set as
    *                                                        the default browser in the background
    *                                                        without user interaction.
    * @property {Boolean} defaultBrowser - Whether the application is the default browser. Since Fx40.
    * @property {String} defaultUpdateChannel - Update channel e.g. 'release', 'beta', 'aurora',
    *                                           'nightly', 'default'
    *                                           (self-built or automated testing builds)
    * @property {String} distribution - Contains the distributionId property. This value will be
@@ -475,47 +489,45 @@ if (typeof Mozilla == "undefined") {
    *    here. Indeed, what services, and in what circumstances they may appear
    *    here in the future is largely TBD.
    * @since 71
    */
 
   /**
    * Information about clients attached to the account.
    * An object. The key is a string ID of the attached service. A list of attached
-   *    service IDs can be found at
-   *    {@link https://docs.telemetry.mozilla.org/datasets/fxa_metrics/attribution.html#service-attribution|
-   *     on our telemetry documentation site}
-   * The value is a {@link Mozilla.UITour.Configuration.AccountService}
-   * @typedef {Object.<string, Mozilla.UITour.Configuration.AccountService>} Mozilla.UITour.Configuration.AccountService
+   * service IDs can be found
+   * `on our telemetry documentation site <https://docs.telemetry.mozilla.org/datasets/fxa_metrics/attribution.html#service-attribution>`_.
+   * The value is a :js:func:`Mozilla.UITour.Configuration.AccountService`
+   * @typedef {Object.<string, Mozilla.UITour.Configuration.AccountService>} Mozilla.UITour.Configuration.AccountServices
    * @since 71
    */
 
   /**
    * Information about an account service
    * @typedef {Object} Mozilla.UITour.Configuration.AccountService
    * @property {String} id - The service ID. A list of attached
-   *    service IDs can be found at
-   *    {@link https://docs.telemetry.mozilla.org/datasets/fxa_metrics/attribution.html#service-attribution|
-   *     on our telemetry documentation site}
+   * service IDs can be found
+   * `on our telemetry documentation site <https://docs.telemetry.mozilla.org/datasets/fxa_metrics/attribution.html#service-attribution>`_.
    * @property {Number} lastAccessedWeeksAgo - How many weeks ago the service
    *    was accessed by this account.
    * @since 71
    */
 
   /**
    * Information about a services attached to the browser. All properties are
    * optional and only exist if the service is enabled.
    *
    * @typedef {Object} Mozilla.UITour.Configuration.BrowserServices
    * @property {Mozilla.UITour.Configuration.Sync} sync - If sync is configured
    * @since 71
    */
 
   /**
-   * Array of UI {@link Mozilla.UITour.Target|Targets} currently available to be annotated.
+   * Array of UI :js:func:`Targets <Mozilla.UITour.Target>` currently available to be annotated.
    * @typedef {Mozilla.UITour.Target[]} Mozilla.UITour.Configuration.AvailableTargets
    */
 
   /**
    * Retrieve some information about the application/profile.
    *
    * @param {Mozilla.UITour.ConfigurationName} configName - Name of configuration to retrieve
    * @param {Function} callback - Called with one argument containing the value of the configuration.
@@ -525,20 +537,20 @@ if (typeof Mozilla == "undefined") {
       callbackID: _waitForCallback(callback),
       configuration: configName,
     });
   };
 
   /**
    * Set some value or take some action.
    *
-   * <p><strong>Valid configuration names:</strong><dl>
-   * <dt>defaultBrowser</dt>
-   * <dd>Try to set the application as the default web browser. Since Fx40</dd>
-   * </dl></p>
+   * Valid configuration names:
+   *
+   * defaultBrowser
+   *   Try to set the application as the default web browser. Since Fx40
    *
    * @param {String} configName - Configuration name to set (e.g. "defaultBrowser")
    * @param {String|Number|Boolean} [configValue] - Not currently used
    *
    * @since 40
    * @example
    * Mozilla.UITour.setConfiguration('defaultBrowser');
    */
@@ -550,17 +562,17 @@ if (typeof Mozilla == "undefined") {
   };
 
   /**
    * Request the browser open the Firefox Accounts page.
    *
    * @param {Object} extraURLCampaignParams - An object containing additional
    * parameters for the URL opened by the browser for reasons of promotional
    * campaign tracking. Each attribute of the object must have a name that
-   * is a string, begins with "utm_" and contains only only alphanumeric
+   * is a string, begins with `utm_` and contains only only alphanumeric
    * characters, dashes or underscores. The values may be any string and will
    * automatically be encoded.
    * @param {String} email - A string containing the default email account
    * for the URL opened by the browser.
    * @since 31, 47 for `extraURLCampaignParams`
    * @example
    * // Will open https://accounts.firefox.com/signup?entrypoint=uitour
    * Mozilla.UITour.showFirefoxAccounts();
@@ -584,17 +596,17 @@ if (typeof Mozilla == "undefined") {
   };
 
   /**
    * Request the browser open the "Connect Another Device" Firefox Accounts page.
    *
    * @param {Object} extraURLCampaignParams - An object containing additional
    * parameters for the URL opened by the browser for reasons of promotional
    * campaign tracking. Each attribute of the object must have a name that
-   * is a string, begins with "utm_" and contains only only alphanumeric
+   * is a string, begins with `utm_` and contains only only alphanumeric
    * characters, dashes or underscores. The values may be any string and will
    * automatically be encoded.
    * @since 59
    * @example
    * // Will open https://accounts.firefox.com/connect_another_device?entrypoint=uitour
    * Mozilla.UITour.showConnectAnotherDevice();
    * @example
    * // Will open:
@@ -639,17 +651,17 @@ if (typeof Mozilla == "undefined") {
       name,
       callbackID: _waitForCallback(callback),
     });
   };
 
   /**
    * Set the specified search engine as the user-set default.
    *
-   * @see {@link https://dxr.mozilla.org/mozilla-release/source/browser/locales/search/list.json}
+   * See https://searchfox.org/mozilla-release/source/browser/locales/search/list.json
    *
    * @param {String} identifier - Identifier of the engine (e.g. 'yahoo').
    * @see Mozilla.UITour.Configuration.Search
    * @since 34
    */
   Mozilla.UITour.setDefaultSearchEngine = function(identifier) {
     _sendEvent("setDefaultSearchEngine", {
       identifier,
@@ -738,27 +750,26 @@ if (typeof Mozilla == "undefined") {
   Mozilla.UITour.toggleReaderMode = function() {
     _sendEvent("toggleReaderMode");
   };
 
   /**
    * @param {String} pane - Pane to open/switch the preferences to.
    * Valid values match fragments on about:preferences and are subject to change e.g.:
    *
-   * <ul>
-   * For the Preferences
-   * <li>general
-   * <li>applications
-   * <li>sync
-   * <li>privacy
-   * <li>advanced
-   * </ul>
+   * For the Preferences:
    *
-   * To open to the options of sending telemetry, health report, crach reports,
-   * that is, the privcacy pane > reports on the preferences.
+   * - general
+   * - applications
+   * - sync
+   * - privacy
+   * - advanced
+   *
+   * To open to the options of sending telemetry, health report, crash reports,
+   * that is, the privacy pane > reports on the preferences.
    * Please call `Mozilla.UITour.openPreferences("privacy-reports")`.
    * UITour would do route mapping automatically.
    *
    * @since 42
    */
   Mozilla.UITour.openPreferences = function(pane) {
     _sendEvent("openPreferences", {
       pane,
new file mode 100644
--- /dev/null
+++ b/browser/components/uitour/docs/UITour-lib.rst
@@ -0,0 +1,11 @@
+UITour library API
+==================
+
+This is the web API provided by the library UITour-lib.js for use by web content with appropriate permissions.
+
+.. js:autoclass:: Mozilla.UITour
+   :members:
+   :exclude-members: Configuration
+
+.. js:autoclass:: Mozilla.UITour.Configuration
+   :members:
new file mode 100644
--- /dev/null
+++ b/browser/components/uitour/docs/index.rst
@@ -0,0 +1,10 @@
+UITour
+======
+
+.. toctree::
+   UITour-lib
+
+.. js:autoclass:: Mozilla.UITour
+   :members: none
+
+
--- a/browser/components/uitour/moz.build
+++ b/browser/components/uitour/moz.build
@@ -6,10 +6,12 @@ EXTRA_JS_MODULES += [
     'UITour.jsm',
     'UITourChild.jsm',
 ]
 
 BROWSER_CHROME_MANIFESTS += [
     'test/browser.ini',
 ]
 
+SPHINX_TREES['docs'] = 'docs'
+
 with Files('**'):
     BUG_COMPONENT = ('Firefox', 'Tours')
--- a/browser/docs/index.rst
+++ b/browser/docs/index.rst
@@ -11,9 +11,11 @@ This is the nascent documentation of the
    BrowserUsageTelemetry
    components/enterprisepolicies/docs/index
    extensions/formautofill/docs/index
    components/newtab/docs/index
    installer/windows/installer/index
    base/sslerrorreport/index
    base/tabbrowser/index
    touchbar/index
+   components/uitour/docs/index
    components/payments/docs/index
+
--- a/tools/docs/conf.py
+++ b/tools/docs/conf.py
@@ -41,16 +41,17 @@ extensions = [
     'sphinxcontrib.mermaid',
     'recommonmark',
 ]
 
 # JSDoc must run successfully for dirs specified, so running
 # tree-wide (the default) will not work currently.
 js_source_path = [
     'browser/components/extensions',
+    'browser/components/uitour',
     'testing/marionette',
     'toolkit/components/extensions',
     'toolkit/components/extensions/parent',
     'toolkit/components/featuregates',
     'toolkit/mozapps/extensions',
 ]
 root_for_relative_js_paths = '.'
 jsdoc_config_path = 'jsdoc.json'