[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
@@ -1,6 +1,6 @@
-==============================
+=============================
 Chapter 2: Odoo web framework
-==============================
+=============================

 In the previous chapter, we learned to use Owl framework and its different concepts. We can now
 learn how to use the Odoo JavaScript framework which is is built on top of Owl.
@@ -287,7 +287,7 @@ For JavaScript, we use ESLint and you can find a `configuration file example her
 <https://github.com/odoo/odoo/wiki/Javascript-coding-guidelines#use-a-linter>`_.

 Administrator tools for PostgreSQL
-----------------------------------
+----------------------------------

 You can manage your PostgreSQL databases using the command line as demonstrated earlier or using
 a GUI application such as `pgAdmin <https://www.pgadmin.org/download/pgadmin-4-apt/>`_ or `DBeaver
@@ -376,7 +376,5 @@ Here is a list of commands:

   Quit the debugger. The program being executed is aborted.

----
-
 Now that your server is running, it's time to start :ref:`writing your own application
 <howto/rdtraining/03_newapp>`!
@@ -205,7 +205,7 @@ template is passed more than one record, it can produce one PDF report for all t
 Using the Print menu in the list view with multiple records selected will demonstrate this.

 Make a Report
---------------
+-------------

 Finally, you now know where to create your files and how the content of the files should look. Happy report making!

@@ -105,6 +105,7 @@ these options. A full example to reference while doing the exercises in this sec

 Data
 ----
+
 To fully enjoy our dashboard view, we will need good test data to populate it. Test data will
 allow us to check that the resulting look and statistics are correct. It is a good idea to test
 with data that will cover most or all of your expected use cases, but is also easy to verify with
@@ -130,6 +131,7 @@ data after you write your dashboard code and then test that your view is working

 Aggregations
 ------------
+
 Building a dashboard view is very similar to what you have previously done in
 :ref:`howto/rdtraining/07_basicviews`. For the dashboard view, we use the `dashboard` root element
 and choose from its possible tags (see all the possibilities and their attributes in the
@@ -164,6 +166,7 @@ covered in :ref:`howto/rdtraining/06_firstui`). Now let's make some dashboards!

 Pie Charts
 ----------
+
 Adding pie charts to dashboards is a piece of cake using the `<widget>` element. An example is:

 .. code-block:: xml
@@ -192,6 +195,7 @@ the ``title`` for the pie chart, and that we're grouping it by property type.

 Subviews
 --------
+
 Similar to how we can use the list view within the form view (we saw this automatically happen for
 One2many relationships in :ref:`howto/rdtraining/08_relations`), we can add other views within our
 dashboard view. The most commonly added are the pivot and graph views, but the cohort view is
@@ -248,6 +252,7 @@ model clean of unnecessary fields.

 Model
 -----
+
 We will start with the more difficult part: our special report model. This file starts the same as
 any other model, except that we add 2 attributes ``_auto`` and ``_rec_name``::

@@ -318,6 +323,7 @@ or use alias names that match.

 View
 ----
+
 Now that we have our model, we can make its dashboard view. There is no difference in how it's made,
 except that its file is in the ``report`` folder. Since it is a new model not linked to
 any other model, we will also have to add a new menuitem to view our dashboard. Typically, SQL views
@@ -334,6 +340,7 @@ remember how to add a ``menuitem``? If not, revisit :ref:`howto/rdtraining/06_fi

 Extra Tips
 ----------
+
 **Tip 1** A common mistake in SQL views is not considering the duplication of certain data
 due to table JOINs. For example, in our **Goal**, we have a pie chart of the offers' property types.
 We may be tempted to add a similar pie chart with a domain to only include canceled properties,
@@ -28,12 +28,9 @@ From common CMS to Odoo
 -----------------------

 .. note::
-
   If you always think and work in the same way, you’ll probably get the same results. If you want something completely new,  then try something different.

-..
-
-    Where is my header.php file?
+**Where is my header.php file?**

 This is usually the first question from a web designer used to working with Wordpress or Joomla and coming to Odoo for the first time.

@@ -183,7 +180,7 @@ Keep reading the tutorial to learn to how properly extend it with your own code.


 Create a theme module
-======================
+=====================

 Odoo’s themes are packaged like modules. Even if you are designing a very simple website for your company or client, you need to package the theme like an Odoo module.

@@ -808,7 +805,7 @@ Options allow publishers to edit a snippet’s appearance using the Website Buil
 Using Website Builder functionalities, you can create snippet options easily and automatically add them to the UI.

 Options group properties
-------------------------
+------------------------

 Options are wrapped in groups. Groups can have properties that define how the included options will interact with the user interface.

@@ -822,7 +819,7 @@ Options are wrapped in groups. Groups can have properties that define how the in
  Defines the list of elements that the snippet can be dropped beside.

 Default option methods
-----------------------
+----------------------

 Options apply standard CSS classes to the snippet. Depending on the method that you choose, the UI will behave differently.

@@ -1100,11 +1097,12 @@ Describe your page
 ------------------

 Define keywords
-'''''''''''''''
+~~~~~~~~~~~~~~~
+
 You should use appropriate, relevant keywords and synonyms for those keywords. You can define them for each page using the built-in “Promote” function found in the bar at the top.

 Define a title and a description
-''''''''''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Define them using the “Promote” function. Keep your page titles short and include the main keyword phrase for the page.
 Good titles evoke an emotional response, ask a question or promise something.
@@ -1,7 +1,5 @@
-
 .. _reference/translations:

-
 ===================
 Translating Modules
 ===================
@@ -118,7 +116,8 @@ of global variables.
                return modules + ['your_module']

 Variables
-^^^^^^^^^
+---------
+
 **Don't** the extract may work but it will not translate the text correctly::

    _("Scheduled meeting with %s" % invitee.name)
@@ -130,7 +129,8 @@ will fallback on source in case of missing placeholder in the translation)::


 Blocks
-^^^^^^
+------
+
 **Don't** split your translation in several blocks or multiples lines::

    # bad, trailing spaces, blocks out of context
@@ -152,7 +152,8 @@ Blocks
      "this sales order request.")

 Plural
-^^^^^^
+------
+
 **Don't** pluralize terms the English-way::

    msg = _("You have %(count)s invoice", count=invoice_count)
@@ -167,7 +168,7 @@ Plural
      msg = _("You have one invoice")

 Read vs Run Time
-^^^^^^^^^^^^^^^^
+----------------

 **Don't** invoke translation lookup at server launch::

@@ -1,8 +1,8 @@
 :orphan:

-=============================
+==========================
 Customizing the web client
-=============================
+==========================

 .. note::

@@ -10,7 +10,6 @@ Customizing the web client
    but meanwhile, this tutorial will probably be frustrating to follow, since it
    was written a long time ago.

-
 .. highlight:: javascript

 .. default-domain:: js
@@ -30,7 +29,6 @@ or extend existing business systems of Odoo, see :doc:`backend`.

    It also requires :ref:`an installed Odoo <setup/install>`, and Git_.

-
 A Simple Module
 ===============

@@ -110,7 +108,9 @@ sub-folders are conventional and not strictly necessary.

 Which only prints a small message in the browser's console.

-The files in the ``static`` folder, need to be defined within the module in order for them to be loaded correctly. Everything in ``src/xml`` is defined in ``__manifest__.py`` while the contents of ``src/css`` and ``src/js`` are defined in ``petstore.xml``, or a similar file.
+The files in the ``static`` folder, need to be defined within the module in order for them to be
+loaded correctly. Everything in ``src/xml`` is defined in ``__manifest__.py`` while the contents of
+``src/css`` and ``src/js`` are defined in ``petstore.xml``, or a similar file.

 .. warning::

@@ -503,11 +503,10 @@ must be explicitly cleaned up (because the garbage collector will not handle
 them), you can override :func:`~odoo.Widget.destroy`.

 .. danger::
-
-    when overriding :func:`~odoo.Widget.destroy`, ``_super()``
-    *must always* be called otherwise the widget and its children are not
-    correctly cleaned up leaving possible memory leaks and "phantom events",
-    even if no error is displayed
+   when overriding :func:`~odoo.Widget.destroy`, ``_super()``
+   *must always* be called otherwise the widget and its children are not
+   correctly cleaned up leaving possible memory leaks and "phantom events",
+   even if no error is displayed

 The QWeb Template Engine
 ========================
@@ -537,16 +536,15 @@ characteristics:
  :class:`~odoo.Widget` without relying on QWeb)

 .. note::
+   The rationale behind using QWeb instead of existing javascript template
+   engines is the extensibility of pre-existing (third-party) templates, much
+   like Odoo :ref:`views <reference/views>`.

-    The rationale behind using QWeb instead of existing javascript template
-    engines is the extensibility of pre-existing (third-party) templates, much
-    like Odoo :ref:`views <reference/views>`.
-
-    Most javascript template engines are text-based which precludes easy
-    structural extensibility where an XML-based templating engine can be
-    generically altered using e.g. XPath or CSS and a tree-alteration DSL (or
-    even just XSLT). This flexibility and extensibility is a core
-    characteristic of Odoo, and losing it was considered unacceptable.
+   Most javascript template engines are text-based which precludes easy
+   structural extensibility where an XML-based templating engine can be
+   generically altered using e.g. XPath or CSS and a tree-alteration DSL (or
+   even just XSLT). This flexibility and extensibility is a core
+   characteristic of Odoo, and losing it was considered unacceptable.

 Using QWeb
 ----------
@@ -598,14 +596,13 @@ usages:
  sub-widget also gets a red background

 .. warning::
-
-    templates should have a single non-``t`` root element, especially if
-    they're set as a widget's :attr:`~odoo.Widget.template`. If there are
-    multiple "root elements", results are undefined (usually only the first
-    root element will be used and the others will be ignored)
+   templates should have a single non-``t`` root element, especially if
+   they're set as a widget's :attr:`~odoo.Widget.template`. If there are
+   multiple "root elements", results are undefined (usually only the first
+   root element will be used and the others will be ignored)

 QWeb Context
-''''''''''''
+~~~~~~~~~~~~

 QWeb templates can be given data and can contain basic display logic.

@@ -659,7 +656,7 @@ Result:
    <div>Hello Mordecai</div>

 Template Declaration
-''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~

 We've seen how to *render* QWeb templates, let's now see the syntax of
 the templates themselves.
@@ -683,7 +680,7 @@ it can be called using :func:`QWeb.render`. It can only be used at the
 top-level of a template file.

 Escaping
-''''''''
+~~~~~~~~

 The ``t-esc`` directive can be used to output text:

@@ -707,7 +704,7 @@ or method calls:
    <div><t t-esc="name.toUpperCase()"/></div>

 Outputting HTML
-'''''''''''''''
+~~~~~~~~~~~~~~~

 To inject HTML in the page being rendered, use ``t-raw``. Like ``t-esc`` it
 takes an arbitrary Javascript expression as parameter, but it does not
@@ -724,7 +721,7 @@ perform an HTML-escape step.
    vulnerabilities

 Conditionals
-''''''''''''
+~~~~~~~~~~~~

 QWeb can have conditional blocks using ``t-if``. The directive takes an
 arbitrary expression, if the expression is falsy (``false``, ``null``, ``0``
@@ -748,7 +745,7 @@ or an empty string) the whole block is suppressed, otherwise it is displayed.
    local variable if it's a complex or expensive expression.

 Iteration
-'''''''''
+~~~~~~~~~

 To iterate on a list, use ``t-foreach`` and ``t-as``. ``t-foreach`` takes an
 expression returning a list to iterate on ``t-as`` takes a variable name to
@@ -768,7 +765,7 @@ bind to each item during iteration.
          (dictionaries)

 Defining attributes
-'''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~

 QWeb provides two related directives to define computed attributes:
 :samp:`t-att-{name}` and :samp:`t-attf-{name}`. In either case, *name* is the
@@ -799,7 +796,7 @@ literal and partially computed such as a class:
    </div>

 Calling other templates
-'''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~

 Templates can be split into sub-templates (for simplicity, maintainability,
 reusability or to avoid excessive markup nesting).
@@ -829,12 +826,12 @@ rendering the ``A`` template will result in:
 Sub-templates inherit the rendering context of their caller.

 To Learn More About QWeb
-''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~

 For a QWeb reference, see :ref:`reference/qweb`.

 Exercise
-''''''''
+~~~~~~~~

 .. exercise:: Usage of QWeb in Widgets

@@ -1667,7 +1664,7 @@ In Odoo Web, the component responsible for handling and reacting to these
 actions is the *Action Manager*.

 Using the Action Manager
-''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~

 The action manager can be invoked explicitly from javascript code by creating
 a dictionary describing :ref:`an action <reference/actions>` of the right
@@ -1811,7 +1808,7 @@ Much of Odoo web's usefulness (and complexity) resides in views. Each view
 type is a way of displaying a model in the client.

 The View Manager
-''''''''''''''''
+~~~~~~~~~~~~~~~~

 When an ``ActionManager`` instance receive an action of type
 ``ir.actions.act_window``, it delegates the synchronization and handling of
@@ -1823,7 +1820,7 @@ multiple views depending on the original action's requirements:
   :width: 40%

 The Views
-'''''''''
+~~~~~~~~~

 Most :ref:`Odoo views <reference/views>` are implemented through a subclass
 of :class:`odoo.web.View` which provides a bit of generic basic structure
@@ -1932,14 +1929,14 @@ interface and the ``AbstractField`` class directly in the code of the Odoo web
 client.

 Creating a New Type of Field
-''''''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 In this part we will explain how to create a new type of field. The example
 here will be to re-implement the ``FieldChar`` class and progressively explain
 each part.

 Simple Read-Only Field
-""""""""""""""""""""""
+**********************

 Here is a first implementation that will only display text. The
 user will not be able to modify the content of the field.
@@ -1979,7 +1976,7 @@ none is specified by the form view (here we assume the default value of a
 ``char`` field should be an empty string).

 Read-Write Field
-""""""""""""""""
+****************

 Read-only fields, which only display content and don't allow the
 user to modify it can be useful, but most fields in Odoo also allow editing.