[FIX] Upgrade documentation: Code review changes

Author: augustoPerez

content/developer/howtos/upgrade_custom_db.rst

@@ -8,7 +8,7 @@ Upgrade a customized database
   :titlesonly:
   :glob:
 
-  upgrade/*
+  upgrade_custom_db/*
 
 Upgrading to a new version of Odoo can be challenging, especially if the database you work on
 contains custom modules. This page intent is to explain the technical process of upgrading a
@@ -195,9 +195,10 @@ To make sure the custom code is working flawlessly in the new version, follow th
 Migrate the data
 ----------------
 
-During the upgrade of the custom modules, you might have to use :doc:`upgrade/upgrade_scripts` to
-reflect changes from the source code to their corresponding data. Together with the Upgrade
-scripts, you can also make use of the :doc:`upgrade/upgrade_util` and its helper functions.
+During the upgrade of the custom modules, you might have to use
+:doc:`upgrade scripts <upgrade_custom_db/upgrade_scripts>` to reflect changes from the source code
+to their corresponding data. Together with the upgrade scripts, you can also make use of the
+:doc:`../reference/upgrade_util` and its helper functions.
 
 - Any technical data that was renamed during the upgrade of the custom code (models, fields,
   external identifiers) should be renamed using upgrade scripts to avoid data loss during the
@@ -227,7 +228,7 @@ scripts, you can also make use of the :doc:`upgrade/upgrade_util` and its helper
                   """
                )
 
-         Check the documentation for more information on :doc:`upgrade/upgrade_scripts`.
+         Check the documentation for more information on :doc:`upgrade_custom_db/upgrade_scripts`.
 
 Upgrade scripts can also be used to:
 

content/developer/howtos/upgrade/upgrade_scripts.rst renamed to content/developer/howtos/upgrade_custom_db/upgrade_scripts.rst

@@ -5,14 +5,14 @@ Upgrade scripts
 An upgrade script is a Python file containing a function called :meth:`migrate`, which the upgrade
 process invokes during the update of a module.
 
-.. method:: migrate(cr, version):
+.. method:: migrate(cr, version)
 
    :param cr: current database cursor
    :type cr: :class:`~odoo.sql_db.Cursor`
    :param str version: installed version of the module
 
 Typically, this function executes one or multiple SQL queries and can also access Odoo's ORM, as
-well as the :doc:`../upgrade/upgrade_util`.
+well as the :doc:`../../reference/upgrade_util`.
 
 As described in :ref:`upgrade_custom/upgraded_database/migrate_data`, you might have to use upgrade
 scripts to reflect changes from the source code to their corresponding data.
@@ -38,15 +38,18 @@ Follow this steps to create the directory's structure and the Python file:
       Upgrade scripts are only executed when the module is being updated. Therefore, the
       :file:`minor_version` set in the directory needs to be higher than the module's installed
       version and equal or lower to the updated version of the module.
-      For example, in an `Odoo 16` database, with a custom module installed in version `1.1`, and an
-      updated module version equal to `1.2`; the version directory should be `16.0.1.2`.
-   #. Create a :file:`Python file` inside the :file:`<version>` directory named according to the
+
+      .. example::
+
+         In an Odoo 16 database, with a custom module installed in version `1.1` that has been
+         updated to version `1.2`; the version directory should be `16.0.1.2`.
+
+   #. Create a Python file inside the :file:`<version>` directory named according to the
       :ref:`Phase <upgrade/upgrade-scripts/phases>` on which it needs to be executed. It should
       follow the template `{pre|post|end}-*.py`. The file name will determine the order in which it
       is executed for that module, version and phase.
-   #. Create a :file:`migrate` function in the Python file that receives as parameters
-      :file:`(cr, version)`.
-   #. Add the logic needed inside the Python file.
+   #. Create a :meth:`migrate` function in the Python file.
+   #. Add the logic needed inside the function.
 
 .. example::
 
@@ -91,8 +94,9 @@ Follow this steps to create the directory's structure and the Python file:
 
           _logger.info("Updated %s partners", len(partners))
 
-   Note that in the second example, the script takes advantage of the :doc:`../upgrade/upgrade_util`
-   to access the ORM. Check the documentation to find out more about this library.
+   Note that in the second example, the script takes advantage of the
+   :doc:`../../reference/upgrade_util` to access the ORM. Check the documentation to find out
+   more about this library.
 
 
 Running and testing upgrade scripts
@@ -144,14 +148,14 @@ The upgrade process consists of three phases for each version of each module:
 Upgrade scripts are grouped according to the first part of their filenames into the corresponding
 phase. Within each phase, the files are executed according to their lexical order.
 
-.. note::
+.. tip::
    If you are unsure which phase to use, use the end-phase.
 
-.. spoiler:: Execution order of example scripts for one module in one version
+.. admonition:: Execution order of example scripts for one module in one version
 
-   - :file:`pre-10-do_something.py`
-   - :file:`pre-20-something_else.py`
-   - :file:`post-do_something.py`
-   - :file:`post-something.py`
-   - :file:`end-01-migrate.py`
-   - :file:`end-migrate.py`
+   #. :file:`pre-10-do_something.py`
+   #. :file:`pre-20-something_else.py`
+   #. :file:`post-do_something.py`
+   #. :file:`post-something.py`
+   #. :file:`end-01-migrate.py`
+   #. :file:`end-migrate.py`

content/developer/reference.rst

@@ -12,5 +12,6 @@ Reference
     reference/user_interface
     reference/standard_modules
     reference/cli
+    reference/upgrade_util
     reference/external_api
     reference/extract_api

content/developer/howtos/upgrade/upgrade_util.rst renamed to content/developer/reference/upgrade_util.rst

@@ -6,7 +6,7 @@ The `Upgrade Util package <https://github.com/odoo/upgrade-util/>`_ is a library
 helper functions to facilitate the writing of upgrade scripts. This package, used by Odoo for the
 upgrade scripts of standard modules, provides reliability and helps speed up the upgrade process:
 
-- The helper functions make sure the data is consitent in the database.
+- The helper functions help make sure the data is consistent in the database.
 - It takes care of indirect references of the updated records.
 - Allows calling functions and avoid writing code, saving time and reducing development risks.
 - Helpers allow to focus on what is important for the upgrade and not think of details.
@@ -37,7 +37,7 @@ Using the Util package
 
 Once installed, the following packages are available for the upgrade scripts:
 
-- :mod:`odoo.upgrade.util`: the helper themself.
+- :mod:`odoo.upgrade.util`: the helper itself.
 - :mod:`odoo.upgrade.testing`: base TestCase classes.
 
 To use it in upgrade scripts, simply import it:
@@ -62,47 +62,45 @@ helper functions.
 
 .. note::
 
-   All util functions receive :attr:`cr` as a parameter. This refers to the database cursor. Use the
-   one received as a parameter in the :doc:`upgrade_scripts`.
+   All util functions receive :attr:`cr` as a parameter. This refers to the database cursor. Pass
+   the one received as a parameter in the :doc:`upgrade_scripts`.
 
 Fields
 ------
 
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/fields.py#L91>`_
-.. method:: remove_field(cr, model, fieldname[, cascade=False][, drop_column=True][, skip_inherit=()])
+.. method:: remove_field(cr, model, fieldname, cascade=False, drop_column=True, skip_inherit=())
 
-   Remove a field and its references from the database
+   Remove a field and its references from the database.
 
    :param str model: model name of the field to remove
    :param str fieldname: name of the field to remove
-   :param bool cascade: if ``True``, removes the field's column and inheritance in ``CASCADE``
-      (default: ``False``)
-   :param bool drop_column: if ``True``, drops the field's column (default: ``True``)
+   :param bool cascade: whether the field's column and inheritance are removed in ``CASCADE``
+   :param bool drop_column: whether the field's column is dropped
    :param list(str) or str skip_inherit: list of models whose field's inheritance is skipped.
       Use ``"*"`` to skip all inheritances
 
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/fields.py#L362>`_
-.. method:: rename_field(cr, model, old, new[, update_references=True][, domain_adapter=None][, skip_inherit=()])
+.. method:: rename_field(cr, model, old, new, update_references=True, domain_adapter=None, skip_inherit=())
 
-   Rename a field and its references from ``old`` to ``new``
+   Rename a field and its references from ``old`` to ``new``.
 
    :param str model: model name of the field to rename
    :param str old: current name od the field to rename
    :param str new: new name od the field to rename
-   :param bool update_references: if ``True``, Replace all references of field ``old`` to ``new``
+   :param bool update_references: whether all references of field ``old`` to ``new`` are replaced
       in: ``ir_filters``, ``ir_exports_line``, ``ir_act_server``, ``mail_alias``,
       ``ir_ui_view_custom (dashboard)``, ``domains (using "domain_adapter")``, ``related fields``
-      (default: ``True``)
    :param function domain_adapter: function that takes three arguments and returns a domain that
       substitutes the original leaf: ``(leaf: Tuple[str,str,Any], in_or: bool, negated: bool)`` ->
       ``List[Union[str,Tuple[str,str,Any]]]``
    :param list(str) or str skip_inherit: list of models whose field's inheritance is skipped.
       Use ``"*"`` to skip all inheritances
 
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/fields.py#L337>`_
-.. method:: move_field_to_module(cr, model, fieldname, old_module, new_module[, skip_inherit=()])
+.. method:: move_field_to_module(cr, model, fieldname, old_module, new_module, skip_inherit=())
 
-   Move a field's reference in ``ir_model_data`` table from ``old_module`` to ``new_module``
+   Move a field's reference in ``ir_model_data`` table from ``old_module`` to ``new_module``.
 
    :param str model: model name of the field to move
    :param str fieldname: name of the field to move
@@ -115,26 +113,26 @@ Models
 ------
 
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/models.py#L53>`_
-.. method:: remove_model(cr, model[, drop_table=True][, ignore_m2m=()])
+.. method:: remove_model(cr, model, drop_table=True, ignore_m2m=())
 
-   Remove a model and its references from the database
+   Remove a model and its references from the database.
 
    :param str model: name of the model to remove
-   :param bool drop_table: if ``True``, drops the model's table (default: ``True``)
+   :param bool drop_table: whether the model's table is dropped
    :param list(str) or str ignore_m2m: list of m2m tables ignored to remove. Use ``"*"`` to ignore
       all m2m tables
 
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/models.py#L203>`_
-.. method:: rename_model(cr, old, new[, rename_table=True])
+.. method:: rename_model(cr, old, new, rename_table=True)
 
-   Rename a model and its references from ``old`` to ``new``
+   Rename a model and its references from ``old`` to ``new``.
 
    :param str old: current name of the model to rename
    :param str new: new name of the model to rename
-   :param bool rename_table: if ``True``, renames the model's table (default: ``True``)
+   :param bool rename_table: whether the model's table is renamed
 
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/models.py#L323>`_
-.. method:: merge_model(cr, source, target[, drop_table=True][, fields_mapping=None][, ignore_m2m=()])
+.. method:: merge_model(cr, source, target, drop_table=True, fields_mapping=None, ignore_m2m=())
 
    Merge the references from ``source`` model into ``target`` model and removes ``source`` model and
    its references. By default, only the fields with the same name in both models are mapped.
@@ -144,7 +142,7 @@ Models
 
    :param str source: name of the source model of the merge
    :param str target: name of the destination model of the merge
-   :param bool drop_table: if ``True``, drops the source model's table (default: ``True``)
+   :param bool drop_table: whether the source model's table is dropped
    :param dict fields_mapping: Dictionary ``{"source_model_field_1": "target_model_field_1", ...}``
       mapping fields with different names on both models
    :param list(str) or str ignore_m2m: list of m2m tables ignored to remove from source model.
@@ -155,92 +153,91 @@ Modules
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/modules.py#L218>`_
 .. method:: remove_module(cr, module)
 
-   Uninstall and remove a module and its references from the database
+   Uninstall and remove a module and its references from the database.
 
    :param str module: name of the module to remove
 
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/modules.py#L263>`_
 .. method:: rename_module(cr, old, new)
 
-   Rename a module and its references from ``old`` to ``new``
+   Rename a module and its references from ``old`` to ``new``.
 
    :param str old: current name of the module to rename
    :param str new: new name of the module to rename
 
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/modules.py#L323>`_
 .. method:: merge_module(cr, old, into, update_dependers=True)
 
-   Move all references of module ``old`` into module ``into``
+   Move all references of module ``old`` into module ``into``.
 
    :param str old: name of the source module of the merge
    :param str into: ame of the destination module of the merge
-   :param bool update_dependers: if ``True``, updates the dependencies of modules that depends on
-      ``old`` (default: ``True``)
+   :param bool update_dependers: whether the dependencies of modules that depends on ``old`` are
+      updated
 
 ORM
 ---
 
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/orm.py#L43>`_
 .. method:: env(cr)
 
-   Create a new environment from the cursor
+   Create a new environment from the cursor.
 
    .. warning::
       This function does NOT empty the cache maintained on the cursor for superuser with an empty
-      environment. A call to invalidate_cache will most probably be necessary every time you
+      environment. A call to `invalidate_cache` will most probably be necessary every time you
       directly modify something in database.
 
    :return: The new environment
    :rtype: :class:`~odoo.api.Environment`
 
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/orm.py#L218>`_
-.. method:: recompute_fields(cr, model, fields[, ids=None][, logger=_logger][, chunk_size=256][, strategy="auto"])
+.. method:: recompute_fields(cr, model, fields, ids=None, logger=_logger, chunk_size=256, strategy="auto")
 
-   Recompute field values
+   Recompute field values.
 
    :param str model:  model name of the field(s) to recompute
    :param list(str) fields: list of field names to recompute
    :param list(int) ids: list of record IDs to recompute
    :param logger: Logger used to print the progress of the function
-   :type: logger: :class:`logging.Logger`
+   :type logger: :class:`logging.Logger`
    :param int chunk_size: size of the chunk used to split the records for better processing
-      (default: ``256``)
-   :param str strategy: strategy used to process the recomputation (default: ``auto``):
+   :param str strategy: strategy used to process the recomputation:
 
       - ``flush``: Flush the recomputation when it's finished
       - ``commit``: Commit the recomputation when it's finished
       - ``auto``: The function chooses the best alternative for the recomputation based on the
-        number of records to recompute and the fields traceability.
+        number of records to recompute and the fields traceability
 
 Records
 -------
 
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/records.py#L612>`_
 .. method:: ref(cr, xmlid)
 
-   Return the id corresponding to the given :term:`xml_id <external identifier>`
+   Return the id corresponding to the given :term:`xml_id <external identifier>`.
 
    :param str xml_id: Record xml_id, under the format ``<module.id>``
-   :return: Found record id or None
-   :rtype: int
+   :return: Found record id, if any
+   :rtype: int or `None`
 
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/records.py#L281>`_
 .. method:: remove_record(cr, name)
 
-   Remove a record and its references corresponding to the given :term:`xml_id <external identifier>`
+   Remove a record and its references corresponding to the given
+   :term:`xml_id <external identifier>`.
 
    :param str name: record xml_id, under the format ``<module.id>``
 
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/records.py#L548>`_
-.. method:: rename_xmlid(cr, old, new[, noupdate=None][, on_collision="fail"])
+.. method:: rename_xmlid(cr, old, new, noupdate=None, on_collision="fail")
 
-   Rename the :term:`external Identifier` of a record
+   Rename the :term:`external Identifier` of a record.
 
    :param str old: current xml_id of the record, under the format ``<module.id>``
    :param str new: new xml_id of the record, under the format ``<module.id>``
-   :param bool noupdate: value to set on the ir_model_data record ``noupdate`` field (default:
-      ``None``)
-   :param str on_collision: action to take if the new xml_id already exists (default: ``fail``)
+   :param bool noupdate: value to set on the ir_model_data record ``noupdate`` field
+   :param str on_collision: action to take if the new xml_id already exists
 
       - ``fail``: raise ``MigrationError`` and prevent renaming
       - ``merge``: renames the external Identifier and removes the old one
@@ -267,17 +264,15 @@ Records
    :rtype: str
 
 .. `[source] <https://github.com/odoo/upgrade-util/blob/master/src/util/records.py#L720>`_
-.. method:: update_record_from_xml(cr, xmlid[, reset_write_metadata=True][, force_create=True][, from_module=None][, reset_translations=()])
+.. method:: update_record_from_xml(cr, xmlid, reset_write_metadata=True, force_create=True, from_module=None, reset_translations=())
 
    Update a record based on its definition in the :doc:`/developer/reference/backend/data`.
 
    Useful to update ``noupdate`` records, in order to reset them for the upgraded version.
 
    :param str xmlid: record xml_id, under the format ``<module.id>``
-   :param bool reset_write_metadata: if ``True``, the metadata before the record update is kept
-      (default: ``True``)
-   :param bool force_create: if ``True``, creates the record if it does not exist. (default:
-      ``True``)
+   :param bool reset_write_metadata: whether the metadata before the record update is kept
+   :param bool force_create: whether the record is created if it does not exist
    :param str from_module: name of the module from which to update the record. Useful when the
       record is rewritten in another module.
-   :param set of str reset_translations: set of field names whose translations get reset.
+   :param set of str reset_translations: set of field names whose translations get reset