[IMP] Accounting: Reports: Document the new cross_report syntax for forced date scope

task-5243334

.gitignore

@@ -2,6 +2,7 @@
 *.mo
 .*
 !.gitattributes
+!.weblate.json
 
 # Sphinx build files
 _build/

.tx/config

@@ -1,152 +0,0 @@
-[main]
-host = https://www.transifex.com
-
-[o:odoo:p:odoo-18-doc:r:administration]
-file_filter            = locale/<lang>/LC_MESSAGES/administration.po
-source_file            = locale/sources/administration.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = administration
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en
-
-[o:odoo:p:odoo-18-doc:r:applications]
-file_filter            = locale/<lang>/LC_MESSAGES/applications.po
-source_file            = locale/sources/applications.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = applications
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en
-
-[o:odoo:p:odoo-18-doc:r:essentials]
-file_filter            = locale/<lang>/LC_MESSAGES/essentials.po
-source_file            = locale/sources/essentials.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = essentials
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en
-
-[o:odoo:p:odoo-18-doc:r:finance]
-file_filter            = locale/<lang>/LC_MESSAGES/finance.po
-source_file            = locale/sources/finance.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = finance
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en
-
-[o:odoo:p:odoo-18-doc:r:general]
-file_filter            = locale/<lang>/LC_MESSAGES/general.po
-source_file            = locale/sources/general.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = general
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en
-
-[o:odoo:p:odoo-18-doc:r:hr]
-file_filter            = locale/<lang>/LC_MESSAGES/hr.po
-source_file            = locale/sources/hr.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = hr
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en
-
-[o:odoo:p:odoo-18-doc:r:index]
-file_filter            = locale/<lang>/LC_MESSAGES/index.po
-source_file            = locale/sources/index.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = index
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en
-
-[o:odoo:p:odoo-18-doc:r:inventory_and_mrp]
-file_filter            = locale/<lang>/LC_MESSAGES/inventory_and_mrp.po
-source_file            = locale/sources/inventory_and_mrp.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = inventory_and_mrp
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en
-
-[o:odoo:p:odoo-18-doc:r:marketing]
-file_filter            = locale/<lang>/LC_MESSAGES/marketing.po
-source_file            = locale/sources/marketing.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = marketing
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en
-
-[o:odoo:p:odoo-18-doc:r:productivity]
-file_filter            = locale/<lang>/LC_MESSAGES/productivity.po
-source_file            = locale/sources/productivity.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = productivity
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en
-
-[o:odoo:p:odoo-18-doc:r:sales]
-file_filter            = locale/<lang>/LC_MESSAGES/sales.po
-source_file            = locale/sources/sales.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = sales
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en
-
-[o:odoo:p:odoo-18-doc:r:services]
-file_filter            = locale/<lang>/LC_MESSAGES/services.po
-source_file            = locale/sources/services.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = services
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en
-
-[o:odoo:p:odoo-18-doc:r:user_settings]
-file_filter            = locale/<lang>/LC_MESSAGES/settings.po
-source_file            = locale/sources/settings.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = settings
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en
-
-[o:odoo:p:odoo-18-doc:r:studio]
-file_filter            = locale/<lang>/LC_MESSAGES/studio.po
-source_file            = locale/sources/studio.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = studio
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en
-
-[o:odoo:p:odoo-18-doc:r:websites]
-file_filter            = locale/<lang>/LC_MESSAGES/websites.po
-source_file            = locale/sources/websites.pot
-type                   = POT
-minimum_perc           = 0
-resource_name          = websites
-replace_edited_strings = false
-keep_translations      = false
-source_lang            = en

.weblate.json

@@ -0,0 +1,76 @@
+{
+    "projects": {
+        "odoo-19-doc": [
+            {
+                "name": "administration",
+                "filemask": "locale/*/LC_MESSAGES/administration.po",
+                "new_base": "locale/sources/administration.pot"
+            },
+            {
+                "name": "applications",
+                "filemask": "locale/*/LC_MESSAGES/applications.po",
+                "new_base": "locale/sources/applications.pot"
+            },
+            {
+                "name": "essentials",
+                "filemask": "locale/*/LC_MESSAGES/essentials.po",
+                "new_base": "locale/sources/essentials.pot"
+            },
+            {
+                "name": "finance",
+                "filemask": "locale/*/LC_MESSAGES/finance.po",
+                "new_base": "locale/sources/finance.pot"
+            },
+            {
+                "name": "general",
+                "filemask": "locale/*/LC_MESSAGES/general.po",
+                "new_base": "locale/sources/general.pot"
+            },
+            {
+                "name": "hr",
+                "filemask": "locale/*/LC_MESSAGES/hr.po",
+                "new_base": "locale/sources/hr.pot"
+            },
+            {
+                "name": "index",
+                "filemask": "locale/*/LC_MESSAGES/index.po",
+                "new_base": "locale/sources/index.pot"
+            },
+            {
+                "name": "inventory_and_mrp",
+                "filemask": "locale/*/LC_MESSAGES/inventory_and_mrp.po",
+                "new_base": "locale/sources/inventory_and_mrp.pot"
+            },
+            {
+                "name": "marketing",
+                "filemask": "locale/*/LC_MESSAGES/marketing.po",
+                "new_base": "locale/sources/marketing.pot"
+            },
+            {
+                "name": "productivity",
+                "filemask": "locale/*/LC_MESSAGES/productivity.po",
+                "new_base": "locale/sources/productivity.pot"
+            },
+            {
+                "name": "sales",
+                "filemask": "locale/*/LC_MESSAGES/sales.po",
+                "new_base": "locale/sources/sales.pot"
+            },
+            {
+                "name": "services",
+                "filemask": "locale/*/LC_MESSAGES/services.po",
+                "new_base": "locale/sources/services.pot"
+            },
+            {
+                "name": "studio",
+                "filemask": "locale/*/LC_MESSAGES/studio.po",
+                "new_base": "locale/sources/studio.pot"
+            },
+            {
+                "name": "websites",
+                "filemask": "locale/*/LC_MESSAGES/websites.po",
+                "new_base": "locale/sources/websites.pot"
+            }
+        ]
+    }
+}

Makefile

@@ -35,6 +35,8 @@ endif
 
 #=== Standard rules ===#
 
+.PHONY: all help clean html latexpdf gettext fast static test review
+
 # In first position to build the documentation from scratch by default
 all: html
 
@@ -89,7 +91,8 @@ static: $(HTML_BUILD_DIR)/_static/style.css
 test:
 	@python tests/main.py $(SOURCE_DIR)/administration $(SOURCE_DIR)/applications $(SOURCE_DIR)/contributing $(SOURCE_DIR)/developer redirects
 
-# Similar as `test`, but called only manually by content reviewers to trigger extra checks.
+# Similar to `test`, but called only manually by content reviewers to specify a path and a max line
+# length.
 review:
 	@read -p "Enter relative content path: " path; read -p "Enter max line length (default: 100): " line_length; \
 	if [ -z "$$path" ]; then echo "Error: Path cannot be empty"; exit 1; fi; \

README.md

@@ -1,38 +1,67 @@
 # Odoo documentation
 
-## Build the documentation locally
+## Build the documentation
 
 ### Requirements
 
-- Git
+- [Git](https://git-scm.com/install)
-- Python 3.6, 3.7, or 3.8
+- [Python 3.10 to 3.14](https://www.python.org/downloads/).
-- Python dependencies listed in the file `requirements.txt`.
 - Make
-- A local copy of the [odoo/odoo repository](https://github.com/odoo/odoo) (optional)
+- Python dependencies from `requirements.txt` (see instructions below)
-- A local copy of the [odoo/upgrade-util repository](https://github.com/odoo/upgrade-util) (optional)
+- A local copy of the [odoo/odoo](https://github.com/odoo/odoo) repository (optional)
+- A local copy of the [odoo/upgrade-util](https://github.com/odoo/upgrade-util) repository
+  (optional)
 
-### Instructions
+### Quick start
 
-1. In a terminal, navigate to the root directory of the documentation and build it `make`.
+1. Create and activate a virtual environment.
-   Additional commands are available with `make help`.
+   - On Linux and macOS: `python3 -m venv .venv && source .venv/bin/activate`
-2. Open the file `documentation/_build/html/index.html` in your web browser.
+   - On Windows (PowerShell): `py3 -m venv .venv; .\.venv\Scripts\Activate.ps1`
-3. See [this guide](https://www.odoo.com/documentation/latest/contributing/documentation.html)
+2. Install the Python dependencies: `pip install -r requirements.txt`
-   for more detailed instructions.
+3. Build the documentation: `make html` (see more commands with `make help`)
+4. Open `documentation/_build/html/index.html` in your web browser.
 
-Optional: place your local copy of the `odoo/odoo` and `odoo/upgrade-util` repositories in
+### Additional build options
-the parent directory or in the root directory of the documentation to build the latter
+
-with the documented Python docstrings.
+- `make fast` to build the documentation with a shallow menu (faster).
+- `make clean` to delete the build files.
+- `make test` to run the guidelines tests.
+- `make html CURRENT_LANG=fr` to build the documentation only in French.
+- `make html CURRENT_LANG=fr LANGUAGES=en,fr,de` to build the documentation in French and enable the
+  language switcher, with the specified LANGUAGES as available languages. This command must be
+  invoked for each CURRENT_LANG you want to build.
+- `make html VERSIONS=17.0,18.0,saas-18.4,19.0,master` to build the documentation in the **current
+  version** and enable the version switcher, with the specified VERSIONS as available versions. This
+  command must be invoked for each of the VERSIONS you want to build.
+
+The list of available languages can be found in `conf.py`, in the `languages_names` variable.
+
+When building the documentation for a specific language or version, the build files are created in
+`documentation/_build/html/<language>/`, `documentation/_build/html/<version>/` or
+`documentation/_build/html/<version>/<language>/`.
+
+### Using local Odoo sources
+
+If you have local checkouts of `odoo/odoo` and/or `odoo/upgrade-util`, place them either:
+- as siblings of this repository (in the parent directory), or
+- inside the `documentation` directory.
+
+When present in one of these locations, the build will include Python docstrings from those
+repositories if their version matches the documentation's version.
+
+### Troubleshooting
+
+- Verify your Python version: `python3 --version` (must be 3.10–3.14)
+- Ensure your virtual environment is active and dependencies are installed.
+- If you have made changes to the file structure, try `make clean` before building.
+- If the language or version switchers redirect to a missing file, check that you have built the
+  documentation for all available languages and versions.
+- The "Developer" documentation is only available in English.
 
 ## Contribute to the documentation
 
-For contributions to the content of the documentation, please refer to the
+For contributions to the content of the documentation, see the
 [Introduction Guide](https://www.odoo.com/documentation/latest/contributing/documentation.html).
 
-To **report a content issue**, **request new content** or **ask a question**, use the
+To report a content issue, request new content, or ask a question, use the
-[repository's issue tracker](https://github.com/odoo/documentation/issues).
+[issue tracker](https://github.com/odoo/documentation/issues).
-
-## Learn More
-
-To learn more about Odoo, in addition to the documentation, have a look at
-[the official eLearning](https://odoo.com/slides) and
-[Scale-up, The Business Game](https://www.odoo.com/page/scale-up-business-game).

conf.py

@@ -21,7 +21,7 @@ copyright = 'Odoo S.A.'
 
 # `version` is the version info for the project being documented, acts as replacement for |version|,
 # also used in various other places throughout the built documents.
-# `release` is the full version, including alpha/beta/rc tags. Acts as replacement for |release|.
+# `release` is the full version, including a/b/rc tags. Acts as replacement for |release|.
 version = release = 'master'
 
 # `current_branch` is the technical name of the current branch.
@@ -82,6 +82,7 @@ source_read_replace_vals = {
     'CURRENT_MAJOR_VERSION': current_major_version,
     'GITHUB_PATH': f'https://github.com/odoo/odoo/blob/{version}',
     'GITHUB_ENT_PATH': f'https://github.com/odoo/enterprise/blob/{version}',
+    'GITHUB_TUTO_PATH': f'https://github.com/odoo/tutorials/blob/{current_major_branch}',
     'OWL_PATH': f'https://github.com/odoo/owl/blob/master',
 }
 
@@ -116,7 +117,7 @@ else:
     odoo.addons.__path__.append(str(odoo_dir) + '/addons')
     from odoo import release as odoo_release  # Don't collide with Sphinx's 'release' config option
     odoo_version = '.'.join(str(s) for s in odoo_release.version_info[:2]).replace('~', '-')  # Change saas~XX.Y to saas-XX.Y
-    odoo_version = 'master' if 'alpha' in odoo_release.version else odoo_version
+    odoo_version = 'master' if odoo_release.ALPHA in odoo_release.version_info else odoo_version
     if release != odoo_version:
         _logger.warning(
             "Found Odoo sources in %(directory)s but with version '%(odoo_version)s' incompatible "
@@ -211,9 +212,9 @@ extensions.append('sphinx.ext.graphviz' if shutil.which('dot') else 'graphviz_pl
 todo_include_todos = False
 
 intersphinx_mapping = {
-    'pillow': ('https://pillow.readthedocs.io/en/stable/', None),
+    'python': ('https://docs.python.org/3/', '../invs/python.inv'),
-    'python': ('https://docs.python.org/3/', None),
+    # apparently local inventories are relative to the source dir?
-    'werkzeug': ('https://werkzeug.palletsprojects.com/en/2.3.x/', None),
+    'werkzeug': ('https://werkzeug.palletsprojects.com/', '../invs/werkzeug.inv'),
 }
 
 github_user = 'odoo'
@@ -227,20 +228,21 @@ sphinx.transforms.i18n.docname_to_domain = (
     sphinx.util.i18n.docname_to_domain
 ) = lambda docname, compact: docname.split('/')[1 if docname.startswith('applications/') else 0]
 
-# The version names that should be shown in the version switcher, if the config option `versions`
+# The labels used in the version switcher to show the versions provided with the `versions` config
-# is populated. If a version is passed to `versions` but is not listed here, it will not be shown.
+# option. If a provided version has no label, the version string is used as label.
 versions_names = {
     'master': "Master",
+    '19.0': "Odoo 19",
+    'saas-18.4': "Odoo 18.4",
+    'saas-18.3': "Odoo 18.3",
+    'saas-18.2': "Odoo 18.2",
     '18.0': "Odoo 18",
-    'saas-17.4': "Odoo Online",
-    'saas-17.2': "Odoo Online",
     '17.0': "Odoo 17",
     '16.0': "Odoo 16",
-    '15.0': "Odoo 15",
 }
 
-# The language names that should be shown in the language switcher, if the config option `languages`
+# The labels used in the language switcher to show the languages provided with the `languages`
-# is populated. If a language is passed to `languages` but is not listed here, it will not be shown.
+# config option. If a provided language code has no label, the upper-cased code is used as label.
 languages_names = {
     'de': 'DE',
     'en': 'EN',
@@ -329,29 +331,31 @@ latex_documents = [
      'terms_of_sale.tex', 'Odoo Terms of Sale', '', 'howto'),
 
     ('legal/terms/i18n/enterprise_tex_fr', 'odoo_enterprise_agreement_fr.tex',
-     'Odoo Enterprise Subscription Agreement (FR)', '', 'howto'),
+     "Contrat d'Abonnement Odoo Enterprise", '', 'howto'),
     ('legal/terms/i18n/partnership_tex_fr',
-     'odoo_partnership_agreement_fr.tex', 'Odoo Partnership Agreement (FR)', '', 'howto'),
+     'odoo_partnership_agreement_fr.tex', 'Contrat de Partenariat Odoo', '', 'howto'),
     ('legal/terms/i18n/terms_of_sale_fr', 'terms_of_sale_fr.tex',
      'Conditions Générales de Vente Odoo', '', 'howto'),
 
     ('legal/terms/i18n/enterprise_tex_nl', 'odoo_enterprise_agreement_nl.tex',
-     'Odoo Enterprise Subscription Agreement (NL)', '', 'howto'),
+     'Odoo Enterprise Abonnementsovereenkomst', '', 'howto'),
 
     ('legal/terms/i18n/enterprise_tex_de', 'odoo_enterprise_agreement_de.tex',
-     'Odoo Enterprise Subscription Agreement (DE)', '', 'howto'),
+     'Odoo Enterprise Abonnementsvertrag', '', 'howto'),
     ('legal/terms/i18n/terms_of_sale_de', 'terms_of_sale_de.tex',
      'Allgemeine Verkaufsbedingungen Odoo', '', 'howto'),
 
     ('legal/terms/i18n/enterprise_tex_es', 'odoo_enterprise_agreement_es.tex',
-     'Odoo Enterprise Subscription Agreement (ES)', '', 'howto'),
+     'Acuerdo de suscripción de Odoo Enterprise', '', 'howto'),
     ('legal/terms/i18n/partnership_tex_es',
-     'odoo_partnership_agreement_es.tex', 'Odoo Partnership Agreement (ES)', '', 'howto'),
+     'odoo_partnership_agreement_es.tex', 'Acuerdo de Colaboración de Odoo', '', 'howto'),
     ('legal/terms/i18n/terms_of_sale_es', 'terms_of_sale_es.tex',
      'Términos Generales de Venta Odoo', '', 'howto'),
 
     ('legal/terms/i18n/enterprise_tex_pt_BR', 'odoo_enterprise_agreement_pt_BR.tex',
-     'Odoo Enterprise Subscription Agreement (PT)', '', 'howto'),
+     'Contrato de Assinatura do Odoo Enterprise', '', 'howto'),
+    ('legal/terms/i18n/terms_of_sale_pt_BR', 'terms_of_sale_pt_BR.tex',
+     'Termos Gerais de Venda Odoo', '', 'howto'),
 ]
 
 # List of languages that have legal translations (excluding EN). The keys must be in
@@ -382,6 +386,18 @@ def source_read_replace(app, docname, source):
         result = result.replace(f"{{{key}}}", app.config.source_read_replace_vals[key])
     source[0] = result
 
+def upgrade_util_signature_rewrite(app, domain, objtype, contentnode):
+    # Same as add_module_names=False but **only** for odoo.upgrade.util functions or classes
+    signature = contentnode.parent[0]
+    if objtype == 'function' and signature.astext().startswith(('odoo.upgrade.util.', 'odoo.upgrade.testing.')):
+        # <odoo.upgrade.util.modules>, <modules_installed>, <(cr, *modules)>
+        # <odoo.upgrade.testing>, <change_version>, <(version_str)>
+        signature.pop(0)
+    if objtype == 'class' and signature.astext().startswith(('class odoo.upgrade.util.', 'class odoo.upgrade.testing.')):
+        # <class >, <odoo.upgrade.util.pg.>, <PGRegexp>
+        # <class >, <odoo.upgrade.testing.>, <UpgradeCase>
+        signature.pop(1)
+
 def setup(app):
     # Generate all alternate URLs for each document
     app.add_config_value('project_root', None, 'env')
@@ -391,6 +407,7 @@ def setup(app):
     app.add_config_value('is_remote_build', None, 'env')  # Whether the build is remotely deployed
     app.add_config_value('source_read_replace_vals', {}, 'env')
     app.connect('source-read', source_read_replace)
+    app.connect('object-description-transform', upgrade_util_signature_rewrite)
     # TODO uncomment after moving to >= v7.2.5 to also substitute placeholders in included  files.
     #  See https://github.com/sphinx-doc/sphinx/commit/ff1831
     #  app.connect('include-read', source_read_replace)
@@ -430,7 +447,7 @@ def _generate_alternate_urls(app, pagename, templatename, context, doctree):
       - The language switcher and related link tags
     """
 
-    def _canonicalize():
+    def canonicalize():
         """ Add the canonical URL for the current document in the rendering context.
 
         The canonical version is the last released version of the documentation.
@@ -442,94 +459,93 @@ def _generate_alternate_urls(app, pagename, templatename, context, doctree):
         - /documentation/11.0/fr/website.html -> canonical = /documentation/14.0/fr/website.html
         """
         # If the canonical version is not set, assume that the project has a single version
-        _canonical_version = app.config.canonical_version or app.config.version
+        canonical_version_ = app.config.canonical_version or app.config.version
-        _canonical_lang = 'en'  # Always 'en'. Don't take the value of the config option.
+        canonical_lang_ = 'en'  # Always 'en'. Don't take the value of the config option.
-        context['canonical'] = _build_url(_version=_canonical_version, _lang=_canonical_lang)
+        context['canonical'] = build_url(version_=canonical_version_, lang_=canonical_lang_)
 
-    def _versionize():
+    def versionize():
         """ Add the pairs of (version, url) for the current document in the rendering context.
 
         The entry 'version' is added by Sphinx in the rendering context.
         """
-        context['version_display_name'] = versions_names[version]
+        context['version_display_name'] = versions_names.get(version, version)
 
-        # If the list of versions is not set, assume the project has no alternate version
+        # If the list of versions is not set, assume the project has no alternate version.
-        _provided_versions = app.config.versions and app.config.versions.split(',') or []
+        provided_versions_ = app.config.versions and app.config.versions.split(',') or []
 
         # Map alternate versions to their display names and URLs.
         context['alternate_versions'] = []
-        for _alternate_version, _display_name in versions_names.items():
+        for alternate_version_ in reversed(provided_versions_):  # Reverse to show latest first.
-            if _alternate_version in _provided_versions and _alternate_version != version:
+            if alternate_version_ != version:
-                context['alternate_versions'].append(
+                display_name_ = versions_names.get(alternate_version_, alternate_version_)
-                    (_display_name, _build_url(_alternate_version))
+                context['alternate_versions'].append((display_name_, build_url(alternate_version_)))
-                )
 
-    def _localize():
+    def localize():
         """ Add the pairs of (lang, code, url) for the current document in the rendering context.
 
         E.g.: ('French', 'fr', 'https://.../fr_BE/...')
 
         The entry 'language' is added by Sphinx in the rendering context.
         """
-        _current_lang = app.config.language or 'en'
+        current_lang_ = app.config.language or 'en'
         # Replace the context value by its upper-cased value ("FR" instead of "fr")
-        context['language'] = languages_names.get(_current_lang, _current_lang.upper())
+        context['language'] = languages_names.get(current_lang_, current_lang_.upper())
-        context['language_code'] = _current_lang
+        context['language_code'] = current_lang_
 
         # If the list of languages is not set, assume that the project has no alternate language
-        _provided_languages = app.config.languages and app.config.languages.split(',') or []
+        provided_languages_ = app.config.languages and app.config.languages.split(',') or []
 
         # Map alternate languages to their display names and URLs.
         context['alternate_languages'] = []
-        for _alternate_lang, _display_name in languages_names.items():
+        for alternate_lang_ in provided_languages_:
-            if _alternate_lang in _provided_languages and _alternate_lang != _current_lang:
+            if alternate_lang_ != current_lang_:
+                display_name_ = languages_names.get(alternate_lang_, alternate_lang_.upper())
                 context['alternate_languages'].append(
                     (
-                        _display_name,
+                        display_name_,
-                        _alternate_lang.split('_')[0] if _alternate_lang != 'en' else 'x-default',
+                        alternate_lang_.split('_')[0] if alternate_lang_ != 'en' else 'x-default',
-                        _build_url(_lang=_alternate_lang),
+                        build_url(lang_=alternate_lang_),
                     )
                 )
 
         # Dynamic generation of localized legal doc links
         context['legal_translations'] = legal_translations
 
-
+    def build_url(version_=None, lang_=None):
-    def _build_url(_version=None, _lang=None):
         if app.config.is_remote_build:
             # Project root like https://www.odoo.com/documentation
-            _root = app.config.project_root
+            root_ = app.config.project_root
         else:
             # Project root like .../documentation/_build/html/14.0/fr
-            _root = re.sub(rf'(/{app.config.version})?(/{app.config.language})?$', '', app.outdir)
+            root_ = re.sub(rf'(/{app.config.version})?(/{app.config.language})?$', '', app.outdir)
         # If the canonical version is not set, assume that the project has a single version
-        _canonical_version = app.config.canonical_version or app.config.version
+        canonical_version_ = app.config.canonical_version or app.config.version
-        _version = _version or app.config.version
+        version_ = version_ or app.config.version
-        _lang = _lang or app.config.language or 'en'
+        lang_ = lang_ or app.config.language or 'en'
-        _canonical_page = f'{pagename}.html'
+        canonical_page_ = f'{pagename}.html'
 
         # legal translations have different URLs schemes as they are not managed on transifex
         # e.g. FR translation of /terms/enterprise => /fr/terms/enterprise_fr
         if pagename.startswith('legal/terms/'):
-            if _lang in legal_translations and not pagename.endswith(f"_{_lang}"):
+            if lang_ in legal_translations and not pagename.endswith(f"_{lang_}"):
                 # remove language code for current translation, set target one
-                _page = re.sub("_[a-z]{2}$", "", pagename)
+                page_ = re.sub("_[a-z]{2}$", "", pagename)
-                if 'terms/i18n' not in _page:
+                if 'terms/i18n' not in page_:
-                    _page = _page.replace("/terms/", "/terms/i18n/")
+                    page_ = page_.replace("/terms/", "/terms/i18n/")
-                _canonical_page = f'{_page}_{_lang}.html'
+                canonical_page_ = f'{page_}_{lang_}.html'
-            elif _lang == 'en' and pagename.endswith(tuple(f"_{l}" for l in legal_translations)):
+            elif lang_ == 'en' and pagename.endswith(tuple(f"_{l}" for l in legal_translations)):
                 # remove language code for current translation, link to original EN one
-                _page = re.sub("_[a-z]{2}$", "", pagename)
+                page_ = re.sub("_[a-z]{2}$", "", pagename)
-                _canonical_page = f'{_page.replace("/i18n/", "/")}.html'
+                canonical_page_ = f'{page_.replace("/i18n/", "/")}.html'
 
         if app.config.is_remote_build:
-            _canonical_page = _canonical_page.replace('index.html', '')
+            canonical_page_ = canonical_page_.replace('index.html', '')
 
-        return f'{_root}' \
+        return f'{root_}' \
-               f'{f"/{_version}" if app.config.versions else ""}' \
+               f'{f"/{version_}" if app.config.versions else ""}' \
-               f'{f"/{_lang}" if _lang != "en" else ""}' \
+               f'{f"/{lang_}" if lang_ != "en" else ""}' \
-               f'/{_canonical_page}'
+               f'/{canonical_page_}'
 
-    _canonicalize()
+    canonicalize()
-    _versionize()
+    versionize()
-    _localize()
+    localize()

content/administration/hosting.rst

@@ -23,7 +23,7 @@ To Odoo Online
 #. Create a :ref:`duplicate of the database <on-premise/duplicate>`.
 #. In this duplicate, uninstall all **non-standard apps**.
 #. Use the database manager to grab a *dump with filestore*.
-#. `Submit a support ticket <https://www.odoo.com/help>`_ including the following:
+#. `Create a support ticket <https://www.odoo.com/help-form>`_ including the following:
 
    - your **subscription number**,
    - the **URL** you want to use for the database (e.g., `company.odoo.com`), and
@@ -33,14 +33,14 @@ To Odoo Online
    issues during the process, Odoo might contact you.
 
 .. note::
-   If you have time constraints, `submit a support ticket <https://www.odoo.com/help>`_ as soon as
+   If you have time constraints, `create a support ticket <https://www.odoo.com/help-form>`_ as soon
-   possible to schedule the transfer.
+   as possible to schedule the transfer.
 
 To Odoo.sh
 ----------
 
-Follow the instructions found in :ref:`the Import your database section
+Follow the instructions found in :ref:`the Import a database section <odoo-sh/create/import>` of the
-<odoo_sh_import_your_database>` of the Odoo.sh *Create your project* documentation.
+Odoo.sh *Create a project* documentation.
 
 Transferring an Odoo Online database
 ====================================
@@ -56,19 +56,20 @@ Transferring an Odoo Online database
       17.0.
 
    .. tip::
-      Click the gear icon (:guilabel:`⚙`) next to the database name on the `Odoo Online database
+      Click the :icon:`fa-gear` (:guilabel:`gear`) button next to the database name on the `Odoo
-      manager <https://www.odoo.com/my/databases/>`_ to display its version number.
+      Online database manager <https://www.odoo.com/my/databases/>`_ to display its version number.
 
    .. warning::
       If there is an active Odoo subscription linked to the database being migrated, reach out to
-      the Customer Service Manager or `submit a support ticket <https://www.odoo.com/help>`_  to
+      the Customer Service Manager or `contact Odoo support <https://www.odoo.com/help>`_ to
       complete the subscription transfer.
 
 To on-premise
 -------------
 
-#. Sign in to `the Odoo Online database manager <https://www.odoo.com/my/databases/>`_ and click the
+#. Download a database backup by signing in to `the Odoo Online database manager
-   gear icon (:guilabel:`⚙`) next to the database name to :guilabel:`Download` a backup. If the
+   <https://www.odoo.com/my/databases/>`_, clicking the :icon:`fa-gear` (:guilabel:`gear`) button
+   next to the database name, then selecting :icon:`fa-cloud-download` :guilabel:`Download`. If the
    download fails due to the file being too large, `contact Odoo support
    <https://www.odoo.com/help>`_.
 #. Restore the database from the database manager on your local server using the backup.
@@ -76,12 +77,13 @@ To on-premise
 To Odoo.sh
 ----------
 
-#. Sign in to `the Odoo Online database manager <https://www.odoo.com/my/databases/>`_ and click the
+#. Download a database backup by signing in to `the Odoo Online database manager
-   gear icon (:guilabel:`⚙`) next to the database name to :guilabel:`Download` a backup. If the
+   <https://www.odoo.com/my/databases/>`_, clicking the :icon:`fa-gear` (:guilabel:`gear`) button
+   next to the database name, then selecting :icon:`fa-cloud-download` :guilabel:`Download`. If the
    download fails due to the file being too large, `contact Odoo support
    <https://www.odoo.com/help>`_.
-#. Follow the instructions found in :ref:`the Import your database section
+#. Follow the instructions found in :ref:`the Import a database section <odoo-sh/create/import>` of
-   <odoo_sh_import_your_database>` of the Odoo.sh *Create your project* documentation.
+   the Odoo.sh *Create a project* documentation.
 
 Transferring an Odoo.sh database
 ================================
@@ -93,7 +95,7 @@ To Odoo Online
    Odoo Online is *not* compatible with **non-standard apps**.
 
 #. Uninstall all **non-standard apps** in a staging build before doing it in the production build.
-#. `Create a support ticket <https://www.odoo.com/help>`_ including the following:
+#. `Create a support ticket <https://www.odoo.com/help-form>`_ including the following:
 
    - your **subscription number**,
    - the **URL** you want to use for the database (e.g., `company.odoo.com`),
@@ -106,8 +108,8 @@ To Odoo Online
    issues during the process, Odoo might contact you.
 
 .. note::
-   - If you have time constraints, `submit a support ticket <https://www.odoo.com/help>`_ as soon as
+   - If you have time constraints, `create a support ticket <https://www.odoo.com/help-form>`_ as
-     possible to schedule the transfer.
+     soon as possible to schedule the transfer.
    - Select the **region** closest to most of your users to reduce latency.
    - Future **administrator(s)** must have an Odoo.com account.
    - The **date and time** you want the database to be up and running are helpful to organize the
@@ -117,5 +119,5 @@ To Odoo Online
 To on-premise
 -------------
 
-#. Download a :ref:`backup of your Odoo.sh production database <odoo_sh_branches_backups>`.
+#. Download a :ref:`backup of your Odoo.sh production database <odoo-sh/branches/tabs/backups>`.
 #. Restore the database from the database manager on your local server using the backup.

content/administration/mobile.rst

@@ -62,6 +62,6 @@ The Odoo mobile apps are available for download on the `Google Play Store
 <https://apps.apple.com/app/odoo/id1272543640>`_.
 
 .. important::
-   The iOS app cannot be updated and will be deprecated at some point in the future.
+   The iOS app might not be updated and might be deprecated at some point in the future.
 
-While the store apps support multi-accounts, they are not compatible with SS0 authentication.
+While the store apps support multi-accounts, they are not compatible with SSO authentication.

content/administration/odoo_accounts.rst

@@ -2,8 +2,33 @@
 Odoo.com accounts
 =================
 
-This documentation is dedicated to edits made to an Odoo.com account. The following processes
+This document describes how to edit and manage an Odoo.com account, including adding a client
-describe how to delete an Odoo.com account, and how to change the password on an Odoo.com account.
+database, deleting an account, resetting a password, and enabling two-factor authentication.
+
+Grant users access to database
+==============================
+
+A database can be linked to an Odoo.com account that was created by a different Odoo.com account.
+This allows the database to appear in the *My Databases* page of the account. To do so, the
+client Odoo.com account needs to be added to the database as a user.
+
+First, sign in to the Odoo.com account that created the client database. In the main Odoo dashboard
+of the database, navigate to the **Settings** app, and click :guilabel:`Manage Users` in the
+:guilabel:`Users` section. Click the :guilabel:`New` button, and enter a name in the
+:guilabel:`Name` field for this user. Next, enter the email address used to register the desired
+Odoo.com account in the :guilabel:`Email` field. Navigate back to :guilabel:`Settings` using the
+breadcrumbs, and a pop-up window titled :guilabel:`Users Invitations` appears, with a warning that
+adding additional users will increase the amount of the subscription.
+
+Click :guilabel:`Confirm`, and the :guilabel:`Users` list appears. An invitation is automatically
+sent to the email address. Once confirmed, the client database now appears in the **My Databases**
+page of the target Odoo.com account.
+
+.. tip::
+   To provide full access to the database for this user, set the :guilabel:`Dashboard` field under
+   the :guilabel:`Productivity` header to :guilabel:`Admin`. Next, set the
+   :guilabel:`Administration` field under the :guilabel:`Administration` header to
+   :guilabel:`Settings`.
 
 Delete Odoo.com account
 =======================
@@ -23,7 +48,7 @@ Edit Security Settings --> Delete Account`. It can also be accessed by going to
 Upon clicking the :guilabel:`Delete Account` button, a pop-up window appears, requesting
 confirmation for the account deletion.
 
-.. image:: odoo_account/delete-account.png
+.. image:: odoo_accounts/delete-account.png
    :align: center
    :alt: Clicking on the Delete Account button will populate a window verifying the change.
 

content/administration/odoo_online.rst

@@ -2,150 +2,179 @@
 Odoo Online
 ===========
 
-`Odoo Online <https://www.odoo.com/trial>`_ provides private databases which are fully managed and
+`Odoo Online <https://www.odoo.com/trial>`_ offers private databases hosted and managed by Odoo.
-hosted by Odoo. It can be used for long-term production or to test Odoo thoroughly, including
+Odoo Online databases can be accessed using any web browser and do not require a local installation.
-customizations that don't require code.
+They can be used for long-term production or to thoroughly test Odoo, including customizations that
+do not require custom code.
+
+.. tip::
+   To quickly try out Odoo, shared `demo databases <https://demo.odoo.com>`_ are available for
+   testing. No registration is required; however, each database is only available for a few hours.
 
 .. note::
-   Odoo Online is incompatible with custom modules or the Odoo App Store.
+   Odoo Online is incompatible with custom modules or modules from the `Odoo Apps Store
+   <https://apps.odoo.com/apps>`_.
 
-Odoo Online databases are accessed using any web browser and do not require a local installation.
+.. _odoo-online/database-manager:
 
-To quickly try out Odoo, shared `demo <https://demo.odoo.com>`_ instances are available. No
+Database manager
-registration is required, but each instance only lives for a few hours.
+================
 
-Database management
+To manage an Odoo Online database, open to the `database manager
-===================
+<https://www.odoo.com/my/databases>`_ and sign in as the database administrator.
 
-To manage a database, go to the `database manager <https://www.odoo.com/my/databases>`_ and sign in
+.. _odoo-online/domain-names:
-as the database administrator.
-
-All the main database management options are available by clicking the database name, except the
-upgrade option, which can be accessed by clicking the **arrow in a circle** icon next to the
-database name. It is only displayed if an upgrade is available.
-
-.. image:: odoo_online/database-manager.png
-   :alt: Accessing the database management options
-
-- :ref:`odoo_online/upgrade`
-- :ref:`odoo_online/duplicate`
-- :ref:`odoo_online/rename`
-- :ref:`odoo_online/download`
-- :ref:`odoo_online/domains`
-- :ref:`odoo_online/tags`
-- :ref:`odoo_online/delete`
-- :ref:`odoo_online/contact-support`
-- :ref:`odoo_online/users`
-
-.. _odoo_online/upgrade:
-
-Upgrade
-=======
-
-Trigger a database upgrade.
-
-.. seealso::
-   For more information about the upgrade process, check out the :ref:`Odoo Online upgrade
-   documentation <upgrade-request-test>`.
-
-.. _odoo_online/duplicate:
-
-Duplicate
-=========
-
-Create an exact copy of the database, which can be used to perform testing without compromising
-daily operations.
-
-.. important::
-   - By checking :guilabel:`For testing purposes`, all external actions (emails, payments, delivery
-     orders, etc.) are disabled by default on the duplicated database.
-   - Duplicated databases expire automatically after 15 days.
-   - A maximum of five duplicates can be made per database. Under extraordinary circumstances,
-     contact `support <https://www.odoo.com/help>`_ to raise the limit.
-
-.. _odoo_online/rename:
-
-Rename
-======
-
-Rename the database and its URL.
-
-.. _odoo_online/download:
-
-Download
-========
-
-Download a ZIP file containing a backup of the database.
-
-.. note::
-   Databases are backed up daily as per the `Odoo Cloud Hosting SLA
-   <https://www.odoo.com/cloud-sla>`_.
-
-.. _odoo_online/domains:
 
 Domain names
-============
+------------
 
-Use a custom :doc:`domain name </applications/websites/website/configuration/domain_names>` to
+:doc:`Configure a custom domain name <../applications/websites/website/configuration/domain_names>`
-access the database via another URL.
+by selecting a database and clicking :icon:`fa-globe` :guilabel:`Domain Names`.
 
 .. tip::
-   You can :ref:`register a domain name for free <domain-name/register>`.
+   :ref:`Register a domain name for free <domain-name/register>`.
 
-.. _odoo_online/tags:
+.. _odoo-online/tags:
 
 Tags
-====
+----
 
-Add tags to easily identify and sort your databases.
+Add tags to identify and sort databases by selecting a database and clicking :icon:`fa-tags`
+:guilabel:`Tags`. In the dialog box, enter a tag, click the :icon:`fa-plus-circle`
+(:guilabel:`plus`) button, and click :guilabel:`Save`.
 
 .. tip::
-   You can search for tags in the search bar.
+   Search for tags in the :icon:`fa-search` search bar at the top right.
 
-.. _odoo_online/delete:
+.. _odoo-online/hide:
 
-Delete
+Hide
-======
+----
 
-Delete a database instantly.
+Permanently hide the database from the database manager by selecting it and clicking
+:icon:`fa-eye-slash` :guilabel:`Hide`. In the dialog box, click :guilabel:`Yes, I don't need it
+anymore`.
 
-.. danger::
+.. Note::
-   Deleting a database means that all data is permanently lost. The deletion is instant and applies
+   It is possible to access a hidden database through its URL.
-   to all users. It is recommended to create a backup of the database before deleting it.
 
-Carefully read the warning message and only proceed if the implications of deleting a database are
+.. _odoo-online/manage:
-fully understood.
 
-.. image:: odoo_online/delete.png
+Manage
-   :alt: The warning message displayed before deleting a database
+------
+
+Access all other database management options by selecting it and clicking :icon:`fa-gears`
+:guilabel:`Manage`.
+
+Switch plans
+~~~~~~~~~~~~
+
+Switch `pricing plans <https://www.odoo.com/pricing>`_ by clicking :guilabel:`Switch` under the
+desired plan.
+
+.. _odoo-online/upgrade:
+
+Upgrade
+~~~~~~~
+
+Launch a :ref:`database upgrade <upgrade-request-test>` by clicking :guilabel:`Upgrade`.
 
 .. note::
-   - Only an administrator can delete a database.
+   This option is only displayed when an upgrade is available.
-   - The database name is immediately made available to anyone.
-   - Deleting a database if it has expired or is linked to a subscription is impossible. In that
-     case, contact `Odoo Support <https://www.odoo.com/help>`_.
 
-.. _odoo_online/contact-support:
+.. _odoo-online/rename:
 
-Contact us
+Rename
-==========
+~~~~~~
 
-Access the `Odoo.com support page <https://www.odoo.com/help>`_ with the database's details already
+Rename and change the URL of a database by clicking :guilabel:`Rename`. In the dialog box, enter a
-pre-filled.
+:guilabel:`New name` and click :guilabel:`Rename`.
 
-.. _odoo_online/users:
+.. _odoo-online/duplicate:
 
-Invite / remove users
+Duplicate
-=====================
+~~~~~~~~~
 
-To invite users, fill out the new user's email address and click :guilabel:`Invite`. To add multiple
+Create a copy of the database by clicking :guilabel:`Duplicate`. In the dialog box, enter a
-users, click :guilabel:`Add more users`.
+:guilabel:`New name` and click :guilabel:`Duplicate`.
 
-.. image:: odoo_online/invite-users.png
+.. important::
-   :alt: Inviting a user on a database
+   - By default, the :guilabel:`For testing purposes` option is enabled. It disables all external
+     actions (emails, payments, delivery orders, etc.) on the duplicated database.
+   - Duplicates expire after 15 days.
+   - A maximum of five duplicates can be created per database. Under extraordinary circumstances,
+     contact `Odoo Support <https://www.odoo.com/help>`_ to extend the limit.
 
-To remove users, select them and click :guilabel:`Remove`.
+.. _odoo-online/download:
 
-.. seealso::
+Download a backup
-   - :doc:`/applications/general/users`
+~~~~~~~~~~~~~~~~~
-   - :doc:`odoo_accounts`
+
+Download a ZIP file containing a database backup by clicking :guilabel:`Download Backup`.
+
+.. note::
+   - Databases are backed up daily as per the `Odoo Cloud Hosting SLA
+     <https://www.odoo.com/cloud-sla>`_.
+   - If the :guilabel:`Download Backup` option is disabled, it means the database is too large to be
+     downloaded using the database manager. Contact `Odoo Support <https://www.odoo.com/help>`_ to
+     request an alternative download solution.
+
+.. _odoo-online/activity-logs:
+
+View admin activity logs
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+View the logs of all actions taken by Odoo employees or the database administrator on the database
+by clicking :guilabel:`View Admin Activity Logs`.
+
+.. note::
+   Actions taken by Odoo employees are typically the result of requests submitted to Odoo support,
+   done within the context of a quick start project, or necessary to maintain the database.
+
+.. _odoo-online/transfer-ownership:
+
+Transfer ownership
+~~~~~~~~~~~~~~~~~~
+
+Create a support ticket to request a database ownership transfer by clicking :guilabel:`Transfer
+Ownership`.
+
+.. _odoo-online/delete:
+
+Delete
+~~~~~~
+
+Delete the database and close its related subscription by clicking :guilabel:`Delete`. In the dialog
+box, click :guilabel:`Delete`.
+
+.. danger::
+   All the database's data will be deleted instaneously for all users and **cannot be restored**. It
+   is recommended to :ref:`download a backup <odoo-online/download>` before deleting a database.
+
+.. note::
+   After deletion, the database's name becomes available to anyone.
+
+.. _odoo-online/web-services:
+
+Web services
+============
+
+To retrieve a list of all databases displayed under the `database manager
+<https://www.odoo.com/my/databases>`_ programmatically, call the `list` method of the
+`odoo.database` model via an :doc:`external JSON-2 API <../developer/reference/external_api>` call.
+
+.. example::
+   .. code:: python
+
+      import requests
+
+      APIKEY = "your_apikey"
+
+      requests.post(
+          "https://www.odoo.com/json/2/odoo.database/list",
+          headers={
+              "Authorization": f"bearer {APIKEY}",
+              "X-Odoo-Database": "openerp",
+          }
+          json={},
+      )

content/administration/odoo_sh.rst

@@ -1,12 +1,16 @@
-:nosearch:
+:show-content:
+:show-toc:
 
 =======
 Odoo.sh
 =======
 
+Odoo.sh is the official cloud platform for hosting and managing Odoo applications. It offers a
+range of features such as web shell, module dependencies, continuous integration, and SSH access.
 
 .. toctree::
+   :titlesonly:
 
-    odoo_sh/overview
+   odoo_sh/getting_started
-    odoo_sh/getting_started
+   odoo_sh/first_module
-    odoo_sh/advanced
+   odoo_sh/advanced

content/administration/odoo_sh/advanced/containers.rst

@@ -147,7 +147,7 @@ with a browser, but you can for instance:
 
 .. code-block:: bash
 
-  $  odoo-bin -i sale --without-demo=all --stop-after-init
+  $  odoo-bin -i sale --stop-after-init
 
 * update a module,
 
@@ -163,7 +163,6 @@ with a browser, but you can for instance:
 
 In the above commands, the argument:
 
-* ``--without-demo=all`` prevents demo data to be loaded for all modules
 * ``--stop-after-init`` will immediately shutdown the server instance after it completed the operations you asked.
 
 More options are available and detailed in the

content/administration/odoo_sh/first_module.rst

@@ -7,7 +7,7 @@ Overview
 
 This chapter helps you to create your first Odoo module and deploy it in your Odoo.sh project.
 
-This tutorial requires :ref:`you created a project on Odoo.sh <odoosh-gettingstarted-create>`, and
+This tutorial requires you created a project on Odoo.sh, and
 you know your Github repository's URL.
 
 Basic use of Git and Github is explained.
@@ -85,7 +85,7 @@ From the Odoo.sh editor, in a terminal:
 
   $ odoo-bin scaffold my_module ~/src/user/
 
-Or, from your computer, if you have an :doc:`installation of Odoo <../../on_premise/source>`:
+Or, from your computer, if you have an installation of Odoo:
 
 .. code-block:: bash
 
@@ -304,6 +304,8 @@ you have to install it manually as explained in the
 :ref:`above section about installing your module in staging databases
 <odoosh-gettingstarted-firstmodule-productiondata-install>`.
 
+.. _odoo-sh/module/add:
+
 Add a change
 ============
 
@@ -481,15 +483,16 @@ Add
 .. code-block:: python
 
   @api.model
-  def create(self, values):
+  def create(self, vals_list):
-      if 'name' in values:
+      for vals in vals_list:
-          values['name'] = unidecode(values['name'])
+          if 'name' in vals:
-      return super(my_module, self).create(values)
+              vals['name'] = unidecode(vals['name'])
+      return super().create(vals_list)
 
-  def write(self, values):
+  def write(self, vals):
-      if 'name' in values:
+      if 'name' in vals:
-          values['name'] = unidecode(values['name'])
+          vals['name'] = unidecode(vals['name'])
-      return super(my_module, self).write(values)
+      return super().write(vals)
 
 Adding a Python dependency requires a module version increase for the platform to install it.
 

content/administration/odoo_sh/getting_started.rst

@@ -1,8 +1,51 @@
-:nosearch:
+:show-content:
 
-===========
+===============
-Get started
+Getting started
-===========
+===============
+
+Main components
+---------------
+
+When working with Odoo.sh, it is important to understand the main components involved. While they
+are all interconnected, each one plays a distinct role in the development and deployment of Odoo
+applications:
+
+- **GitHub repository**: a version-controlled space where the Odoo applications' source code is
+  stored. It tracks every change, supports collaboration, and can be either public or private.
+
+  .. image:: getting_started/github-repository.png
+     :alt: Example of a GitHub repository
+
+- **Odoo.sh project**: a Platform as a Service (PaaS) that integrates with GitHub and enables
+  streamlined development, testing, and deployment of Odoo applications. It includes tools such as
+  automated backups, staging environments, and continuous integration pipelines.
+
+  .. image:: getting_started/odoo-sh-project.png
+     :alt: Example of an Odoo.sh project
+
+- **Odoo database**: a database stores all the operational data used and generated by Odoo
+  applications, such as business records, configurations, and user data.
+
+  .. image:: getting_started/odoo-database.png
+     :alt: Example of an Odoo database
+
+Together, they form a cohesive pipeline from code development to a live business use.
+
+User types
+----------
+
+Odoo.sh involves different types of users, each with a specific role in the project lifecycle:
+
+- GitHub users: developers with access to the GitHub repository linked to the Odoo.sh project.
+  Access to the repository does not automatically make someone a collaborator on the Odoo.sh
+  project.
+
+- Odoo.sh collaborators: individuals managing the Odoo.sh project. Each collaborator must be
+  linked to a GitHub user. However, collaborators are not the same as database users.
+
+- Database users: end-users of the deployed Odoo database. They interact with the live system but
+  are not involved in development or project management.
 
 .. toctree::
    :titlesonly:
@@ -13,4 +56,3 @@ Get started
    getting_started/status
    getting_started/settings
    getting_started/online-editor
-   getting_started/first_module

content/administration/odoo_sh/getting_started/builds.rst

@@ -1,124 +1,137 @@
-
-.. _odoosh-gettingstarted-builds:
-
 ======
 Builds
 ======
 
+In Odoo.sh, a build is a database loaded by an Odoo server (`odoo/odoo
+<https://github.com/odoo/odoo>`_ and `odoo/enterprise <https://github.com/odoo/enterprise>`_)
+running on a specific revision of your project repository in a containerized environment. Its
+purpose is to test the proper behavior of the server, the database, and the features associated with
+that revision.
+
+.. _odoo-sh/builds/overview:
+
 Overview
 ========
 
-In Odoo.sh, a build is considered as a database loaded by an Odoo server
+.. image:: builds/builds-overview.png
-(`odoo/odoo <https://github.com/odoo/odoo>`_ & `odoo/enterprise
+   :alt: Overiew of the builds
-<https://github.com/odoo/enterprise>`_) running on a specific revision of your project repository in
-a containerized environment. Its purpose is to test the well-behavior of the server, the database
-and the features with this revision.
 
-.. image:: builds/interface-builds.png
+In the :guilabel:`Builds` overview, a row represents a branch, and a cell within that row represents
-   :align: center
+a build of that branch.
 
-In this view, a row represents a branch, and a cell of a row represents a build of this branch.
+Most builds are created after pushes to your GitHub repository branches. They can also be created
+through other operations, such as importing a database on Odoo.sh or requesting a rebuild for a
+branch in your project.
 
-Most of the time, builds are created following pushes on your Github repository branches.
+Builds can have three possible statuses:
-They can be created as well when you do other operations,
-such as importing a database on Odoo.sh or asking a rebuild for a branch in your project.
 
-A build is considered successful if no errors or warnings come up during its creation.
+- A build is considered **successful** if no errors or warnings occur during its creation.
-A successful build is highlighted in green.
+  Successful builds are highlighted in **green**.
+- A build is considered **almost successful** if warnings occur, but there are no errors. Almost
+  successful builds are highlighted in **yellow**.
+- A build is considered **failed** if errors occur during its creation. Failed builds are
+  highlighted in **red**.
 
-A build is considered failed if errors come up during its creation.
+.. note::
-A failed build is highlighted in red.
+   Builds do not always create a database from scratch. For instance, when pushing a change on the
+   production branch, the created build starts the server with your new revision and tries to load
+   the current production database on it.
 
-If warnings come up during the creation, but there are no errors, the build is considered almost
+.. _odoo-sh/builds/stages:
-successful. It is highlighted in yellow to notify the developer warnings were raised.
-
-Builds do not always create a database from scratch. For instance, when pushing a change on the
-production branch, the build created just starts the server with your new revision and tries to load
-the current production database on it. If no errors come up, the build is considered successful, and
-otherwise failed.
 
 Stages
 ======
 
+.. _odoo-sh/builds/stages/production:
+
 Production
 ----------
 
-The first build of a production branch creates a database from scratch.
+The first build of a production branch creates a database from scratch. If this build is successful,
-If this build is successful, this database is considered as the production database of your project.
+this database will become the production database of your project.
 
-From then, pushes on the production branch will create new builds that attempt to load the database
+From then on, pushes to the production branch will create new builds that attempt to load the
-using a server running with the new revision.
+database using a server running the new revision.
 
-If the build is successful, or has warnings but no errors, the production database will now run with
+If the build is successful or almost successful, the production database will run with this build
-this build, along with the revision associated to this build.
+and its associated revision.
 
-If the build fails to load or update the database, then the previous successful build is re-used to
+If the build fails to load or update the database, the previous successful build is reused to load
-load the database, and therefore the database will run using a server running with the previous
+the database. In that case, the database continues to run using the previous successful revision.
-successful revision.
 
-The build used to run the production database is always the first of the builds list. If a build
+.. note::
-fails, it is put after the build currently running the production database.
+   The build used to run the production database is always the first in the builds list. If a build
+   fails, it is placed after the build currently running the production database.
+
+.. _odoo-sh/builds/stages/staging:
 
 Staging
 -------
 
-Staging builds duplicate the production database,
+Staging builds duplicate the production database and attempt to load this copy using the revisions
-and try to load this duplicate with the revisions of the staging branches.
+of the staging branches.
 
-Each time you push a new revision on a staging branch, the build created uses a new copy of the
+Each time you push a new revision to a staging branch, the resulting build uses a fresh copy of the
-production database. The databases are not re-used between builds of the same branch. This ensures:
+production database. Databases are not reused between builds of the same branch. This ensures that:
 
-* staging builds use databases that are close to what the production looks like, so you do not make
+- Staging builds use databases that closely match the current production state, so your tests are
-  your tests with outdated data,
+  not performed on outdated data.
+- You can freely experiment within a staging database. When you want to start over with a new copy
+  of the production database, you can request a rebuild.
 
-* you can play around as much as you want in the same staging database, and you can then ask for a
+However, this also means that if you make configuration changes in a staging database and do not
-  rebuild when you want to restart with a new copy of the production.
+apply them in production, those changes will not be present in the next build of the same staging
+branch.
 
-Nevertheless, this means that if you make configuration changes in staging databases and do not
+.. _odoo-sh/builds/stages/development:
-apply them in the production, they will not be passed on the next build of the same staging branch.
 
 Development
 -----------
 
-Development builds create new databases, load the demo data and run the unit tests.
+Development builds create new databases, load the demo data, and run the unit tests.
 
-A build will be considered failed and highlighted in red if tests fail during the installation,
+A build will be considered failed if tests fail during installation, as they are designed to raise
-as they are meant to raise errors if something wrong occurs.
+errors when something is wrong.
 
-If all tests pass, and there is no error, the build will be considered successful.
+If all tests pass and no errors occur, the build is considered successful.
 
-According to the list of modules to install and test, a development build can take up to 1 hour to
+.. note::
-be ready. This is due to the large number of tests set in the default Odoo modules suite.
+   Depending on the list of modules to install and test, a development build can take up to one hour
+   to be ready. This is due to the large number of tests included in the default Odoo module suite.
+
+.. _odoo-sh/builds/stages/features:
 
 Features
 ========
 
-The production branch will always appear first, and then the other branches are ordered by last
+The production branch always appears first. Other branches are ordered by the time of their last
-build created. You can filter out the branches.
+created build. The stage highlighted in purple corresponds to the stage selected in the
+:guilabel:`Branches` menu.
 
-.. image:: builds/interface-builds-branches.png
+.. tip::
-   :align: center
+   You can filter branches using the search bar.
 
-For each branch, you can access the last build's database using the *Connect* link and jump to the
+.. image:: builds/branches-menu.png
-branch code using the *Github* link. For other branches than the production, you can create a new
+   :alt: The branches menu
-build which will use the latest revision of the branch using the link *rebuild*. This last link is
-not available when there is already a build in progress for the branch.
 
-.. image:: builds/interface-builds-build.png
+For each branch, you can:
-   :align: center
 
-For each build, you can access the revision changes using the button with the Github icon. You can
+- Access the latest build's database by clicking :guilabel:`Connect`.
-access the build's database as the administrator using the *Connect* button. Also, you can access
+- Jump to the branch's code by clicking :guilabel:`Github`.
-the database with another user using the *Connect as* button, in the dropdown menu of the *Connect*
+- Create a new build by clicking :guilabel:`Rebuild`. It uses the latest revision of the branch (it
-button.
+  is not available if a build is already in progress for that branch).
 
-.. _odoosh-gettingstarted-builds-download-dump:
+For each build, you can:
 
-.. image:: builds/interface-builds-build-dropdown.png
+- View the revision changes by clicking the :icon:`fa-github` (:guilabel:`GitHub`) icon.
-   :align: center
+- Access the build's database as the administrator by clicking :guilabel:`Connect` or as another
+  user by clicking the :icon:`fa-caret-down` (:guilabel:`More Actions`) button next to
+  :guilabel:`Connect` and selecting :guilabel:`Connect as`.
+- Access the same tools as in the branches view by clicking the :icon:`fa-caret-down`
+  (:guilabel:`More Actions`) button next to :guilabel:`Connect` and selecting :guilabel:`Logs`,
+  :guilabel:`Web Shell`, :guilabel:`Editor`, :guilabel:`Outgoing e-mails` (for the staging and
+  development stages), :guilabel:`Monitoring`, and :guilabel:`Download DB dump` (for the production
+  and staging stages).
 
-.. _odoosh-gettingstarted-builds-dropdown-menu:
+.. image:: builds/builds-options.png
-
+   :alt: A build's options
-In the dropdown menu of the build, you can access the same features than in :ref:`the branches view
-<odoosh-gettingstarted-branches-tabs>`: *Logs*, *Web Shell*, *Editor*, *Outgoing e-mails*. You also
-have the possibility to *Download a dump* of the build's database.

content/administration/odoo_sh/getting_started/create.rst

@@ -1,205 +1,192 @@
+================
+Create a project
+================
 
-.. _odoosh-gettingstarted-create:
+Deploy a platform
-
-===================
-Create your project
-===================
-
-Deploy your platform
-====================
-
-Go to `Odoo.sh <https://www.odoo.sh/>`_ and hit the *Deploy your platform* button.
-
-.. image:: create/deploy.png
-   :align: center
-
-Sign in with Github
-===================
-
-Sign in with your Github account. If you do not have an account yet, hit the *Create an account*
-link.
-
-.. image:: create/github-signin.png
-   :align: center
-
-Authorize Odoo.sh
 =================
 
-Grant Odoo.sh the required accesses to your account by clicking the *Authorize* button.
+#. Visit `Odoo.sh <https://www.odoo.sh>`_ and click :guilabel:`Deploy your platform`.
 
-.. image:: create/github-authorize.png
+   .. image:: create/deploy-button.png
-   :align: center
+      :alt: The Deploy your platform button on Odoo.sh
 
-Odoo.sh basically needs:
+#. Sign in with a `GitHub <https://github.com>`_ account.
 
-* to know your Github login and email,
+   .. image:: create/github-sign-in.png
-* to create a new repository in case you decide to start from scratch,
+      :alt: Signing in to GitHub
-* to read your existing repositories, including the ones of your organizations, in case you want to
-  start from an existing repository,
-* to create a webhook to be notified each time you push changes,
-* to commit changes to make your deployment easier, merging branches or adding new `submodules
-  <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_ for example.
 
-Submit your project
+#. Authorize Odoo.sh by clicking :guilabel:`Authorize odoo` twice.
-===================
 
-Choose if you want to start from scratch by creating a new repository, or if you want to use an
+   .. image:: create/github-authorize.png
-existing repository.
+      :alt: Granting Odoo.sh permissions to perform actions and access data on GitHub
 
-Then, choose a name or select the repository you want to use.
+   .. image:: create/github-authorize.png
+      :alt: Granting Odoo.sh additional permissions to perform actions and access data on GitHub
 
-Choose the Odoo version you want to use. If you plan to import an existing database or an existing
+   .. note::
-set of applications, you might need to choose the according version. If you start from scratch, use
+      Odoo.sh requests GitHub to:
-the latest version.
 
-Enter your *subscription code*. This is also called *subscription referral*, *contract number* or
+      - Access your GitHub login and email.
-*activation code*.
+      - Create a new repository, in case you start from scratch.
+      - Access existing repositories, including organization ones, in case you start from an
+        existing repository.
+      - Create a webhook to notify you each time changes are pushed.
+      - Commit changes for easier deployment.
 
-It should be the code of your Enterprise subscription that includes Odoo.sh.
+#. Fill in the :guilabel:`Deploy your platform` form and click :guilabel:`Deploy`:
 
-Partners can use their partnership codes to start a trial. Should their clients start a project,
+   - :guilabel:`Github repository`: to create a new repository, choose :guilabel:`New repository`
-they ought to get an Enterprise subscription including Odoo.sh and use its subscription code. The
+     and enter a name; to use an existing one, choose :guilabel:`Existing repository` and select it.
-partner will get 50% of the amount back as commission. Contact your sales representative or account
+   - :guilabel:`Odoo Version`: select the major version of Odoo you want to use.
-manager in order to get it.
 
-When submitting the form, if you are notified your subscription is not valid, it either means:
+     .. tip::
+        - Use the latest major version of Odoo version when creating a new repository. If you are
+          planning to import an existing database or applications, it might be required that their
+          versions match.
+        - If you are starting on Odoo Online and plan to migrate to Odoo.sh later, create your
+          database using `odoo.com/start-lts <https://www.odoo.com/start-lts>`_ to ensure
+          compatibility, as minor versions are not supported by Odoo.sh.
 
-* it is not an existing subscription,
+   - :guilabel:`Subscription Code`: enter your Odoo Enterprise subscription code that includes
-* it is not a partnership subscription,
+     Odoo.sh. It is also sometimes called the *subscription referral*, *contract number*, or
-* it is an enterprise subscription, but which does not include Odoo.sh,
+     *activation code*.
-* it is neither a partnership subscription or an enterprise subscription (e.g. an online
-  subscription).
 
-In case of doubt with your subscription, please contact the `Odoo support
+      .. tip::
-<https://www.odoo.com/help>`_.
+         Partners can use their partnership codes to initiate a trial (trial builds are limited to 1
+         GB storage and two staging). If a client proceeds to start a project, they must subscribe
+         to an Odoo Enterprise plan that includes Odoo.sh hosting and use their subscription code.
 
-.. image:: create/deploy-form.png
+   - :guilabel:`Hosting location`: select the region where your platform will be hosted.
-   :align: center
 
-You're done !
+   .. image:: create/deploy-form.png
-=============
+      :alt: The Deploy your platform form
 
-You can start using Odoo.sh. Your first build is about to be created. You will soon be able to
+.. _odoo-sh/create/import:
-connect to your first database.
 
-.. image:: create/deploy-done.png
+Import a database
-   :align: center
+=================
 
-.. _odoo_sh_import_your_database:
+Once your platform is deployed, you can import a database into your Odoo.sh project, provided it
+uses a :doc:`supported version <../../supported_versions>` of Odoo.
 
-Import your database
+.. note::
-====================
+   Due to `Odoo's backup policy <https://www.odoo.com/cloud-sla>`_, the import process requires
+   **four times** the size of your database dump in available storage. For example, a 10 GB dump
+   file will require at least 40 GB of available space. We recommend allocating **more than four
+   times×** the dump size temporarily, then reducing storage after the import is complete.
 
-You can import your database in your Odoo.sh project as long as it is in a :doc:`supported version
+   If your project is a trial created with a partnership code, you can only import database dumps up
-</administration/supported_versions>` of Odoo.
+   to **1 GB** in size.
 
-Push your modules in production
+Push modules in production
--------------------------------
+--------------------------
 
-If you use community or custom modules, add them in a branch in your Github repository.
+If you are using community or custom modules, add them to a branch in your GitHub repository.
-Databases hosted on the Odoo.com online platform do not have any custom modules.
-Users of these databases can therefore skip this step.
 
-You can structure your modules as you wish, Odoo.sh will automatically detect the folders containing
+.. note::
-Odoo addons. For instance, you can put all your modules folder in the root directory of your
+   Databases hosted on Odoo Online do not support custom modules.
-repository, or group the modules in folders by categories that you define (accounting, project,
-...).
 
-For community modules available in public Git repositories,
+Odoo.sh automatically detects folders containing Odoo modules. You can organize them however you
-you can also consider to add them using :ref:`Submodules <odoosh-advanced-submodules>`.
+prefer. For example, you can place them directly in the root directory of your repository or group
+them by category (e.g., `accounting`, `project`, etc.).
 
-Then, either :ref:`make this branch the production branch <odoosh-gettingstarted-branches-stages>`,
+For publicly available community modules, you may also consider using :doc:`submodules
-or :ref:`merge it into your production branch <odoosh-gettingstarted-branches-mergingbranches>`.
+<../advanced/submodules>`.
 
 Download a backup
 -----------------
 
-On-premise databases
+.. tabs::
-~~~~~~~~~~~~~~~~~~~~
 
-Access the URL :file:`/web/database/manager` of your on-premise database and download a backup.
+   .. group-tab:: On-premise
 
-.. Warning::
+      Go to `/web/database/manager` on your on-premise Odoo instance and click :icon:`fa-floppy-o`
+      :guilabel:`Backup`.
 
-  If you cannot access the database manager, it may have been disabled by your system administrator.
+      .. image:: create/on-premise-manager.png
-  See the :ref:`database manager security documentation <db_manager_security>`.
+         :alt: The on-premise web manager interface
 
-You will need the master password of your database server. If you do not have it, contact your
+      Select :guilabel:`zip (includes filestore)` as the :guilabel:`Backup Format`.
-system administrator.
 
-.. image:: create/create-import-onpremise-backup.png
+      .. image:: create/on-premise-backup.png
-   :align: center
+         :alt: Downloading an on-premise database backup
 
-Choose a zip including the filestore as the backup format.
+      .. note::
+         - You will need the :guilabel:`Master Password` of your Odoo server. If you do not have it,
+           contact your system administrator.
+         - If you cannot access the database manager, it may have been disabled by your system
+           administrator. Refer to the :ref:`database manager security documentation
+           <db_manager_security>`.
 
-.. image:: create/create-import-onpremise-backup-dialog.png
+   .. group-tab:: Odoo Online
-  :align: center
 
-Odoo Online databases
+      Log in to your portal account and navigate to the `My Databases page
-~~~~~~~~~~~~~~~~~~~~~
+      <https://www.odoo.com/my/databases>`_, and download a backup by clicking the :icon:`fa-gear`
+      (:guilabel:`gear`) icon, then :icon:`fa-cloud-download` :guilabel:`Download`.
 
-`Access your databases manager <https://accounts.odoo.com/my/databases/manage>`_ and download a
+      .. image:: create/odoo-online-backup.png
-backup of your database.
+         :alt: Downloading an Odoo Online database backup
 
-.. image:: create/create-import-online-backup.png
+      .. warning::
-   :align: center
+         Only major versions of Odoo are compatible with Odoo.sh.
-
-.. Warning::
-
-  Online versions (e.g. *saas-**) are not supported on Odoo.sh.
 
 Upload the backup
 -----------------
 
-Then, in your Odoo.sh project, in the backups tab of your production branch, import the backup you
+In your Odoo.sh project, navigate to the :guilabel:`Backups` tab of your :guilabel:`Production`
-just downloaded.
+branch, and click :guilabel:`Import Database` to upload the backup you previously downloaded.
 
-.. image:: create/create-import-production.png
+.. image:: create/import-database.png
-   :align: center
+   :alt: Importing a database backup on Odoo.sh
 
-Once the backup imported, you can access the database using the *Connect* button in the history of
+Once the import is complete, you can access the database using the :guilabel:`Connect` button in the
-the branch.
+branch's :guilabel:`History` tab.
 
-.. image:: create/create-import-production-done.png
+.. important::
-   :align: center
+   Importing a backup **overwrites all data** currently in the branch. Consider downloading a manual
+   backup beforehand if you want to preserve the existing data.
 
-Check your outgoing email servers
+Check outgoing email servers
----------------------------------
-
-There is a default mail server provided with Odoo.sh.
-To use it, there must be no enabled outgoing mail server configured in your database in
-:menuselection:`Settings --> Technical --> Outgoing Mail Servers` (:ref:`Developer mode
-<developer-mode>` must be activated).
-
-After the import of your database, all outgoing email servers are disabled so you use the Odoo.sh
-email server provided by default.
-
-.. warning::
-   Port 25 is (and will stay) closed. If you want to connect to an external SMTP server, you should
-   use ports 465 and 587.
-
-Check your scheduled actions
 ----------------------------
 
-All scheduled actions are disabled after the import.
+Odoo.sh provides a default email server. To use it, ensure that **no outgoing mail server is
+enabled** in your database by enabling :ref:`developer mode <developer-mode>` and navigating to
+:menuselection:`Settings --> Technical --> Email: Outgoing Mail Servers`
 
-This is to prevent your newly imported database to perform actions that could impact your running
+After importing your database, all configured outgoing mail servers are **disabled**, and the
-production, such as sending the mails remaining in the queue, processing mass mailings, or
+default Odoo.sh server is used.
-third-party services synchronization (Calendars, files hosting, ...).
 
-If you plan to make the imported database your production, enable the scheduled actions you need.
+.. warning::
-You can check what is enabled in the database of origin and enable the same actions in the imported
+   Port **25** is and will remain closed. If connecting to an external SMTP server, use port **465**
-database. Scheduled actions are located under :menuselection:`Settings --> Technical --> Automation
+   or **587**.
---> Scheduled Actions`.
 
-Register your subscription
+Check scheduled actions
---------------------------
+-----------------------
 
-Your subscription is unlinked after the import.
+Scheduled actions are **disabled by default** after importing your database. This prevents your
+newly imported database from performing potentially disruptive operations such as:
 
-The imported database is considered a duplicate by default and the enterprise subscription is
+- sending queued emails,
-therefore removed, as you can only have one database linked per subscription.
+- triggering mass mailings, or
+- syncing with third-party services (e.g., calendars, cloud storage).
 
-If you plan to make it your production, unlink your former database from the subscription, and
+If you intend to use this imported database in production, **re-enable** only the scheduled actions
-register the newly imported database. Read the :doc:`database registration documentation
+you need by enabling :ref:`developer mode <developer-mode>` and going to :menuselection:`Settings
-<../../on_premise>` for instructions.
+--> Technical --> Automation: Scheduled Actions`.
+
+Register the subscription
+-------------------------
+
+After import, the database is considered a **duplicate** and will be unlinked from your enterprise
+subscription.
+
+.. note::
+   You are allowed only one active database per subscription.
+
+If you intend to make the imported database your production environment:
+
+#. Unlink your previous database from the subscription.
+#. Register the new one.
+
+Refer to the :doc:`database registration documentation <../../on_premise>` for step-by-step
+instructions.