update edit repository

Apply suggestions from LARM review

edits

Apply suggestions from FEKU review

edits

edits2

edits3

Apply suggestions from SALI review

edits

closes odoo/documentation#12115

Signed-off-by: Dina Klarisse Dugar (dikd) <dikd@odoo.com>
Co-authored-by: larm-odoo <121518652+larm-odoo@users.noreply.github.com>
Co-authored-by: Felicia Kuan <feku@odoo.com>
Co-authored-by: Sam Lieber (sali) <36018073+samueljlieber@users.noreply.github.com>

.gitignore

@@ -8,3 +8,4 @@ _build/
 
 # Dependencies
 odoo
+venv/

.tx/config

@@ -1,63 +1,152 @@
 [main]
 host = https://www.transifex.com
 
-[o:odoo:p:odoo-16-doc:r:administration]
-file_filter = locale/<lang>/LC_MESSAGES/administration.po
-source_file = locale/sources/administration.pot
-source_lang = en
+[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-16-doc:r:applications]
-file_filter = locale/<lang>/LC_MESSAGES/applications.po
-source_file = locale/sources/applications.pot
-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-16-doc:r:finance]
-file_filter = locale/<lang>/LC_MESSAGES/finance.po
-source_file = locale/sources/finance.pot
-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-16-doc:r:general]
-file_filter = locale/<lang>/LC_MESSAGES/general.po
-source_file = locale/sources/general.pot
-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-16-doc:r:index]
-file_filter = locale/<lang>/LC_MESSAGES/index.po
-source_file = locale/sources/index.pot
-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-16-doc:r:inventory_and_mrp]
-file_filter = locale/<lang>/LC_MESSAGES/inventory_and_mrp.po
-source_file = locale/sources/inventory_and_mrp.pot
-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-16-doc:r:marketing]
-file_filter = locale/<lang>/LC_MESSAGES/marketing.po
-source_file = locale/sources/marketing.pot
-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-16-doc:r:productivity]
-file_filter = locale/<lang>/LC_MESSAGES/productivity.po
-source_file = locale/sources/productivity.pot
-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-16-doc:r:sales]
-file_filter = locale/<lang>/LC_MESSAGES/sales.po
-source_file = locale/sources/sales.pot
-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-16-doc:r:services]
-file_filter = locale/<lang>/LC_MESSAGES/services.po
-source_file = locale/sources/services.pot
-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-16-doc:r:user_settings]
-file_filter = locale/<lang>/LC_MESSAGES/settings.po
-source_file = locale/sources/settings.pot
-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-16-doc:r:websites]
-file_filter = locale/<lang>/LC_MESSAGES/websites.po
-source_file = locale/sources/websites.pot
-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

Makefile

@@ -14,19 +14,32 @@ ifndef CURRENT_LANG
 endif
 
 SPHINX_BUILD   = sphinx-build
+SPHINX_AUTO_BUILD = sphinx-autobuild
 CONFIG_DIR     = .
 SPHINXOPTS     = -D project_root=$(ROOT) -D canonical_version=$(CANONICAL_VERSION) \
                  -D versions=$(VERSIONS) -D languages=$(LANGUAGES) -D language=$(CURRENT_LANG) \
                  -D is_remote_build=$(IS_REMOTE_BUILD) \
+                 -T \
                  -A google_analytics_key=$(GOOGLE_ANALYTICS_KEY) \
                  -A plausible_script=$(PLAUSIBLE_SCRIPT) \
                  -A plausible_domain=$(PLAUSIBLE_DOMAIN) \
 				 -j $(WORKERS)
 SOURCE_DIR     = content
-
+THEME		   = extensions/odoo_theme
+THEME_STATIC   = extensions/odoo_theme/static
+LOCALE		   = locale
+STATIC         = static
+REDIRECTS      = redirects
+SERVER_IP := $(shell ip -4 addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}')
+# Get all listening ports
+LISTENING_PORTS := $(shell ss -tuln | awk 'NR>1 {print $$4}' | awk -F: '{print $$NF}' | sort -n | uniq)
+LOGFILE := $(BUILD_DIR)/live_server.log
+# Default port
+OPEN_PORTS := $(shell ss -tuln | awk 'NR>1 {print $$4}' | awk -F: '{print $$NF}' | sort -n | uniq)
+SELECTED_PORT := $(shell echo "$(OPEN_PORTS)" | awk 'NR==1')
 HTML_BUILD_DIR = $(BUILD_DIR)/html
 ifdef VERSIONS
-  HTML_BUILD_DIR := $(HTML_BUILD_DIR)/master
+  HTML_BUILD_DIR := $(HTML_BUILD_DIR)/18.0
 endif
 ifneq ($(CURRENT_LANG),en)
   HTML_BUILD_DIR := $(HTML_BUILD_DIR)/$(CURRENT_LANG)
@@ -51,8 +64,24 @@ clean:
 
 html: $(HTML_BUILD_DIR)/_static/style.css
 	@echo "Starting build..."
-	$(SPHINX_BUILD) -c $(CONFIG_DIR) -b html $(SPHINXOPTS) $(SOURCE_DIR) $(HTML_BUILD_DIR)
+	$(SPHINX_BUILD) -q -c $(CONFIG_DIR) -b html $(SPHINXOPTS) $(SOURCE_DIR) $(HTML_BUILD_DIR)
 	@echo "Build finished."
+html_log: SPHINXOPTS += -A collapse_menu=True
+html_log: $(HTML_BUILD_DIR)/_static/style.css
+	@echo "Starting build..."
+	$(SPHINX_BUILD) -q -c $(CONFIG_DIR) -b html $(SPHINXOPTS) $(SOURCE_DIR) $(HTML_BUILD_DIR) > $(LOGFILE) 2>&1
+	@echo "Build finished."
+
+live: SPHINXOPTS += -A collapse_menu=True
+live:
+	@echo "Starting Live Server..."
+	$(SPHINX_AUTO_BUILD) $(SOURCE_DIR) $(HTML_BUILD_DIR) \
+	--port 8000 --host $(SERVER_IP) \
+	--watch $(THEME) --watch $(LOCALE) --watch $(STATIC) --watch $(REDIRECTS) --watch $(THEME_STATIC) --watch . \
+	--pre-build "sh -c 'mkdir -p $(HTML_BUILD_DIR)/_static && python3 -m pysassc $(THEME)/static/style.scss $(HTML_BUILD_DIR)/_static/style.css'" \
+	$(SPHINXOPTS) -c $(CONFIG_DIR) -b html
+
+
 
 # To call *after* `make html`
 # Binary dependencies (Debian): texlive-fonts-recommended texlive-latex-extra
@@ -78,7 +107,7 @@ $(HTML_BUILD_DIR)/_static/style.css: extensions/odoo_theme/static/style.scss ext
 #=== Development and debugging rules ===#
 
 fast: SPHINXOPTS += -A collapse_menu=True
-fast: html
+fast: hmlt
 
 static: $(HTML_BUILD_DIR)/_static/style.css
 	cp -r extensions/odoo_theme/static/* $(HTML_BUILD_DIR)/_static/
@@ -86,12 +115,13 @@ static: $(HTML_BUILD_DIR)/_static/style.css
 
 # Called by runbot for the ci/documentation_guideline check.
 test:
-	@python tests/main.py $(SOURCE_DIR)/administration $(SOURCE_DIR)/applications $(SOURCE_DIR)/contributing $(SOURCE_DIR)/developer $(SOURCE_DIR)/services redirects
+	@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.
 review:
-	@read -p "Enter content path: " path; read -p "Enter max line length (default: 100): " line_length; \
+	@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; \
+	if echo $$path | grep -q 'content/'; then path=`echo $$path | sed 's|content/||'`; fi; \
 	if [ -z "$$line_length" ]; then line_length=100; fi; \
 	export REVIEW=1; \
 	python tests/main.py --max-line-length=$$line_length $(SOURCE_DIR)/$$path

README.md

@@ -1,4 +1,4 @@
-# Odoo documentation
+# Documentation
 
 ## Build the documentation locally
 
@@ -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

@@ -13,86 +13,92 @@ from sphinx.util import logging
 _logger = logging.getLogger(__name__)
 
 
-#=== General configuration ===#
+# === General configuration ===#
 
 # General information about the project.
-project = 'Odoo'
-copyright = 'Odoo S.A.'
+project = "Odoo"
+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|.
-version = release = 'master'
+version = release = "18.0"
 
 # `current_branch` is the technical name of the current branch.
 # E.g., saas-15.4 -> saas-15.4; 12.0 -> 12.0, master -> master (*).
 current_branch = version
 # `current_version` is the Odoo version linked to the current branch.
 # E.g., saas-15.4 -> 15.4; 12.0 -> 12; master -> master (*).
-current_version = current_branch.replace('saas-', '').replace('.0', '')
+current_version = current_branch.replace("saas-", "").replace(".0", "")
 # `current_major_branch` is the technical name of the major branch before the current branch.
 # E.g., saas-15.4 -> 15.0; 12.0 -> 12.0; master -> master (*).
-current_major_branch = re.sub(r'\.\d', '.0', current_branch.replace('saas-', ''))
+current_major_branch = re.sub(r"\.\d", ".0", current_branch.replace("saas-", ""))
 # `current_major_version` is the Odoo version linked to the current major branch.
 # E.g., saas-15.4 -> 15; 12.0 -> 12; master -> master (*).
-current_major_version = current_major_branch.replace('.0', '')
+current_major_version = current_major_branch.replace(".0", "")
 # (*): We don't care for master.
 
 # The minimal Sphinx version required to build the documentation.
-needs_sphinx = '3.0.0'
+needs_sphinx = "3.0.0"
 
 # The default language in which the documentation is written. It is set to `None` because Sphinx
 # considers that no language means 'en'.
 language = None
 
 # The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = {
+    ".md": "markdown",
+    ".rst": "restructuredtext",
+}
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # List of patterns, relative to source directory, that match files and directories to ignore when
 # looking for source files.
 exclude_patterns = [
-    'locale',
-    'README.*',
-    'bin', 'include', 'lib',
-    'odoo',
+    "locale",
+    "README.*",
+    "bin",
+    "include",
+    "lib",
+    "odoo",
 ]
 
 # The RST text role to use when the role is not specified. E.g.: `example`.
 # We use 'literal' as default role for markdown compatibility: `foo` behaves like ``foo``.
 # See https://docutils.sourceforge.io/docs/ref/rst/roles.html#standard-roles for other roles.
-default_role = 'literal'
-
+default_role = "literal"
 
+html_copy_source = False
 # Whether scaled down images should be be wrapped in a `<a/>` tag linking to the image file or not.
 html_scaled_image_link = False
 
 # If true, '()' will be appended to :func: etc. cross-reference text
 add_function_parentheses = True
 
-#=== Extensions configuration ===#
+# === Extensions configuration ===#
 
 source_read_replace_vals = {
-    'BRANCH': current_branch,
-    'CURRENT_BRANCH': current_branch,
-    'CURRENT_VERSION': current_version,
-    'CURRENT_MAJOR_BRANCH': current_major_branch,
-    '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}',
-    'OWL_PATH': f'https://github.com/odoo/owl/blob/master',
+    "BRANCH": current_branch,
+    "CURRENT_BRANCH": current_branch,
+    "CURRENT_VERSION": current_version,
+    "CURRENT_MAJOR_BRANCH": current_major_branch,
+    "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}",
+    "OWL_PATH": f"https://github.com/odoo/owl/blob/master",
 }
 
 # Add extensions directory to PYTHONPATH
-extension_dir = Path('extensions')
+extension_dir = Path("extensions")
 sys.path.insert(0, str(extension_dir.absolute()))
 
 # Search for the directory of odoo sources to know whether autodoc should be used on the dev doc
-odoo_sources_candidate_dirs = (Path('odoo'), Path('../odoo'))
+odoo_sources_candidate_dirs = (Path("Odoo18"), Path("../Odoo18"))
+# odoo_sources_candidate_dirs = (Path('odoo'), Path('../odoo'))
 odoo_sources_dirs = [
-    d for d in odoo_sources_candidate_dirs if d.is_dir() and (d / 'odoo-bin').exists()
+    d for d in odoo_sources_candidate_dirs if d.is_dir() and (d / "odoo-bin").exists()
 ]
 odoo_dir_in_path = False
 
@@ -103,20 +109,30 @@ if not odoo_sources_dirs:
         "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/odoo` or create a symbolic link.",
-        {'dir_list': '\n'.join([f'\t- {d.resolve()}' for d in odoo_sources_candidate_dirs])},
+        {
+            "dir_list": "\n".join(
+                [f"\t- {d.resolve()}" for d in odoo_sources_candidate_dirs]
+            )
+        },
     )
 else:
     if (3, 6) < sys.version_info < (3, 7):
         # Running odoo needs python 3.7 min but monkey patch version_info to be compatible with 3.6.
         sys.version_info = (3, 7, 0)
     odoo_dir = odoo_sources_dirs[0].resolve()
-    source_read_replace_vals['ODOO_RELPATH'] = '/../' + str(odoo_sources_dirs[0])
+    source_read_replace_vals["ODOO_RELPATH"] = "/../" + str(odoo_sources_dirs[0])
     sys.path.insert(0, str(odoo_dir))
     import odoo.addons
-    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.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
     if release != odoo_version:
         _logger.warning(
             "Found Odoo sources in %(directory)s but with version '%(odoo_version)s' incompatible "
@@ -124,146 +140,193 @@ else:
             "The 'Developer' documentation will be built but autodoc directives will be skipped.\n"
             "In order to fully build the 'Developer' documentation, checkout the matching branch"
             " with `cd odoo && git checkout %(doc_version)s`.",
-            {'directory': odoo_dir, 'odoo_version': odoo_version, 'doc_version': version},
+            {
+                "directory": odoo_dir,
+                "odoo_version": odoo_version,
+                "doc_version": version,
+            },
         )
     else:
         _logger.info(
             "Found Odoo sources in %(directory)s matching documentation version '%(version)s'.",
-            {'directory': odoo_dir, 'version': release},
+            {"directory": odoo_dir, "version": release},
         )
         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.
 model_references = {
-    'account.account.type': 'addons/account/data/data_account_type.xml',
-    'res.country': 'odoo/addons/base/data/res_country_data.xml',
-    'res.currency': 'odoo/addons/base/data/res_currency_data.xml',
+    "account.account.type": "addons/account/data/data_account_type.xml",
+    "res.country": "odoo/addons/base/data/res_country_data.xml",
+    "res.currency": "odoo/addons/base/data/res_currency_data.xml",
 }
 
 # The Sphinx extensions to use, as module names.
 # They can be extensions coming with Sphinx (named 'sphinx.ext.*') or custom ones.
 extensions = [
     # Link sources in other projects (used to build the reference doc)
-    'sphinx.ext.intersphinx',
-
+    "sphinx.ext.intersphinx",
     # Support the specialized to-do directives
-    'sphinx.ext.todo',
-
+    "sphinx.ext.todo",
     # Custom Odoo theme
-    'odoo_theme',
-
+    "odoo_theme",
     # Youtube and Vimeo videos integration (youtube, vimeo directives)
-    'embedded_video',
-
-    'custom_admonitions',
-
+    "embedded_video",
+    "custom_admonitions",
     # Redirection generator
-    'redirects',
-
+    "redirects",
     # Content tabs
-    'sphinx_tabs.tabs',
-
+    "sphinx_tabs.tabs",
     # Cards
-    'cards',
-
+    # "cards",
     # Spoilers
-    'spoilers',
-
+    "spoilers",
     # Strange html domain logic used in memento pages
-    'html_domain',
+    "html_domain",
+    "myst_parser",
+    "sphinx_design",
 ]
 
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "fieldlist",
+    "html_admonition",
+    "html_image",
+    "replacements",
+    "smartquotes",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+]
 if odoo_dir_in_path:
     # GitHub links generation
     extensions += [
-        'sphinx.ext.linkcode',
-        'github_link',
+        "sphinx.ext.linkcode",
+        "github_link",
         # Parse Python docstrings (autodoc, automodule, autoattribute directives)
-        'sphinx.ext.autodoc',
-        'autodoc_field',
+        "sphinx.ext.autodoc",
+        "autodoc_field",
     ]
 else:
     extensions += [
-        'autodoc_placeholder',
+        "autodoc_placeholder",
     ]
-extensions.append('sphinx.ext.graphviz' if shutil.which('dot') else 'graphviz_placeholder')
+extensions.append(
+    "sphinx.ext.graphviz" if shutil.which("dot") else "graphviz_placeholder"
+)
 
 todo_include_todos = False
 
 intersphinx_mapping = {
-    'pillow': ('https://pillow.readthedocs.io/en/stable/', None),
-    'python': ('https://docs.python.org/3/', None),
-    'werkzeug': ('https://werkzeug.palletsprojects.com/en/2.3.x/', None),
+    "pillow": ("https://pillow.readthedocs.io/en/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    "werkzeug": ("https://werkzeug.palletsprojects.com/en/2.3.x/", None),
 }
 
-github_user = 'odoo'
-github_project = 'documentation'
+github_user = "NextERP"
+github_project = "documentation"
 
-locale_dirs = ['../locale/']
-templates_path = ['../extensions']
+locale_dirs = ["../locale/"]
+templates_path = ["../extensions"]
 
 # custom docname_to_domain to divide the translations of applications in subdirectories
-sphinx.transforms.i18n.docname_to_domain = (
-    sphinx.util.i18n.docname_to_domain
-) = lambda docname, compact: docname.split('/')[1 if docname.startswith('applications/') else 0]
+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`
 # is populated. If a version is passed to `versions` but is not listed here, it will not be shown.
 versions_names = {
-    'master': "Master",
-    'saas-16.4': "Odoo Online",
-    'saas-16.3': "Odoo Online",
-    'saas-16.2': "Odoo Online",
-    'saas-16.1': "Odoo Online",
-    '16.0': "Odoo 16",
-    'saas-15.2': "Odoo Online",
-    '15.0': "Odoo 15",
-    '14.0': "Odoo 14",
-    '13.0': "Odoo 13",
+    "master": "Master",
+    "saas-18.1": "Odoo Online",
+    "18.0": "18.0",
+    "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`
 # is populated. If a language is passed to `languages` but is not listed here, it will not be shown.
 languages_names = {
-    'de': 'DE',
-    'en': 'EN',
-    'es': 'ES',
-    'fr': 'FR',
-    'it': 'IT',
-    'nl': 'NL',
-    'pt_BR': 'PT',
-    'uk': 'UA',
-    'zh_CN': 'ZH (CN)',
-    'zh_TW': 'ZH (TW)'
+    "de": "DE",
+    "en": "EN",
+    "es": "ES",
+    "es_419": "ES (LATAM)",
+    "fr": "FR",
+    "id": "ID",
+    "it": "IT",
+    "ja": "JA",
+    "ko": "KR",
+    "nl": "NL",
+    "pt_BR": "PT",
+    "ro": "RO",
+    "sv": "SV",
+    "th": "TH",
+    "uk": "UA",
+    "vi": "VI",
+    "zh_CN": "ZH (CN)",
+    "zh_TW": "ZH (TW)",
 }
 
 # The directory in which files holding redirect rules used by the 'redirects' extension are listed.
-redirects_dir = 'redirects/'
+redirects_dir = "redirects/"
 
 sphinx_tabs_disable_tab_closing = True
 sphinx_tabs_disable_css_loading = True
 
-#=== Options for HTML output ===#
+# Autodoc ordering
+autodoc_member_order = "bysource"
 
-html_theme = 'odoo_theme'
+# === Options for HTML output ===#
+
+html_theme = "odoo_theme"
 
 # The name of the Pygments (syntax highlighting) style to use.
 # See extensions/odoo_theme/pygments_override.py
-pygments_style = 'odoo'
+pygments_style = "odoo"
 
 # The paths that contain custom themes, relative to this directory.
-html_theme_path = ['extensions']
+html_theme_path = ["extensions"]
 
 # The name of an image file (within the static path) to use as favicon of the docs.
 # This file should be a Windows icon file (.ico) being 16x16 or 32x32 pixels large.
-html_favicon = os.path.join(html_theme_path[0], html_theme, 'static', 'img', 'favicon.ico')
+html_favicon = os.path.join(
+    html_theme_path[0], html_theme, "static", "img", "favicon.ico"
+)
 
 # The paths that contain custom static files, relative to this directory.
 # They are copied after the builtin static files, so a file named "default.css" will overwrite the
 # builtin "default.css".
-html_static_path = ['static']
+html_static_path = ["static"]
 html_permalinks = True
 
 # Additional JS & CSS files that can be imported with the 'custom-js' and 'custom-css' metadata.
@@ -273,72 +336,131 @@ html_css_files = []
 
 # PHP lexer option to not require <?php
 highlight_options = {
-  'php': {'startinline': True},
+    "php": {"startinline": True},
 }
 
-#=== Options for LaTeX output ===#
+# === Options for LaTeX output ===#
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    'papersize': 'a4paper',
-
+    "papersize": "a4paper",
     # Additional stuff for the LaTeX preamble.
-    'preamble': r'\usepackage{odoo}',
-    'tableofcontents': '',  # no TOC
-
+    "preamble": r"\usepackage{odoo}",
+    "tableofcontents": "",  # no TOC
     # Output manually in latex docs
-    'releasename': release,
+    "releasename": release,
 }
 
-latex_additional_files = ['static/latex/odoo.sty']
+latex_additional_files = ["static/latex/odoo.sty"]
 
 # Grouping the document tree into LaTeX files. List of tuples:
 # (source start file, target name, title, author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    ('legal/terms/enterprise_tex', 'odoo_enterprise_agreement.tex',
-     'Odoo Enterprise Subscription Agreement', '', 'howto'),
-    ('legal/terms/partnership_tex',
-     'odoo_partnership_agreement.tex', 'Odoo Partnership Agreement', '', 'howto'),
-    ('legal/terms/terms_of_sale',
-     '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'),
-    ('legal/terms/i18n/partnership_tex_fr',
-     'odoo_partnership_agreement_fr.tex', 'Odoo Partnership Agreement (FR)', '', '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'),
-
-    ('legal/terms/i18n/enterprise_tex_de', 'odoo_enterprise_agreement_de.tex',
-     'Odoo Enterprise Subscription Agreement (DE)', '', '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'),
-    ('legal/terms/i18n/partnership_tex_es',
-     'odoo_partnership_agreement_es.tex', 'Odoo Partnership Agreement (ES)', '', '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'),
+    (
+        "legal/terms/enterprise_tex",
+        "odoo_enterprise_agreement.tex",
+        "Odoo Enterprise Subscription Agreement",
+        "",
+        "howto",
+    ),
+    (
+        "legal/terms/partnership_tex",
+        "odoo_partnership_agreement.tex",
+        "Odoo Partnership Agreement",
+        "",
+        "howto",
+    ),
+    (
+        "legal/terms/terms_of_sale",
+        "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",
+    ),
+    (
+        "legal/terms/i18n/partnership_tex_fr",
+        "odoo_partnership_agreement_fr.tex",
+        "Odoo Partnership Agreement (FR)",
+        "",
+        "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",
+    ),
+    (
+        "legal/terms/i18n/enterprise_tex_de",
+        "odoo_enterprise_agreement_de.tex",
+        "Odoo Enterprise Subscription Agreement (DE)",
+        "",
+        "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",
+    ),
+    (
+        "legal/terms/i18n/partnership_tex_es",
+        "odoo_partnership_agreement_es.tex",
+        "Odoo Partnership Agreement (ES)",
+        "",
+        "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",
+    ),
 ]
 
 # List of languages that have legal translations (excluding EN). The keys must be in
 # `languages_names`. These translations will have a link to their versions of the legal
 # contracts, instead of the default EN one. The main legal documents are not part of the
 # translations since they have legal meaning.
-legal_translations = ['de', 'es', 'fr', 'nl', 'pt_BR']
+legal_translations = ["de", "es", "fr", "nl", "pt_BR"]
 
 # The name of an image file (relative to this directory) to place at the top of the title page.
-latex_logo = 'static/img/odoo_logo.png'
+latex_logo = "static/img/odoo_logo.png"
 
 # If true, show URL addresses after external links.
-latex_show_urls = 'True'
+latex_show_urls = "True"
+
 
 # https://github.com/sphinx-doc/sphinx/issues/4054#issuecomment-329097229
 def source_read_replace(app, docname, source):
@@ -356,33 +478,42 @@ def source_read_replace(app, docname, source):
         result = result.replace(f"{{{key}}}", app.config.source_read_replace_vals[key])
     source[0] = result
 
+
 def setup(app):
     # Generate all alternate URLs for each document
-    app.add_config_value('project_root', None, 'env')
-    app.add_config_value('canonical_version', None, 'env')
-    app.add_config_value('versions', None, 'env')
-    app.add_config_value('languages', None, 'env')
-    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.add_config_value("project_root", None, "env")
+    app.add_config_value("canonical_version", None, "env")
+    app.add_config_value("versions", None, "env")
+    app.add_config_value("languages", None, "env")
+    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)
+    # 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)
 
-    app.add_lexer('json', JsonLexer)
-    app.add_lexer('xml', XmlLexer)
+    app.add_lexer("json", JsonLexer)
+    app.add_lexer("xml", XmlLexer)
 
-    app.connect('html-page-context', _generate_alternate_urls)
+    app.connect("html-page-context", _generate_alternate_urls)
 
     # Add a `condition` option on directives to ignore them based on config values
-    app.add_config_value('odoo_dir_in_path', None, 'env')
+    app.add_config_value("odoo_dir_in_path", None, "env")
+
     def context_eval(expr):
         return eval(expr, {confval.name: confval.value for confval in app.config})
 
     def patch(to_patch):
-        to_patch.option_spec['condition'] = context_eval
+        to_patch.option_spec["condition"] = context_eval
         original_run = to_patch.run
+
         def new_run(self):
-            if not self.options.get('condition', True):
+            if not self.options.get("condition", True):
                 return []
             return original_run(self)
+
         to_patch.run = new_run
 
     for to_patch in (
@@ -393,7 +524,7 @@ def setup(app):
 
 
 def _generate_alternate_urls(app, pagename, templatename, context, doctree):
-    """ Add keys of required alternate URLs for the current document in the rendering context.
+    """Add keys of required alternate URLs for the current document in the rendering context.
 
     Alternate URLS are required for:
       - The canonical link tag
@@ -402,7 +533,7 @@ def _generate_alternate_urls(app, pagename, templatename, context, doctree):
     """
 
     def _canonicalize():
-        """ Add the canonical URL for the current document in the rendering context.
+        """Add the canonical URL for the current document in the rendering context.
 
         The canonical version is the last released version of the documentation.
         For a given language, the canonical root of a page is in the same language so that web
@@ -414,76 +545,117 @@ def _generate_alternate_urls(app, pagename, templatename, context, doctree):
         """
         # 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_lang = 'en'  # Always 'en'. Don't take the value of the config option.
-        context['canonical'] = _build_url(_version=_canonical_version, _lang=_canonical_lang)
+        _canonical_lang = (
+            "en"  # Always 'en'. Don't take the value of the config option.
+        )
+        context["canonical"] = _build_url(
+            _version=_canonical_version, _lang=_canonical_lang
+        )
 
     def _versionize():
-        """ Add the pairs of (version, url) for the current document in the rendering context.
+        """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[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'] = []
+        context["alternate_versions"] = []
         for _alternate_version, _display_name in versions_names.items():
-            if _alternate_version in _provided_versions and _alternate_version != version:
-                context['alternate_versions'].append(
+            if (
+                _alternate_version in _provided_versions
+                and _alternate_version != version
+            ):
+                context["alternate_versions"].append(
                     (_display_name, _build_url(_alternate_version))
                 )
 
     def _localize():
-        """ Add the pairs of (lang, code, url) for the current document in the rendering context.
+        """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)
-        context['language_code'] = _current_lang
+        context["language"] = languages_names.get(_current_lang, _current_lang.upper())
+        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'] = []
+        context["alternate_languages"] = []
         for _alternate_lang, _display_name in languages_names.items():
-            if _alternate_lang in _provided_languages and _alternate_lang != _current_lang:
-                context['alternate_languages'].append(
+            if (
+                _alternate_lang in _provided_languages
+                and _alternate_lang != _current_lang
+            ):
+                context["alternate_languages"].append(
                     (
                         _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),
                     )
                 )
 
         # Dynamic generation of localized legal doc links
-        context['legal_translations'] = legal_translations
-
+        context["legal_translations"] = legal_translations
 
     def _build_url(_version=None, _lang=None):
+        # print(f"###################################{app.config.is_remote_build}")
+        # print(f"###################################{app.config.project_root}")
         if app.config.is_remote_build:
             # Project root like https://www.odoo.com/documentation
             _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
         _version = _version or app.config.version
-        _lang = _lang or app.config.language or 'en'
-        _canonical_page = f'{pagename}.html'
+        _lang = _lang or app.config.language or "en"
+        _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}"):
+                # remove language code for current translation, set target one
+                _page = re.sub("_[a-z]{2}$", "", pagename)
+                if "terms/i18n" not in _page:
+                    _page = _page.replace("/terms/", "/terms/i18n/")
+                _canonical_page = f"{_page}_{_lang}.html"
+            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)
+                _canonical_page = f'{_page.replace("/i18n/", "/")}.html'
+
         if app.config.is_remote_build:
-            _canonical_page = _canonical_page.replace('index.html', '')
-        return f'{_root}' \
-               f'{f"/{_version}" if app.config.versions else ""}' \
-               f'{f"/{_lang}" if _lang != "en" else ""}' \
-               f'/{_canonical_page}'
+            _canonical_page = _canonical_page.replace("index.html", "")
+
+        return (
+            f"{_root}"
+            f'{f"/{_version}" if app.config.versions else ""}'
+            f'{f"/{_lang}" if _lang != "en" else ""}'
+            f"/{_canonical_page}"
+        )
 
     _canonicalize()
     _versionize()

config.yaml

@@ -0,0 +1,42 @@
+  # -d, --dry-run                   Do not write/remove any files
+  # -R, --replace-files             Remove parsed files
+  # -S, --stop-on-fail              Stop on first failure
+  # -W, --raise-on-warning          Raise exception on parsing warning
+  # -l, --language TEXT             Language code for directive names  [default:
+  #                                 en]
+  # --sphinx / --no-sphinx          Load sphinx.  [default: sphinx]
+  # -e, --extensions TEXT           A comma-separated list of sphinx extensions
+  #                                 to load.
+  # -dd, --default-domain TEXT      Default sphinx domain  [default: py]
+  # -dr, --default-role TEXT        Default sphinx role [default: convert to
+  #                                 literal]
+  # -cp, --cite-prefix TEXT         Prefix to add to citation references
+  #                                 [default: cite]
+  # --consecutive-numbering / --no-consecutive-numbering
+  #                                 Apply consecutive numbering to ordered lists
+  #                                 [default: consecutive-numbering]
+  # --colon-fences / --no-colon-fences
+  #                                 Use colon fences for directives with parsed
+  #                                 content  [default: colon-fences]
+  # --dollar-math / --no-dollar-math
+  #                                 Convert math (where possible) to dollar-
+  #                                 delimited math  [default: dollar-math]
+  # -c, --conversions PATH          YAML file mapping directives -> conversions
+  # --encoding TEXT                 Encoding for read/write  [default: utf8]
+  # --config FILE                   YAML file to read default configuration from
+  # -h, --help                      Show this message and exit.
+language: en
+sphinx: true
+default_conversion: parse_all
+conversions:
+  docutils.parsers.rst.directives.images.image: parse_all
+  sphinx.directives.patches.ListTable: parse_all  # For tables if needed
+extensions:
+- sphinx.ext.intersphinx
+- sphinx.ext.todo
+- sphinx_tabs.tabs
+- sphinx_design
+default_domain: py
+consecutive_numbering: true
+colon_fences: true
+dollar_math: true

content-rst/administration.rst

@@ -0,0 +1,65 @@
+:nosearch:
+:show-content:
+:hide-page-toc:
+:show-toc:
+
+===================
+Database management
+===================
+
+These guides provide instructions on how to install, maintain and upgrade Odoo databases.
+
+.. seealso::
+    :doc:`History of Versions <administration/supported_versions>`
+
+Installation
+============
+
+Depending on the intended use case, there are multiple ways to install Odoo - or not install it at
+all.
+
+- :doc:`Online <administration/odoo_online>` is the easiest way to use Odoo in production or to try it.
+
+- :doc:`Packaged installers <administration/on_premise/packages>` are suitable for testing Odoo and
+  developing modules. They can be used for long-term production with additional deployment and
+  maintenance work.
+
+- :doc:`Source install <administration/on_premise/source>` provides greater flexibility, as it
+  allows, for example, running multiple Odoo versions on the same system. It is adequate to develop
+  modules and can be used as a base for production deployment.
+
+- A `Docker <https://hub.docker.com/_/odoo/>`_ base image is available for development or
+  deployment.
+
+.. _install/editions:
+
+Editions
+========
+
+There are two different editions.
+
+**Odoo Community** is the free and open-source version of the software, licensed under the `GNU
+LGPLv3 <https://github.com/odoo/odoo/blob/master/LICENSE>`_. It is the core upon which Odoo
+Enterprise is built.
+
+**Odoo Enterprise** is the shared source version of the software, giving access to more
+functionalities, including functional support, upgrades, and hosting. `Pricing
+<https://www.odoo.com/pricing-plan>`_ starts from one app free.
+
+.. tip::
+   :doc:`Switch from Community to Enterprise <administration/on_premise/community_to_enterprise>` at
+   any time (except for the source install).
+
+
+.. toctree::
+    :titlesonly:
+
+    administration/hosting
+    administration/odoo_online
+    administration/odoo_sh
+    administration/on_premise
+    administration/upgrade
+    administration/neutralized_database
+    administration/supported_versions
+    administration/mobile
+    administration/odoo_accounts

content-rst/administration/hosting.rst

@@ -0,0 +1,121 @@
+=======
+Hosting
+=======
+
+.. _hosting/change-solution:
+
+Change hosting solution
+=======================
+
+The instructions to change the hosting type of a database depend on the current solution used and to
+which solution the database should be moved.
+
+Transferring an on-premise database
+===================================
+
+To Odoo Online
+--------------
+
+.. important::
+   - Odoo Online is *not* compatible with **non-standard apps**.
+   - The database's current version must be :doc:`supported <supported_versions>`.
+
+#. 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:
+
+   - your **subscription number**,
+   - the **URL** you want to use for the database (e.g., `company.odoo.com`), and
+   - the **dump** as an attachment or as a link to the file (required for 60 MB+ files).
+
+#. Odoo then makes sure the database is compatible before putting it online. In case of technical
+   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
+   possible to schedule the transfer.
+
+To Odoo.sh
+----------
+
+Follow the instructions found in :ref:`the Import your database section
+<odoo_sh_import_your_database>` of the Odoo.sh *Create your project* documentation.
+
+Transferring an Odoo Online database
+====================================
+
+.. important::
+   Odoo Online's :ref:`intermediary versions <supported_versions>` are not supported by Odoo.sh or
+   on-premise. Therefore, if the database to transfer is running an intermediary version, it must be
+   upgraded first to the next :ref:`major version <supported_versions>`, waiting for its release if
+   necessary.
+
+   .. example::
+      Transferring an online database running on Odoo 16.3 would require first upgrading it to Odoo
+      17.0.
+
+   .. tip::
+      Click the gear icon (:guilabel:`⚙`) next to the database name on the `Odoo 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
+      complete the subscription transfer.
+
+To on-premise
+-------------
+
+#. Sign in to `the Odoo Online database manager <https://www.odoo.com/my/databases/>`_ and click the
+   gear icon (:guilabel:`⚙`) next to the database name to :guilabel:`Download` a backup. 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.
+
+To Odoo.sh
+----------
+
+#. Sign in to `the Odoo Online database manager <https://www.odoo.com/my/databases/>`_ and click the
+   gear icon (:guilabel:`⚙`) next to the database name to :guilabel:`Download` a backup. 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
+   <odoo_sh_import_your_database>` of the Odoo.sh *Create your project* documentation.
+
+Transferring an Odoo.sh database
+================================
+
+To Odoo Online
+--------------
+
+.. important::
+   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:
+
+   - your **subscription number**,
+   - the **URL** you want to use for the database (e.g., `company.odoo.com`),
+   - which **branch** should be migrated,
+   - in which **region** you want the database to be hosted (Americas, Europe, or Asia),
+   - which user(s) will be the **administrator(s)**, and
+   - **when** (and in which timezone) you want the database to be up and running.
+
+#. Odoo then makes sure the database is compatible before putting it online. In case of technical
+   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
+     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
+     switch from the Odoo.sh server to the Odoo Online servers.
+   - Databases are **not reachable** during their migration.
+
+To on-premise
+-------------
+
+#. Download a :ref:`backup of your Odoo.sh production database <odoo_sh_branches_backups>`.
+#. Restore the database from the database manager on your local server using the backup.

content-rst/administration/mobile.rst

@@ -0,0 +1,67 @@
+================
+Odoo mobile apps
+================
+
+Two kind of Odoo mobile app exist: the progressive web app (PWA) and store apps. Using the PWA is
+recommended.
+
+Progressive web app (PWA)
+=========================
+
+PWAs are web-based applications designed to function across different devices and platforms,
+leveraging web browsers to deliver user experiences similar to native apps.
+
+The Odoo PWA features include:
+
+- Quick access by adding the PWA to a device's home screen
+- Seamless and borderless navigation experience
+- Push notifications
+- SSO authentication
+
+To install the Odoo PWA, launch a browser supporting PWAs, and sign in to an Odoo database. The
+instructions to install a PWA depend on the platform and browser used.
+
+.. tabs::
+
+   .. tab:: Android
+
+      **Chrome**: open Chrome's menu (:guilabel:`⋮`), select :guilabel:`Install app`, and tap
+      :guilabel:`Install`.
+
+      **Firefox**: open Firefox's menu (:guilabel:`⋮`), select :guilabel:`Install`, and either touch
+      and hold the Odoo icon or tap :guilabel:`Add automatically`.
+
+      The PWA can also be installed with **Samsung Internet**, **Edge**, and **Opera**.
+
+   .. tab:: iOS
+
+      **Safari**: open the **Share** menu by tapping the square with an arrow pointing upwards icon,
+      select :guilabel:`Add to Home Screen`, edit the PWA details if desired, and tap
+      :guilabel:`Add`.
+
+      On iOS 16.4 and above, the PWA can also be installed with **Chrome**, **Firefox**, and
+      **Edge**.
+
+   .. tab:: Desktop
+
+      **Chrome** and **Edge**: click the installation icon at the right of the address bar and click
+      :guilabel:`Install`.
+
+.. seealso::
+   - `Google Chrome Help: Use progressive web apps
+     <https://support.google.com/chrome/answer/9658361>`_
+   - `MDN Web Docs: Installing and uninstalling web apps
+     <https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Installing>`_
+   - `Microsoft Support: Install, manage, or uninstall apps in Microsoft Edge <https://support.microsoft.com/en-us/topic/install-manage-or-uninstall-apps-in-microsoft-edge-0c156575-a94a-45e4-a54f-3a84846f6113>`_
+
+Store apps
+==========
+
+The Odoo mobile apps are available for download on the `Google Play Store
+<https://play.google.com/store/apps/details?id=com.odoo.mobile>`_ and `Apple App 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.
+
+While the store apps support multi-accounts, they are not compatible with SSO authentication.

content-rst/administration/neutralized_database.rst

@@ -0,0 +1,36 @@
+====================
+Neutralized database
+====================
+
+A neutralized database is a non-production database on which several parameters are deactivated.
+This enables one to carry out tests without the risk of launching specific automated processes that
+could impact production data (e.g., sending emails to customers). Live access is removed and
+turned into a testing environment.
+
+.. note::
+   **Any testing database created is a neutralized database:**
+
+   - testing backup databases
+   - duplicate databases
+   - for Odoo.sh: staging and development databases
+
+.. important::
+   A database can also be neutralized when upgrading, as it is vital to do some tests before
+   switching to a new version.
+
+Deactivated features
+====================
+
+Here is a non-exhaustive list of the deactivated features:
+
+- all planned actions (e.g., automatic invoicing of subscriptions, mass mailing, etc.)
+- outgoing emails
+- bank synchronization
+- payment providers
+- delivery methods
+- :abbr:`IAP (In-App Purchase)` tokens
+- website visibility (prevent search engines from indexing your site)
+
+.. note::
+   **A red banner at the top of the screen is displayed on the neutralized database so that it can
+   be seen immediately.**

content-rst/administration/odoo_accounts.rst

@@ -0,0 +1,80 @@
+=================
+Odoo.com accounts
+=================
+
+This documentation is dedicated to edits made to an Odoo.com account. The following processes
+describe how to delete an Odoo.com account, and how to change the password on an Odoo.com account.
+
+Delete Odoo.com account
+=======================
+
+To delete an Odoo.com account, start by clicking the profile icon in the upper-right corner
+(represented by the username and icon) to reveal a drop-down menu. From the drop-down menu, select
+:guilabel:`My Odoo.com account`, which reveals the user portal.
+
+From the user portal, the delete option can be accessed by going to :menuselection:`My Account -->
+Edit Security Settings --> Delete Account`. It can also be accessed by going to
+`https://www.odoo.com/my/home <https://www.odoo.com/my/home>`_.
+
+.. danger::
+   Deleting an Odoo account is irreversible. Be careful performing this action, as the Odoo.com
+   account is **not** retrievable once deleted.
+
+Upon clicking the :guilabel:`Delete Account` button, a pop-up window appears, requesting
+confirmation for the account deletion.
+
+.. image:: odoo_accounts/delete-account.png
+   :align: center
+   :alt: Clicking on the Delete Account button will populate a window verifying the change.
+
+To confirm the deletion, enter the :guilabel:`Password` and the :guilabel:`Login` for the account
+being deleted. Then, click the :guilabel:`Delete Account` button to confirm the deletion.
+
+.. _odoocom/change_password:
+
+Odoo.com account password change
+================================
+
+To change an Odoo.com account password, first login into the Odoo.com user account from the Odoo.com
+login page. After logging-in, go to the upper-right corner of the screen, and click the :guilabel:`▼
+(down arrow)` icon next to the profile icon. Then, select :guilabel:`My Account`, and a portal
+dashboard appears.
+
+To change the Odoo.com password, click on the :guilabel:`Edit Security Settings` link, below the
+:menuselection:`Account Security` section. Next, make the necessary changes by typing in the current
+:guilabel:`Password`, :guilabel:`New Password`, and verify the new password. Lastly, click on
+:guilabel:`Change Password` to complete the password change.
+
+.. note::
+   If a customer would like to change the login, contact Odoo support `here
+   <https://www.odoo.com/help>`_.
+
+.. note::
+   Passwords for Odoo.com users and portal users remain separate, even if the same email address is
+   used.
+
+Add two-factor authentication
+=============================
+
+To add two-factor authentication, login into the Odoo.com user account from the Odoo.com login page.
+After logging-in, go to the upper-right corner of the screen, and click the :guilabel:`▼ (down
+arrow)` icon next to the :guilabel:`profile icon`. Then, select :guilabel:`My Account`, and a portal
+dashboard appears.
+
+If the user would like to turn on two-factor authentication (2FA) for Odoo.com access, click on the
+:guilabel:`Edit Security Settings` link below the :menuselection:`Account Security` section.
+
+Click on :guilabel:`Enable two-factor authentication` to turn on :abbr:`2FA (two-factor
+authentication)`. Then, confirm the current password in the :guilabel:`Password` field. Next, click
+on :guilabel:`Confirm Password`. Following that, activate :abbr:`2FA (two-factor authentication)` in
+a :abbr:`2FA (two-factor authentication)` app (Google Authenticator, Authy, etc.), by scanning the
+:guilabel:`QR code` or entering a :guilabel:`Verification Code`.
+
+Finally, click on :guilabel:`Enable two-factor authentication` to complete the setup.
+
+.. note::
+   Under :guilabel:`My Account` Odoo.com users can also access the following:
+
+   - :guilabel:`My Partner dashboard`
+   - :guilabel:`My In-App Services`
+   - :guilabel:`My Apps Dashboard`

content-rst/administration/odoo_online.rst

@@ -0,0 +1,151 @@
+===========
+Odoo Online
+===========
+
+`Odoo Online <https://www.odoo.com/trial>`_ provides private databases which are fully managed and
+hosted by Odoo. It can be used for long-term production or to test Odoo thoroughly, including
+customizations that don't require code.
+
+.. note::
+   Odoo Online is incompatible with custom modules or the Odoo App Store.
+
+Odoo Online databases are accessed using any web browser and do not require a local installation.
+
+To quickly try out Odoo, shared `demo <https://demo.odoo.com>`_ instances are available. No
+registration is required, but each instance only lives for a few hours.
+
+Database management
+===================
+
+To manage a database, go to the `database manager <https://www.odoo.com/my/databases>`_ and sign in
+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
+access the database via another URL.
+
+.. tip::
+   You can :ref:`register a domain name for free <domain-name/register>`.
+
+.. _odoo_online/tags:
+
+Tags
+====
+
+Add tags to easily identify and sort your databases.
+
+.. tip::
+   You can search for tags in the search bar.
+
+.. _odoo_online/delete:
+
+Delete
+======
+
+Delete a database instantly.
+
+.. danger::
+   Deleting a database means that all data is permanently lost. The deletion is instant and applies
+   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
+fully understood.
+
+.. image:: odoo_online/delete.png
+   :alt: The warning message displayed before deleting a database
+
+.. note::
+   - Only an administrator can delete a database.
+   - 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:
+
+Contact us
+==========
+
+Access the `Odoo.com support page <https://www.odoo.com/help>`_ with the database's details already
+pre-filled.
+
+.. _odoo_online/users:
+
+Invite / remove users
+=====================
+
+To invite users, fill out the new user's email address and click :guilabel:`Invite`. To add multiple
+users, click :guilabel:`Add more users`.
+
+.. image:: odoo_online/invite-users.png
+   :alt: Inviting a user on a database
+
+To remove users, select them and click :guilabel:`Remove`.
+
+.. seealso::
+   - :doc:`/applications/general/users`
+   - :doc:`odoo_accounts`

content-rst/administration/odoo_sh/advanced/frequent_technical_questions.rst

@@ -0,0 +1,60 @@
+
+.. _odoosh-advanced-frequent_technical_questions:
+
+============================
+Frequent Technical Questions
+============================
+
+"Scheduled actions do not run at the exact time they were expected"
+-------------------------------------------------------------------
+
+On the Odoo.sh platform, we cannot guarantee an exact running time for scheduled actions.
+
+This is due to the fact that there might be multiple customers on the same server, and we must guarantee a fair share of the server for every customer. Scheduled actions are therefore implemented slightly differently than on a regular Odoo server, and are run on a *best effort* policy.
+
+.. warning::
+    Do not expect any scheduled action to be run more often than every 5 min.
+
+Are there "best practices" regarding scheduled actions?
+-------------------------------------------------------
+
+**Odoo.sh always limits the execution time of scheduled actions (*aka* crons).**
+Therefore, you must keep this fact in mind when developing your own crons.
+
+We advise that:
+
+- Your scheduled actions should work on small batches of records.
+- Your scheduled actions should commit their work after processing each batch;
+  this way, if they get interrupted by the time-limit, there is no need to start over.
+- Your scheduled actions should be
+  `idempotent <https://stackoverflow.com/a/1077421/3332416>`_: they must not
+  cause side-effects if they are started more often than expected.
+
+.. _ip-address-change:
+
+How can I automate tasks when an IP address change occurs?
+----------------------------------------------------------
+
+**Odoo.sh notifies project administrators of IP address changes.**
+Additionally, when the IP address of a production instance changes, an HTTP `GET` request is made
+to the path `/_odoo.sh/ip-change` with the new IP address included as a query string parameter
+(`new`), along with the previous IP address as an additional parameter (`old`).
+
+This mechanism allows custom actions to be applied in response to the IP address change
+(e.g., sending an email, contacting a firewall API, configuring database objects, etc.)
+
+For security reasons, the `/_odoo.sh/ip-change` route is accessible only internally by the platform
+itself and returns a `403` response if accessed through any other means.
+
+Here is a pseudo-implementation example:
+
+.. code-block:: python
+
+    class IPChangeController(http.Controller):
+
+        @http.route('/_odoo.sh/ip-change', auth='public')
+        def ip_change(self, old=None, new=None):
+            _logger.info("IP address changed from %s to %s", old, new)
+            # Then perform whatever action required for your use case, e.g., update an
+            # ir.config_parameter, send an email, contact an external firewall service's API, ...
+            return 'ok'

content-rst/administration/odoo_sh/getting_started/branches.rst

@@ -295,7 +295,7 @@ Upgrade
 Available for production and staging branches for valid projects.
 
 .. seealso::
-    :doc:`Upgrade - Odoo.sh <../../upgrade/odoo_sh>`
+    :doc:`Upgrade documentation <../../upgrade>`
 
 .. _odoosh-gettingstarted-branches-tabs-settings:
 
@@ -402,9 +402,9 @@ we are considering the feature if there is enough demand.
 
 In case the domain of your users email addresses use SPF (Sender Policy Framework) or DKIM
 (DomainKeys Identified Mail), don't forget to authorize Odoo as a sending host in your domain name
-settings to increase the deliverability of your outgoing emails.
-The configuration steps are explained in the documentation about :ref:`SPF
-<email_communication/spf_compliant>` and :ref:`DKIM <email_communication/dkim_compliant>`.
+settings to increase the deliverability of your outgoing emails. The configuration steps are
+explained in the documentation about :ref:`SPF <email-domain-spf>` and :ref:`DKIM
+<email-domain-dkim>`.
 
 .. Warning::
   Forgetting to configure your SPF or DKIM to authorize Odoo as a sending host can lead to the

content-rst/administration/odoo_sh/getting_started/create.rst

@@ -0,0 +1,205 @@
+
+.. _odoosh-gettingstarted-create:
+
+===================
+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.
+
+.. image:: create/github-authorize.png
+   :align: center
+
+Odoo.sh basically needs:
+
+* to know your Github login and email,
+* to create a new repository in case you decide to start from scratch,
+* 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
+===================
+
+Choose if you want to start from scratch by creating a new repository, or if you want to use an
+existing repository.
+
+Then, choose a name or select the repository you want to use.
+
+Choose the Odoo version you want to use. If you plan to import an existing database or an existing
+set of applications, you might need to choose the according version. If you start from scratch, use
+the latest version.
+
+Enter your *subscription code*. This is also called *subscription referral*, *contract number* or
+*activation code*.
+
+It should be the code of your Enterprise subscription that includes Odoo.sh.
+
+Partners can use their partnership codes to start a trial. Should their clients start a project,
+they ought to get an Enterprise subscription including Odoo.sh and use its subscription code. The
+partner will get 50% of the amount back as commission. Contact your sales representative or account
+manager in order to get it.
+
+When submitting the form, if you are notified your subscription is not valid, it either means:
+
+* it is not an existing subscription,
+* it is not a partnership subscription,
+* it is an enterprise subscription, but which does not include Odoo.sh,
+* 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
+<https://www.odoo.com/help>`_.
+
+.. image:: create/deploy-form.png
+   :align: center
+
+You're done !
+=============
+
+You can start using Odoo.sh. Your first build is about to be created. You will soon be able to
+connect to your first database.
+
+.. image:: create/deploy-done.png
+   :align: center
+
+.. _odoo_sh_import_your_database:
+
+Import your database
+====================
+
+You can import your database in your Odoo.sh project as long as it is in a :doc:`supported version
+</administration/supported_versions>` of Odoo.
+
+Push your modules in production
+-------------------------------
+
+If you use community or custom modules, add them in 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
+Odoo addons. For instance, you can put all your modules folder in the root directory of your
+repository, or group the modules in folders by categories that you define (accounting, project,
+...).
+
+For community modules available in public Git repositories,
+you can also consider to add them using :ref:`Submodules <odoosh-advanced-submodules>`.
+
+Then, either :ref:`make this branch the production branch <odoosh-gettingstarted-branches-stages>`,
+or :ref:`merge it into your production branch <odoosh-gettingstarted-branches-mergingbranches>`.
+
+Download a backup
+-----------------
+
+On-premise databases
+~~~~~~~~~~~~~~~~~~~~
+
+Access the URL :file:`/web/database/manager` of your on-premise database and download a backup.
+
+.. Warning::
+
+  If you cannot access the database manager, it may have been disabled by your system administrator.
+  See the :ref:`database manager security documentation <db_manager_security>`.
+
+You will need the master password of your database server. If you do not have it, contact your
+system administrator.
+
+.. image:: create/create-import-onpremise-backup.png
+   :align: center
+
+Choose a zip including the filestore as the backup format.
+
+.. image:: create/create-import-onpremise-backup-dialog.png
+  :align: center
+
+Odoo Online databases
+~~~~~~~~~~~~~~~~~~~~~
+
+`Access your databases manager <https://accounts.odoo.com/my/databases/manage>`_ and download a
+backup of your database.
+
+.. image:: create/create-import-online-backup.png
+   :align: center
+
+.. 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
+just downloaded.
+
+.. image:: create/create-import-production.png
+   :align: center
+
+Once the backup imported, you can access the database using the *Connect* button in the history of
+the branch.
+
+.. image:: create/create-import-production-done.png
+   :align: center
+
+Check your 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.
+
+This is to prevent your newly imported database to perform actions that could impact your running
+production, such as sending the mails remaining in the queue, processing mass mailings, or
+third-party services synchronization (Calendars, files hosting, ...).
+
+If you plan to make the imported database your production, enable the scheduled actions you need.
+You can check what is enabled in the database of origin and enable the same actions in the imported
+database. Scheduled actions are located under :menuselection:`Settings --> Technical --> Automation
+--> Scheduled Actions`.
+
+Register your subscription
+--------------------------
+
+Your subscription is unlinked after the import.
+
+The imported database is considered a duplicate by default and the enterprise subscription is
+therefore removed, as you can only have one database linked per subscription.
+
+If you plan to make it your production, unlink your former database from the subscription, and
+register the newly imported database. Read the :doc:`database registration documentation
+<../../on_premise>` for instructions.

content-rst/administration/odoo_sh/getting_started/first_module.rst

@@ -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 <../../install/source>`:
+Or, from your computer, if you have an :doc:`installation of Odoo <../../on_premise/source>`:
 
 .. code-block:: bash
 
@@ -146,7 +146,7 @@ Manually
 --------
 
 If you want to create your module structure manually,
-you can follow the :doc:`/developer/tutorials/getting_started` tutorial to understand
+you can follow the :doc:`/developer/tutorials/server_framework_101` tutorial to understand
 the structure of a module and the content of each file.
 
 Push the development branch

content-rst/administration/odoo_sh/getting_started/settings.rst

@@ -0,0 +1,339 @@
+========
+Settings
+========
+
+Overview
+========
+
+The settings allow you to manage the configuration of your project.
+
+.. image:: settings/interface-settings.png
+   :align: center
+
+Project name
+============
+
+The name of your project.
+
+.. image:: settings/interface-settings-projectname.png
+   :align: center
+
+This defines the address that will be used to access your production database.
+
+Addresses of your staging and development builds are derived from this name and assigned
+automatically. However, when you change your project name, only future builds will use the new name.
+
+.. _odoosh-gettingstarted-settings-collaborators:
+
+Collaborators
+=============
+
+Manage the Github users who can access your project.
+
+.. image:: settings/interface-settings-collaborators.png
+   :align: center
+
+There are three levels of users:
+
+- :guilabel:`Admin`: has access to all features of an Odoo.sh project.
+
+- :guilabel:`Tester`: has access to the *Staging* and *Development* databases and their tooling.
+  This role is for users conducting User Acceptance Tests. Testers can work with copies of
+  production data but cannot access the production database through the Odoo.sh tooling.
+
+- :guilabel:`Developer`: has access only to the *Development* databases and their tooling. This
+  role is for developers who propose code modifications but are not allowed to access production
+  and staging databases through the Odoo.sh tooling.
+
+.. list-table::
+   :header-rows: 1
+   :widths: auto
+
+   * -
+     -
+     - Developer
+     - Tester
+     - Admin
+   * - Development
+     - History
+     - |green|
+     - |green|
+     - |green|
+   * -
+     - 1-click connect
+     - |green|
+     - |green|
+     - |green|
+   * -
+     - Logs
+     - |green|
+     - |green|
+     - |green|
+   * -
+     - Shell/SSH
+     - |green|
+     - |green|
+     - |green|
+   * -
+     - Mails
+     - |green|
+     - |green|
+     - |green|
+   * -
+     - Settings
+     - |green|
+     - |green|
+     - |green|
+   * - Staging
+     - History
+     - |green|
+     - |green|
+     - |green|
+   * -
+     - 1-click connect
+     -
+     - |green|
+     - |green|
+   * -
+     - Logs
+     -
+     - |green|
+     - |green|
+   * -
+     - Shell/SSH
+     -
+     - |green|
+     - |green|
+   * -
+     - Mails
+     -
+     - |green|
+     - |green|
+   * -
+     - Monitoring
+     -
+     - |green|
+     - |green|
+   * -
+     - Backups
+     -
+     -
+     - |green|
+   * -
+     - Upgrade
+     -
+     - |green|
+     - |green|
+   * -
+     - Settings
+     -
+     - |green|
+     - |green|
+   * - Production
+     - History
+     - |green|
+     - |green|
+     - |green|
+   * -
+     - 1-click connect
+     -
+     -
+     - |green|
+   * -
+     - Logs
+     -
+     -
+     - |green|
+   * -
+     - Shell/SSH
+     -
+     -
+     - |green|
+   * -
+     - Mails
+     -
+     -
+     - |green|
+   * -
+     - Monitoring
+     -
+     -
+     - |green|
+   * -
+     - Backups
+     -
+     -
+     - |green|
+   * -
+     - Upgrade
+     -
+     -
+     - |green|
+   * -
+     - Settings
+     -
+     -
+     - |green|
+   * - Status
+     -
+     - |green|
+     - |green|
+     - |green|
+   * - Settings
+     -
+     -
+     -
+     - |green|
+
+.. warning::
+   Those roles only apply to the usage of Odoo.sh. It is important to reflect the user roles
+   attribution within the repository on GitHub.  Please refer to the GitHub documentation section on
+   `Managing a branch protection rule <https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule>`_
+   for detailed guidance.
+
+.. |green| raw:: html
+
+   <span class="text-success" style="font-size: 32px; line-height: 0.5">●</span>
+
+.. |orange| raw:: html
+
+   <span class="text-warning" style="font-size: 32px; line-height: 0.5">●</span>
+
+.. |red| raw:: html
+
+   <span class="text-danger" style="font-size: 32px; line-height: 0.5">●</span>
+
+Public Access
+=============
+
+Allow public access to your development builds.
+
+.. image:: settings/interface-settings-public.png
+   :align: center
+
+If activated, this option exposes the Builds page publicly, allowing visitors to view logs of development builds.
+
+Production and staging builds are excluded, visitors can only see their status.
+
+.. _odoosh-gettingstarted-settings-modules-installation:
+
+GitHub commit statuses
+======================
+
+This option enables Odoo.sh to push commit statuses to your GitHub repository when a build is
+created or updated. It requires a GitHub token with permissions to push commit statuses to the
+repository. Refer to `GitHub's documentation on personal access tokens <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens>`_
+for instructions to create yours.
+
+.. note::
+    GitHub's **fine-grained personal tokens** have an expiration date and will be disabled if they
+    fail to update the commit status. You can replace the token at any time on Odoo.sh.
+
+The commit statuses pushed to GitHub can have the following contexts:
+
+- :guilabel:`ci/odoo.sh (dev)`: status of a development build
+- :guilabel:`ci/odoo.sh (staging)`: status of a staging build
+- :guilabel:`ci/odoo.sh (production)`: status of a production build
+- :guilabel:`ci/odoo.sh (test_ci)`: testing the token from the Settings page will push a test
+  status on the last commit of your repository
+
+Custom domains
+==============
+
+To configure additional domains please refer to the corresponding branch's :ref:`settings tab
+<odoosh-gettingstarted-branches-tabs-settings>`.
+
+.. _odoosh-gettingstarted-settings-submodules:
+
+Submodules
+==========
+
+Configure the deploy keys for the private repositories you use
+as submodules in your branches to allow Odoo.sh to download them.
+
+.. warning::
+   These settings are required for **private repositories** only. If you are looking on how to set
+   up your submodules, instructions are available in the chapter :ref:`Submodules
+   <odoosh-advanced-submodules>` of this documentation.
+
+.. image:: settings/interface-settings-submodules.png
+   :align: center
+
+When a repository is private, it is not possible to publicly download its branches and revisions.
+For that reason, you need to configure a deploy key for Odoo.sh,
+so the remote Git server allows our platform to download the revisions
+of this private repository.
+
+To configure the deploy key for a private repository, proceed as follows:
+
+* in the input, paste the SSH URL of your private sub-repository and click on *Add*,
+
+  * e.g. *git@github.com:USERNAME/REPOSITORY.git*
+  * it can be another Git server than Github, such as Bitbucket, Gitlab or even your own self-hosted
+    server
+
+* copy the public key,
+
+  * it should look like *ssh-rsa some...random...characters...here...==*
+
+* in the settings of the private sub-repository, add the public key amongst the deploy keys.
+
+  * Github.com: :menuselection:`Settings --> Deploy keys --> Add deploy key`
+  * Bitbucket.com: :menuselection:`Settings --> Access keys --> Add key`
+  * Gitlab.com: :menuselection:`Settings --> Repository --> Deploy Keys`
+  * Self-hosted: append the key to the git user’s authorized_keys file in its .ssh directory
+
+Storage Size
+============
+
+This section shows the storage size used by your project.
+
+.. image:: settings/interface-settings-storage.png
+   :align: center
+
+Storage size is computed as follows:
+
+* the size of the PostgreSQL database
+
+* the size of the disk files available in your container: database filestore, sessions storage directory...
+
+.. warning::
+   In case you want to analyze disk usage, you can run the tool `ncdu
+   <https://dev.yorhel.nl/ncdu/man>`_ in your Web Shell.
+
+Should your production database size grow to exceed what's provisioned in your subscription, it
+will automatically be synchronized with it.
+
+Database Workers
+================
+
+Additional database workers can be configured here. More workers help increase the load your
+production database is able to handle. If you add more, it will automatically be synchronized
+with your subscription.
+
+.. image:: settings/interface-settings-workers.png
+   :align: center
+
+.. Warning::
+  Adding more workers will not magically solve all performance issues. It only allows the server
+  to handle more connections at the same time. If some operations are unusually slow, it's most
+  likely a problem with the code, if it's not due to your own customizations you can open a ticket
+  `here <https://www.odoo.com/help>`_.
+
+Staging Branches
+================
+
+Additional staging branches allow you to develop and test more features at the same time. If you
+add more, it will automatically be synchronized with your subscription.
+
+.. image:: settings/interface-settings-staging-branches.png
+   :align: center
+
+Activation
+==========
+
+Shows the status of the project's activation. You can change the project's activation code if
+needed.
+
+.. image:: settings/interface-settings-activation.png
+   :align: center