[FW][REF] core,developer: improve upgrade doc

README.md

@@ -9,6 +9,7 @@
 - Python dependencies listed in the file `requirements.txt`.
 - Make
 - A local copy of the [odoo/odoo repository](https://github.com/odoo/odoo) (optional)
+- A local copy of the [odoo/upgrade-util repository](https://github.com/odoo/upgrade-util) (optional)
 
 ### Instructions
 
@@ -18,8 +19,9 @@
 3. See [this guide](https://www.odoo.com/documentation/latest/contributing/documentation.html)
    for more detailed instructions.
 
-Optional: place your local copy of the `odoo/odoo` repository in the parent directory or in the root
-directory of the documentation to build the latter with the documented Python docstrings.
+Optional: place your local copy of the `odoo/odoo` and `odoo/upgrade-util` repositories in
+the parent directory or in the root directory of the documentation to build the latter
+with the documented Python docstrings.
 
 ## Contribute to the documentation
 

conf.py

@@ -133,6 +133,24 @@
         )
         odoo_dir_in_path = True
 
+if odoo_dir_in_path:
+    upgrade_util_dir = next(filter(Path.exists, [Path('upgrade-util'), Path('../upgrade-util')]), None)
+    if not upgrade_util_dir:
+        _logger.warning(
+            "Could not find Upgrade Utils sources directory in `upgrade_util`.\n"
+            "The developer documentation will be built but autodoc directives will be skipped.\n"
+            "In order to fully build the 'Developer' documentation, clone the repository with "
+            "`git clone https://github.com/odoo/upgrade-util` or create a symbolic link."
+        )
+        odoo_dir_in_path = False
+    else:
+        _logger.info(
+            "Found Upgrade Util sources in %(directory)s",
+            {'directory': upgrade_util_dir.resolve()},
+        )
+        from odoo import upgrade
+        upgrade.__path__.append(str((upgrade_util_dir / 'src').resolve()))
+
 # Mapping between odoo models related to master data and the declaration of the
 # data. This is used to point users to available xml_ids when giving values for
 # a field with the autodoc_field extension.
@@ -250,6 +268,9 @@
 sphinx_tabs_disable_tab_closing = True
 sphinx_tabs_disable_css_loading = True
 
+# Autodoc ordering
+autodoc_member_order = 'bysource'
+
 #=== Options for HTML output ===#
 
 html_theme = 'odoo_theme'

content/developer/howtos/upgrade_custom_db.rst

@@ -187,10 +187,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 scripts <../reference/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_utils` and its helper functions.
+During the upgrade of the custom modules, you might have to use :doc:`upgrade scripts
+<../reference/upgrades/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/upgrades/upgrade_utils` 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
@@ -220,7 +220,7 @@ to their corresponding data. Together with the upgrade scripts, you can also mak
                   """
                )
 
-         Check the documentation for more information on :doc:`../reference/upgrade_scripts`.
+         Check the documentation for more information on :doc:`../reference/upgrades/upgrade_scripts`.
 
 Upgrade scripts can also be used to:
 

content/developer/reference.rst

@@ -15,7 +15,6 @@ Reference
    reference/user_interface
    reference/standard_modules
    reference/cli
-   reference/upgrade_scripts
-   reference/upgrade_utils
+   reference/upgrades
    reference/external_api
    reference/extract_api

content/developer/reference/upgrades.rst

@@ -0,0 +1,11 @@
+:nosearch:
+
+========
+Upgrades
+========
+
+.. toctree::
+    :titlesonly:
+
+    upgrades/upgrade_scripts
+    upgrades/upgrade_utils

content/developer/reference/upgrade_scripts.rst → content/developer/reference/upgrades/upgrade_scripts.rst

@@ -26,6 +26,11 @@ module (including Odoo's major version and the module's minor version) and `{pre
 the file that needs to be executed. The file's name will determine the :ref:`phase
 <upgrade-scripts/phases>` and order in which it is executed for that module and version.
 
+.. note::
+   From Odoo 13 the top-level directory for the upgrade scripts can also be named `upgrades`. This
+   naming is preferred since it has the correct meaning: *migrate* can be confused with *moving out
+   of Odoo*. Thus :file:`$module/upgrades/$version/` is also valid.
+
 .. note::
    Upgrade scripts are only executed when the module is being updated. Therefore, the
    module's minor version set in the `$version` directory needs to be higher than the module's