[FIX] *: RST cleanup

RST cleanup to comply with the RST guidelines. This is required so we can use "make test", as there are currently hundreds of errors. For now, it is unusable because of the oldest code in this repo. closes odoo/documentation#3581 Signed-off-by: Castillo Jonathan (jcs) <jcs@odoo.com>
2023-02-13 15:50:13 +00:00
parent 18b000602b
commit 17319f92b2
67 changed files with 707 additions and 716 deletions
@@ -280,12 +280,13 @@ using the view in the kanban arch (a specific example is the helpdesk dashboard)
    need to have a valid arch field.

 Promises and asynchronous code
-===============================
+==============================

 For a very good and complete introduction to promises, please read this excellent article https://github.com/getify/You-Dont-Know-JS/blob/1st-ed/async%20%26%20performance/ch3.md

 Creating new Promises
-----------------------
+---------------------
+
 - turn a constant into a promise
    There are 2 static functions on Promise that create a resolved or rejected promise based on a constant:

@@ -383,6 +384,7 @@ Creating new Promises

 Waiting for Promises
 --------------------
+
 - waiting for a number of Promises
        if you have multiple promises that all need to be waited, you can convert them into a single promise that will be resolved when all the promises are resolved using Promise.all(arrayOfPromises).

@@ -486,7 +488,7 @@ Error handling


 Testing asynchronous code
--------------------------
+-------------------------

 - using promises in tests
        In the tests code, we support the latest version of Javascript, including primitives like `async` and `await`. This makes using and waiting for promises very easy.
@@ -263,7 +263,7 @@ within the same Odoo addon.
 .. _frontend/modules/odoo_module:

 Odoo Module System
-===================
+==================

 Odoo has defined a small module system (located in the file
 :file:`addons/web/static/src/js/boot.js`, which needs to be loaded first). The Odoo
@@ -371,7 +371,7 @@ If an error happens, it will be logged (in debug mode) in the console:
  Modules who depend on a missing or a failed module

 Asynchronous modules
---------------------
+--------------------

 It can happen that a module needs to perform some work before it is ready.  For
 example, it could do an rpc to load some data.  In that case, the module can
@@ -1,11 +1,10 @@
-
 .. highlight:: javascript

 .. default-domain:: js

-=====================
+====================
 Javascript Reference
-=====================
+====================

 This document presents the Odoo Javascript framework. This
 framework is not a large application in term of lines of code, but it is quite
@@ -15,7 +14,7 @@ records in the database.  It is even possible to use the web client to modify
 the interface of the web client.

 Overview
-=========
+========

 The Javascript framework is designed to work with three main use cases:

@@ -53,7 +52,7 @@ action manager) actually creates and destroys many sub components. The state is
 highly dynamic, and each widget could be destroyed at any time.

 Overview of web client JS code
-------------------------------------
+------------------------------

 Here, we give a very quick overview on the web client code, in
 the *web/static/src/js* addon. Note that it is deliberately not exhaustive.
@@ -105,7 +104,7 @@ are a few things you can try to solve the issue:


 Loading Javascript Code
-========================
+=======================

 Large applications are usually broken up into smaller files, that need to be
 connected together.  Some file may need to use some part of code defined in
@@ -146,8 +145,6 @@ not the primary way to write javascript code.
 .. note::
    Native javascript modules are the primary way to define javascript code.

-
-
 Class System
 ============

@@ -204,7 +201,6 @@ framework will secretly rebind a special method: *_super* to the currently
 called method.  This allows us to use *this._super* whenever we need to call a
 parent method.

-
 .. code-block:: javascript

    var Animal = require('web.Animal');
@@ -248,7 +244,6 @@ of them in the new class.
 In this example, the *Hamster* class is a subclass of Animal, but it also mix
 the DanceMixin in.

-
 Patching an existing class
 --------------------------

@@ -273,7 +268,6 @@ the way Odoo is structured, it is sometimes necessary in one addon to modify
 the behavior of a widget/class defined in another addon.  Note that it will
 modify all instances of the class, even if they have already been created.

-
 Widgets
 =======

@@ -524,7 +518,6 @@ Widget API
    :param Element element: a DOM element or jQuery object to set as
                            the widget's DOM root

-
 Inserting a widget in the DOM
 -----------------------------

@@ -558,7 +551,7 @@ and are charged with three tasks:
 * starting the widget, and returning the result of starting it

 Widget Guidelines
----------------------
+-----------------

 * Identifiers (``id`` attribute) should be avoided. In generic applications
  and modules, ``id`` limits the re-usability of components and tends to make
@@ -668,7 +661,6 @@ in order to make the web client slightly lighter.  In that case, we can use the
 With this, the *Counter* widget will load the xmlDependencies files in its
 *willStart* method, so the template will be ready when the rendering is performed.

-
 Event system
 ============

@@ -760,9 +752,8 @@ The previous example can be updated to use the custom event system:

    ... this.trigger_up('valuechange', {value: someValue});

-
 Registries
-===========
+==========

 A common need in the Odoo ecosystem is to extend/change the behaviour of the
 base system from the outside (by installing an application, i.e. a different
@@ -799,7 +790,6 @@ action registry
  action.  In version 11, each value should simply be a subclass of *Widget*.
  However, in version 12, the values are required to be *AbstractAction*.

-
 Communication between widgets
 =============================

@@ -867,7 +857,6 @@ Cross component
          },
      });

-
    In this example, we use the bus exported by *web.core*, but this is not
    required. A bus could be created for a specific purpose.

@@ -884,7 +873,7 @@ events, these events bubble up to a service provider, which will ask a service
 to perform a task, then maybe return an answer.

 Service
--------
+-------

 A service is an instance of the *AbstractService* class.  It basically only has
 a name and a few methods.  Its job is to perform some work, typically something
@@ -916,7 +905,6 @@ dispatch the custom events.  In the *backend* (web client), this is done by the
 main web client instance. Note that the code for the service provider comes from
 the *ServiceProviderMixin*.

-
 Widget
 ------

@@ -975,7 +963,7 @@ may need to directly call a controller (available on some route).
    });

 Notifications
-==============
+=============

 The Odoo framework has a standard way to communicate various information to the
 user: notifications, which are displayed on the top right of the user interface.
@@ -1010,9 +998,9 @@ The notification system in Odoo is designed with the following components:

 - an helper function in *ServiceMixin*: *displayNotification*

-
 Displaying a notification
 -------------------------
+
 The most common way to display a notification is by using the method that come
 from the *ServiceMixin*:

@@ -1098,7 +1086,6 @@ the class variable SystrayMenu.items.

    SystrayMenu.Items.push(MySystrayWidget);

-
 Ordering
 --------

@@ -1112,7 +1099,6 @@ left).

    MySystrayWidget.prototype.sequence = 100;

-
 Translation management
 ======================

@@ -1207,7 +1193,7 @@ client for everyone), and for data which is required early in the initialization
 process.

 Views
-======
+=====

 The word 'view' has more than one meaning. This section is about the design of
 the javascript code of the views, not the structure of the *arch* or anything
@@ -1216,7 +1202,6 @@ else.
 In 2017, Odoo replaced the previous view code with a new architecture.  The
 main need was to separate the rendering logic from the model logic.

-
 Views (in a generic sense) are now described with  4 pieces: a View, a
 Controller, a Renderer and a Model.  The API of these 4 pieces is described in
 the AbstractView, AbstractController, AbstractRenderer and AbstractModel classes.
@@ -2090,6 +2075,7 @@ reference (FieldReference)

 Widgets
 -------
+
 week_days (WeekDays)
  This field displays a list of checkboxes for week days, 1 checkbox for each day
  and allow the user to select a subset of the choices.
@@ -2162,7 +2148,6 @@ Registering the client action:
          <field name="tag">my-custom-action</field>
      </record>

-
 Using the control panel
 -----------------------

@@ -1,9 +1,8 @@
-
 .. _reference/mobile:

-==================
+=================
 Mobile JavaScript
-==================
+=================

 Introduction
 ============
@@ -11,15 +10,16 @@ Introduction
 In Odoo 10.0 we released a mobile app which allows you to access all **Odoo apps**
 (even your customized modules).

-The application is a combination of **Odoo Web** and **Native Mobile
-components**. In other words it is a Odoo Web instance loaded inside a native, mobile, WebView container.
+The application is a combination of **Odoo Web** and **Native Mobile components**. In other words it
+is a Odoo Web instance loaded inside a native, mobile, WebView container.

 This page documents how you can access mobile native components like Camera,
 Vibration, Notification and Toast through Odoo Web (via JavaScript). For this, you
 do not need to be a mobile developer, if you know Odoo JavaScript API you can
 access all available mobile features.

-.. warning:: These features work with **Odoo Enterprise 10.0+** only
+.. warning::
+   These features work with **Odoo Enterprise 10.0+** only

 How does it work?
 =================
@@ -64,7 +64,7 @@ Methods
   a data JSON dictionary

 Show Toast in device
-.....................
+~~~~~~~~~~~~~~~~~~~~

 .. js:function:: showToast

@@ -80,10 +80,8 @@ remains visible and interactive.

 .. image:: mobile/toast.png

-
 Vibrating device
-................
-
+~~~~~~~~~~~~~~~~

 .. js:function:: vibrate

@@ -97,7 +95,7 @@ Vibrate mobile device with given duration.
    mobile.methods.vibrate({'duration': 100});

 Show snackbar with action
-.........................
+~~~~~~~~~~~~~~~~~~~~~~~~~

 .. js:function:: showSnackBar

@@ -122,7 +120,7 @@ displayed at a time.
 .. image:: mobile/snackbar.png

 Showing notification
-.....................
+~~~~~~~~~~~~~~~~~~~~

 .. js:function:: showNotification

@@ -143,7 +141,7 @@ view at any time.


 Create contact in device
-.........................
+~~~~~~~~~~~~~~~~~~~~~~~~

 .. js:function:: addContact

@@ -176,7 +174,7 @@ Create a new device contact with the given contact details.
 .. image:: mobile/mobile_contact_create.png

 Scanning barcodes
-..................
+~~~~~~~~~~~~~~~~~

 .. js:function:: scanBarcode

@@ -198,7 +196,7 @@ The barcode API can read the following barcode formats:
    });

 Switching account in device
-...........................
+~~~~~~~~~~~~~~~~~~~~~~~~~~~

 .. js:function:: switchAccount

@@ -487,7 +487,7 @@ open themselves on mouse hover, without the need for a click.


 Example: Direct Siblings Dropdown
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 When one dropdown toggler is clicked (**File** , **Edit** or **About**), the
 others will open themselves on hover.
@@ -257,9 +257,8 @@ exists in 3 different forms:
 setting variables
 =================

-QWeb allows creating variables from within the template, to memoize a
-computation (to use it multiple times), give a piece of data a clearer name,
-...
+QWeb allows creating variables from within the template, to memoize a computation (to use it
+multiple times), give a piece of data a clearer name, ...

 This is done via the ``set`` directive, which takes the name of the variable
 to create. The value to set can be provided in two ways:
@@ -374,7 +373,7 @@ templates:
  will not strip that information from safe content.

 Creating safe content using :class:`~markupsafe.Markup`
-'''''''''''''''''''''''''''''''''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 See the official documentation for explanations, but the big advantage of
 :class:`~markupsafe.Markup` is that it's a very rich type overrinding
@@ -471,12 +470,12 @@ Exclusive directives
 --------------------

 Asset bundles
-'''''''''''''
+~~~~~~~~~~~~~

 .. todo:: have fme write these up because I've no idea how they work

 "smart records" fields formatting
-'''''''''''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 The ``t-field`` directive can only be used when performing field access
 (``a.b``) on a "smart" record (result of the ``browse`` method). It is able
@@ -511,7 +510,7 @@ are also done only once.
 The content can only use the root values.

 Why and when to use ``t-cache``?
-''''''''''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 This directive is used to speed up the rendering, by caching parts of the final
 document, which may save queries to the database.  However, it should be used
@@ -542,7 +541,7 @@ the template, the rendering of what comes after it could be different than if
 there was no ``t-cache`` directive.

 What if there is a ``t-cache`` inside a ``t-cache``?
-''''''''''''''''''''''''''''''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 The parts are cached. Each containing only the string corresponding to its
 rendering. Thus, the ``t-cache`` inside will probably be read less often, its
@@ -550,7 +549,7 @@ cache key will not necessarily be used. If this must be the case, then you may
 need to add a ``t-nocache`` (on the same node or a parent).

 What is ``t-nocache`` used for?
-'''''''''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 If you want to cache part of a template with ``t-cache`` but a small piece must
 remain dynamic and be evaluated at cache times. However, the part in
@@ -562,7 +561,7 @@ investigate). However, in the menu, we want the ecommerce cart to be always up
 to date. So there is a ``t-nocache`` to keep this part dynamic.

 The base of ``t-cache``
-'''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~

 The ``t-cache`` directive allows you to store the rendered result of a template.
 The **key expression** (eg 42: ``t-cache="42"``) will be evaluated as a python
@@ -587,7 +586,7 @@ condition. And if a module modifies the record, the write_date being modified,
 the cached value is discarded.

 ``t-cache`` and scoped values (``t-set``, ``t-foreach``...)
-'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Values in ``t-cache`` are scoped, this involves a change in behavior between
 having or not having ``t-cache`` on one of the parent nodes. Don't forget to
@@ -626,7 +625,7 @@ Will render::


 The base of ``t-nocache``
-'''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~~

 The template part contained in a node with a ``t-nocache`` attribute is not
 cached. This content is therefore **dynamic** and is rendered systematically.
@@ -655,7 +654,7 @@ Here the ``<i>`` tag that contains the container will always be rendered. While
 the rest is as a single string in the cache.

 ``t-nocache`` and scoped root values (``t-set``, ``t-foreach``...)
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 The contents of the ``t-nocache`` tag can be used for documentation and to
 explain why the directive is added.
@@ -697,7 +696,7 @@ the rest is as a single string in the cache. The counter is not updated by the
 ``t-set`` out of the ``t-nocache``

 ``t-nocache-*`` add some primitive values in the cache
-'''''''''''''''''''''''''''''''''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 In order to be able to use values generated in the template, it is possible to
 cache them. The directive is used as ``t-nocache-*="expr"`` where ``*`` is the
@@ -725,7 +724,7 @@ Helpers
 -------

 Request-based
-'''''''''''''
+~~~~~~~~~~~~~

 Most Python-side uses of QWeb are in controllers (and during HTTP requests),
 in which case templates stored in the database (as
@@ -742,7 +741,7 @@ This automatically creates a :class:`~odoo.http.Response` object which can
 be returned from the controller (or further customized to suit).

 View-based
-''''''''''
+~~~~~~~~~~

 At a deeper level than the previous helper is the ``_render`` method on
 ``ir.qweb`` (use the datable) and the public module method ``render``
@@ -808,7 +807,7 @@ Exclusive directives
 --------------------

 Defining templates
-''''''''''''''''''
+~~~~~~~~~~~~~~~~~~

 The ``t-name`` directive can only be placed at the top-level of a template
 file (direct children to the document root)::
@@ -829,7 +828,7 @@ names to indicate hierarchical relationships.
 .. _reference/qweb/template_inheritance:

 Template inheritance
-''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~

 Template inheritance is used to either:
 - Alter existing templates in-place, e.g. to add information to templates
@@ -866,7 +865,7 @@ Extension inheritance (in-place transformation)::
    </t>

 Old inheritance mechanism (deprecated)
-''''''''''''''''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Template inheritance is performed via the ``t-extend`` directive which takes
 the name of the template to alter as parameter.
@@ -673,8 +673,7 @@ When a rpc fails, then:

 * the promise representing the rpc is rejected, so the calling code will crash,
  unless it handles the situation
-*
-  an event ``RPC_ERROR`` is triggered on the main application bus. The event payload
+* an event ``RPC_ERROR`` is triggered on the main application bus. The event payload
  contains a description of the cause of the error:

  If it is a server error (the server code threw an exception). In that case