[IMP] doc: improve organization of upgrades docs

* Add autodoc directives to generate documentation directly from
  upgrade-util repo.
* Group all upgrades-related reference documentation into one group in
  the sidebar, instead of having two entries.
* Mention `upgrades` vs `migrations` directory. It has been supported
  since a while but nothing was explicit in the documentation.

closes #8834

X-original-commit: 91a48bf
Signed-off-by: Victor Feyens (vfe) <vfe@odoo.com>

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

@@ -12,7 +12,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