review suggestions - part 2

Author: AntoineVDV

content/administration/odoo_online.rst

@@ -161,19 +161,20 @@ Web Services
 
 In order to programmatically retrieve the list of the databases displayed in the
 `database manager <https://www.odoo.com/my/databases>`_, call the method ``list`` of the model
-``odoo.database`` via a :doc:`/developer/reference/external_api` call.
+``odoo.database`` via an :doc:`external JSON-2 API </developer/reference/external_api>` call.
 
-Example::
+.. example::
+   .. code:: python
 
-   import requests
+      import requests
 
-   APIKEY = "your_apikey"
+      APIKEY = "your_apikey"
 
-   requests.post(
-       "https://www.odoo.com/json/2/odoo.database/list",
-       headers={
-           "Authorization": f"bearer {APIKEY}",
-           "X-Odoo-Database": "openerp",
-       }
-       json={},
-   )
+      requests.post(
+          "https://www.odoo.com/json/2/odoo.database/list",
+          headers={
+              "Authorization": f"bearer {APIKEY}",
+              "X-Odoo-Database": "openerp",
+          }
+          json={},
+      )

content/developer/reference/external_api.rst

@@ -242,9 +242,10 @@ module.
 Code Example
 ============
 
-The following examples showcase how to execute two of the :ref:`reference/orm/models/crud` on a fake
-database ``mycompany`` hosted on a fake website ``https://mycompany.example.com``. Its comprehensive
-documentation is be available at https://mycompany.example.com/doc
+The following examples showcase how to execute two of the :ref:`common ORM methods
+<reference/orm/models/crud>` on a dummy database ``mycompany`` hosted on the dummy website
+``https://mycompany.example.com``. Its :ref:`dynamic documentation
+<reference/external_api/dynamic_doc>` would be available at https://mycompany.example.com/doc.
 
 .. tabs::
 
@@ -360,7 +361,7 @@ The above example is equivalent to running::
    records = Model.search([("name", "ilike", "%deco%"), ("is_company", "=", True)])
    return json.dumps(records.ids)
 
-then in a new transaction::
+Then, in a new transaction::
 
    records = self.env["res.partner"].with_context({"lang": "en_US"}).browse(ids)
    names = records.read(["name"])
@@ -409,17 +410,16 @@ The version function is replaced by the ``/web/version`` endpoint.
 
    {"version_info": [19, 0, 0, "final", 0, ""], "version": "19.0"}
 
-The two ``login`` and ``authenticate`` functions return the user id corresponding to the user after
-a successful login. The user id and password are necessary for subsequent RPC calls to the *object*
-service. The JSON-2 API uses a different authentication scheme where neither the user id nor the
-password are used. It is still possible to get the user own id doing a JSON-2 request for
-``res.users/context_get`` with no ids (the current user is extracted from the API key).
+The two ``login`` and ``authenticate`` functions return the user ID corresponding to the user after
+a successful login. The user ID and password are necessary for subsequent RPC calls to the *object*
+service. The JSON-2 API uses a different authentication scheme where neither the user ID nor the
+password are used. It is still possible to retrieve the user's own ID by sending a JSON-2 request to
+``res.users/context_get`` with no ID (the current user is extracted from the API key).
 
 Database service
 ----------------
 
 .. seealso::
-
    :ref:`db_manager_security`
 
 The db service defines 13 fonctions:
@@ -441,30 +441,31 @@ The db service defines 13 fonctions:
 Many of those function are accessible via the ``/web/database`` controllers. Those controllers
 work hand-in-hand with the HTML form at ``/web/database/manager`` and are accessible via HTTP.
 
-The following controllers use verb ``POST`` and content-type ``application/x-www-form-urlencoded``.
+The following controllers use the verb ``POST`` and content-type
+``application/x-www-form-urlencoded``.
 
-#. ``/web/database/create``, takes inputs ``master_pwd``, ``name``, ``login``, ``password``,
-   ``demo``, ``lang`` and ``phone``.
-#. ``/web/database/duplicate``, takes inputs ``master_pwd``, ``name``, ``new_name`` and
+#. ``/web/database/create`` takes inputs ``master_pwd``, ``name``, ``login``, ``password``,
+   ``demo``, ``lang``, and ``phone``.
+#. ``/web/database/duplicate`` takes inputs ``master_pwd``, ``name``, ``new_name``, and
    ``neutralize_database`` (not neutralized by default).
-#. ``/web/database/drop``, takes inputs ``master_pwd`` and ``name``.
-#. ``/web/database/backup``, takes inputs ``master_pwd``, ``name`` and ``backup_format`` (zip by
-   default), returns the backup in the http response.
-#. ``/web/database/change_password``, takes inputs ``master_pwd`` and ``master_pwd_new``.
+#. ``/web/database/drop`` takes inputs ``master_pwd`` and ``name``.
+#. ``/web/database/backup`` takes inputs ``master_pwd``, ``name``, and ``backup_format`` (zip by
+   default), and returns the backup in the http response.
+#. ``/web/database/change_password`` takes inputs ``master_pwd`` and ``master_pwd_new``.
 
-The following controller use verb ``POST`` and content-type ``multipart/form-data``.
+The following controller uses the verb ``POST`` and content-type ``multipart/form-data``.
 
-* ``/web/database/restore``, takes inputs ``master_pwd``, ``name``, ``copy`` (not copied by
+* ``/web/database/restore`` takes inputs ``master_pwd``, ``name``, ``copy`` (not copied by
   default) and ``neutralize`` (not neutralized by default), it takes a file input ``backup_file``.
 
-The following controller use verb ``POST`` and content-type ``application/json-rpc``.
+The following controller uses the verb ``POST`` and content-type ``application/json-rpc``.
 
-* ``/web/database/list``, takes an empty json object as input, returns the database list under the
-  json response's ``result`` entry.
+* ``/web/database/list`` takes an empty JSON object as input, and returns the database list under
+  the JSON response's ``result`` entry.
 
-The remaining function are: ``server_version``, which exist under ``/web/version``; ``list_lang``
-and ``list_countries`` which exist via JSON-2 on the ``res.lang`` and ``res.country`` models; and
-``migrate_databases`` which as no programmable API at the moment.
+The remaining function are: ``server_version``, which exists under ``/web/version``, ``list_lang``,
+and ``list_countries``, which exist via JSON-2 on the ``res.lang`` and ``res.country`` models, and
+``migrate_databases``, which as non-programmable API at the moment.
 
 Object service
 --------------
@@ -476,72 +477,74 @@ The object service defines 2 fonctions:
 
 They both give for access to all public model methods, including the generic ORM ones.
 
-Both functions are stateless. It means that the database, user id and user password are to be
+Both functions are stateless. It means that the database, user ID and user password are to be
 provided for each call. The model, method and arguments must be provided, too. The ``execute``
-function takes as many extra positional arguments as necessary. The ``execute_kw`` function takes a
+function takes as many extra positional arguments as necessary. The ``execute_kw`` function takes an
 ``args`` list of positional arguments and an optional ``kw`` dict of keyword arguments.
 
-The records ids are extracted from the first ``args``. When the called method is decorated with
-``@api.model``, no record ids are extracted and ``args`` is left as-is. It is only possible to give
-a context with ``execute_kw`` as it is extracted from the keyword argument named ``context``.
+The records IDs are extracted from the first ``args``. When the called method is decorated with
+``@api.model``, no record ID is extracted, and ``args`` is left as-is. It is only possible to give a
+context with ``execute_kw``, as it is extracted from the keyword argument named ``context``.
 
-Example, to run the following:
+.. example::
+   To run the following:
 
-.. code:: python
+   .. code:: python
 
-   (env['res.partner']
-       .with_user(2)  # admin
-       .with_context(lang='en_US')
-       .browse([1, 2, 3])
-       .read(['name'], load=None)
-   )
+      (env['res.partner']
+          .with_user(2)  # admin
+          .with_context(lang='en_US')
+          .browse([1, 2, 3])
+          .read(['name'], load=None)
+      )
 
-Using XML-RPC (JSON-RPC would be similar):
+   Using XML-RPC (JSON-RPC would be similar):
 
-.. code:: python
+   .. code:: python
 
-   from xmlrpc.client import ServerProxy
-   object = ServerProxy(...)
-   ids = [1, 2, 3]
-   fields = ['name']
-   load = None
+      from xmlrpc.client import ServerProxy
+      object = ServerProxy(...)
+      ids = [1, 2, 3]
+      fields = ['name']
+      load = None
 
-   object.execute("database", 2, "admin", "res.partner", "read", ids, fields, load)
-   object.execute("database", 2, "admin", "res.partner", "search", [
-       ids,
-       fields,
-   ], {
-       "context": {"lang": "en_US"},
-       "load": load,
-   })
+      object.execute("database", 2, "admin", "res.partner", "read", ids, fields, load)
+      object.execute("database", 2, "admin", "res.partner", "search", [
+          ids,
+          fields,
+      ], {
+          "context": {"lang": "en_US"},
+          "load": load,
+      })
 
 The JSON-2 API replaces the object service with a few differences. The database must only be 
 provided (via the ``X-Odoo-Database`` HTTP header) on systems where there are multiple databases
 available for a same domain. The login/password authentication scheme is replaced by an API key (via
 the ``Authorization: bearer`` HTTP header). The ``model`` and ``method`` are placed in the URL. The
 request body is a JSON object with all the methods arguments, plus ``ids`` and ``context``. All
-the arguments are named, there is no way in JSON-2 to call a function with positional arguments.
-
-Using JSON-2:
-
-.. code:: python
-
-   import requests
-
-   DATABSE = ...
-   DOMAIN = ...
-   API_KEY = "6578616d706c65206a736f6e20617069206b6579"
-
-   requests.post(
-       f"https://{DOMAIN}/json/2/res.partner/read",
-       headers={
-           # "X-Odoo-Database": DATABASE,  # only when DOMAIN isn't enough
-           "Authorization": f"bearer {API_KEY}",
-       },
-       json={
-           "ids": [1, 2, 3],
-           "context": {"lang": "en_US"},
-           "fields": ["name"],
-           "load": None,
-       },
-   ).json()
+the arguments are named; there is no way in JSON-2 to call a function with positional arguments.
+
+.. example::
+   Using JSON-2:
+
+   .. code:: python
+
+      import requests
+
+      DATABSE = ...
+      DOMAIN = ...
+      API_KEY = "6578616d706c65206a736f6e20617069206b6579"
+
+      requests.post(
+          f"https://{DOMAIN}/json/2/res.partner/read",
+          headers={
+              # "X-Odoo-Database": DATABASE,  # only when DOMAIN isn't enough
+              "Authorization": f"bearer {API_KEY}",
+          },
+          json={
+              "ids": [1, 2, 3],
+              "context": {"lang": "en_US"},
+              "fields": ["name"],
+              "load": None,
+          },
+      ).json()