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>

.gitattributes

@@ -0,0 +1,2 @@
+# Include RST files in language statistics on GitHub.
+*.rst linguist-detectable

.github/CODEOWNERS

@@ -1,11 +0,0 @@
-# All changes to technical files (build environment and Sphinx extensions) have to be approved
-/extensions/         @odoo/doc-review
-.gitignore           @odoo/doc-review
-commit_template.txt  @odoo/doc-review
-conf.py              @odoo/doc-review
-Makefile             @odoo/doc-review
-requirements.txt     @odoo/doc-review
-
-# All changes to legal material have to be approved
-/content/legal/     @odoo/legal
-/content/legal.rst  @odoo/legal

.gitignore

@@ -1,9 +1,11 @@
 *.pyc
-.*
 *.mo
+.*
+!.gitattributes
 
 # Sphinx build files
 _build/
 
 # Dependencies
 odoo
+venv/

.tx/config

@@ -1,63 +1,152 @@
 [main]
 host = https://www.transifex.com
-type = PO
 
-[odoo-14-doc.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: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
 
-[odoo-14-doc.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: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
 
-[odoo-14-doc.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: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
 
-[odoo-14-doc.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: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
 
-[odoo-14-doc.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: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
 
-[odoo-14-doc.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: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
 
-[odoo-14-doc.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: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
 
-[odoo-14-doc.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: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
 
-[odoo-14-doc.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: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
 
-[odoo-14-doc.theme]
-file_filter = locale/<lang>/LC_MESSAGES/sphinx.po
-source_file = locale/sources/sphinx.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
 
-[odoo-14-doc.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
 
-[odoo-14-doc.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

COPYRIGHT

@@ -0,0 +1,13 @@
+Most of the files are
+
+  Copyright (c) 2004-2023 Odoo S.A.
+
+Some files may also contain contributions from third
+parties. In this case the original copyright of
+the contributions can be traced through the
+history of the source version control system.
+
+When that is not the case, the files contain a prominent
+notice stating the original copyright and applicable
+license, or come with their own dedicated COPYRIGHT
+and/or LICENSE file.

LICENSE

@@ -0,0 +1,428 @@
+Attribution-ShareAlike 4.0 International
+
+=======================================================================
+
+Creative Commons Corporation ("Creative Commons") is not a law firm and
+does not provide legal services or legal advice. Distribution of
+Creative Commons public licenses does not create a lawyer-client or
+other relationship. Creative Commons makes its licenses and related
+information available on an "as-is" basis. Creative Commons gives no
+warranties regarding its licenses, any material licensed under their
+terms and conditions, or any related information. Creative Commons
+disclaims all liability for damages resulting from their use to the
+fullest extent possible.
+
+Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and
+conditions that creators and other rights holders may use to share
+original works of authorship and other material subject to copyright
+and certain other rights specified in the public license below. The
+following considerations are for informational purposes only, are not
+exhaustive, and do not form part of our licenses.
+
+     Considerations for licensors: Our public licenses are
+     intended for use by those authorized to give the public
+     permission to use material in ways otherwise restricted by
+     copyright and certain other rights. Our licenses are
+     irrevocable. Licensors should read and understand the terms
+     and conditions of the license they choose before applying it.
+     Licensors should also secure all rights necessary before
+     applying our licenses so that the public can reuse the
+     material as expected. Licensors should clearly mark any
+     material not subject to the license. This includes other CC-
+     licensed material, or material used under an exception or
+     limitation to copyright. More considerations for licensors:
+    wiki.creativecommons.org/Considerations_for_licensors
+
+     Considerations for the public: By using one of our public
+     licenses, a licensor grants the public permission to use the
+     licensed material under specified terms and conditions. If
+     the licensor's permission is not necessary for any reason--for
+     example, because of any applicable exception or limitation to
+     copyright--then that use is not regulated by the license. Our
+     licenses grant only permissions under copyright and certain
+     other rights that a licensor has authority to grant. Use of
+     the licensed material may still be restricted for other
+     reasons, including because others have copyright or other
+     rights in the material. A licensor may make special requests,
+     such as asking that all changes be marked or described.
+     Although not required by our licenses, you are encouraged to
+     respect those requests where reasonable. More considerations
+     for the public:
+    wiki.creativecommons.org/Considerations_for_licensees
+
+=======================================================================
+
+Creative Commons Attribution-ShareAlike 4.0 International Public
+License
+
+By exercising the Licensed Rights (defined below), You accept and agree
+to be bound by the terms and conditions of this Creative Commons
+Attribution-ShareAlike 4.0 International Public License ("Public
+License"). To the extent this Public License may be interpreted as a
+contract, You are granted the Licensed Rights in consideration of Your
+acceptance of these terms and conditions, and the Licensor grants You
+such rights in consideration of benefits the Licensor receives from
+making the Licensed Material available under these terms and
+conditions.
+
+
+Section 1 -- Definitions.
+
+  a. Adapted Material means material subject to Copyright and Similar
+     Rights that is derived from or based upon the Licensed Material
+     and in which the Licensed Material is translated, altered,
+     arranged, transformed, or otherwise modified in a manner requiring
+     permission under the Copyright and Similar Rights held by the
+     Licensor. For purposes of this Public License, where the Licensed
+     Material is a musical work, performance, or sound recording,
+     Adapted Material is always produced where the Licensed Material is
+     synched in timed relation with a moving image.
+
+  b. Adapter's License means the license You apply to Your Copyright
+     and Similar Rights in Your contributions to Adapted Material in
+     accordance with the terms and conditions of this Public License.
+
+  c. BY-SA Compatible License means a license listed at
+     creativecommons.org/compatiblelicenses, approved by Creative
+     Commons as essentially the equivalent of this Public License.
+
+  d. Copyright and Similar Rights means copyright and/or similar rights
+     closely related to copyright including, without limitation,
+     performance, broadcast, sound recording, and Sui Generis Database
+     Rights, without regard to how the rights are labeled or
+     categorized. For purposes of this Public License, the rights
+     specified in Section 2(b)(1)-(2) are not Copyright and Similar
+     Rights.
+
+  e. Effective Technological Measures means those measures that, in the
+     absence of proper authority, may not be circumvented under laws
+     fulfilling obligations under Article 11 of the WIPO Copyright
+     Treaty adopted on December 20, 1996, and/or similar international
+     agreements.
+
+  f. Exceptions and Limitations means fair use, fair dealing, and/or
+     any other exception or limitation to Copyright and Similar Rights
+     that applies to Your use of the Licensed Material.
+
+  g. License Elements means the license attributes listed in the name
+     of a Creative Commons Public License. The License Elements of this
+     Public License are Attribution and ShareAlike.
+
+  h. Licensed Material means the artistic or literary work, database,
+     or other material to which the Licensor applied this Public
+     License.
+
+  i. Licensed Rights means the rights granted to You subject to the
+     terms and conditions of this Public License, which are limited to
+     all Copyright and Similar Rights that apply to Your use of the
+     Licensed Material and that the Licensor has authority to license.
+
+  j. Licensor means the individual(s) or entity(ies) granting rights
+     under this Public License.
+
+  k. Share means to provide material to the public by any means or
+     process that requires permission under the Licensed Rights, such
+     as reproduction, public display, public performance, distribution,
+     dissemination, communication, or importation, and to make material
+     available to the public including in ways that members of the
+     public may access the material from a place and at a time
+     individually chosen by them.
+
+  l. Sui Generis Database Rights means rights other than copyright
+     resulting from Directive 96/9/EC of the European Parliament and of
+     the Council of 11 March 1996 on the legal protection of databases,
+     as amended and/or succeeded, as well as other essentially
+     equivalent rights anywhere in the world.
+
+  m. You means the individual or entity exercising the Licensed Rights
+     under this Public License. Your has a corresponding meaning.
+
+
+Section 2 -- Scope.
+
+  a. License grant.
+
+       1. Subject to the terms and conditions of this Public License,
+          the Licensor hereby grants You a worldwide, royalty-free,
+          non-sublicensable, non-exclusive, irrevocable license to
+          exercise the Licensed Rights in the Licensed Material to:
+
+            a. reproduce and Share the Licensed Material, in whole or
+               in part; and
+
+            b. produce, reproduce, and Share Adapted Material.
+
+       2. Exceptions and Limitations. For the avoidance of doubt, where
+          Exceptions and Limitations apply to Your use, this Public
+          License does not apply, and You do not need to comply with
+          its terms and conditions.
+
+       3. Term. The term of this Public License is specified in Section
+          6(a).
+
+       4. Media and formats; technical modifications allowed. The
+          Licensor authorizes You to exercise the Licensed Rights in
+          all media and formats whether now known or hereafter created,
+          and to make technical modifications necessary to do so. The
+          Licensor waives and/or agrees not to assert any right or
+          authority to forbid You from making technical modifications
+          necessary to exercise the Licensed Rights, including
+          technical modifications necessary to circumvent Effective
+          Technological Measures. For purposes of this Public License,
+          simply making modifications authorized by this Section 2(a)
+          (4) never produces Adapted Material.
+
+       5. Downstream recipients.
+
+            a. Offer from the Licensor -- Licensed Material. Every
+               recipient of the Licensed Material automatically
+               receives an offer from the Licensor to exercise the
+               Licensed Rights under the terms and conditions of this
+               Public License.
+
+            b. Additional offer from the Licensor -- Adapted Material.
+               Every recipient of Adapted Material from You
+               automatically receives an offer from the Licensor to
+               exercise the Licensed Rights in the Adapted Material
+               under the conditions of the Adapter's License You apply.
+
+            c. No downstream restrictions. You may not offer or impose
+               any additional or different terms or conditions on, or
+               apply any Effective Technological Measures to, the
+               Licensed Material if doing so restricts exercise of the
+               Licensed Rights by any recipient of the Licensed
+               Material.
+
+       6. No endorsement. Nothing in this Public License constitutes or
+          may be construed as permission to assert or imply that You
+          are, or that Your use of the Licensed Material is, connected
+          with, or sponsored, endorsed, or granted official status by,
+          the Licensor or others designated to receive attribution as
+          provided in Section 3(a)(1)(A)(i).
+
+  b. Other rights.
+
+       1. Moral rights, such as the right of integrity, are not
+          licensed under this Public License, nor are publicity,
+          privacy, and/or other similar personality rights; however, to
+          the extent possible, the Licensor waives and/or agrees not to
+          assert any such rights held by the Licensor to the limited
+          extent necessary to allow You to exercise the Licensed
+          Rights, but not otherwise.
+
+       2. Patent and trademark rights are not licensed under this
+          Public License.
+
+       3. To the extent possible, the Licensor waives any right to
+          collect royalties from You for the exercise of the Licensed
+          Rights, whether directly or through a collecting society
+          under any voluntary or waivable statutory or compulsory
+          licensing scheme. In all other cases the Licensor expressly
+          reserves any right to collect such royalties.
+
+
+Section 3 -- License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the
+following conditions.
+
+  a. Attribution.
+
+       1. If You Share the Licensed Material (including in modified
+          form), You must:
+
+            a. retain the following if it is supplied by the Licensor
+               with the Licensed Material:
+
+                 i. identification of the creator(s) of the Licensed
+                    Material and any others designated to receive
+                    attribution, in any reasonable manner requested by
+                    the Licensor (including by pseudonym if
+                    designated);
+
+                ii. a copyright notice;
+
+               iii. a notice that refers to this Public License;
+
+                iv. a notice that refers to the disclaimer of
+                    warranties;
+
+                 v. a URI or hyperlink to the Licensed Material to the
+                    extent reasonably practicable;
+
+            b. indicate if You modified the Licensed Material and
+               retain an indication of any previous modifications; and
+
+            c. indicate the Licensed Material is licensed under this
+               Public License, and include the text of, or the URI or
+               hyperlink to, this Public License.
+
+       2. You may satisfy the conditions in Section 3(a)(1) in any
+          reasonable manner based on the medium, means, and context in
+          which You Share the Licensed Material. For example, it may be
+          reasonable to satisfy the conditions by providing a URI or
+          hyperlink to a resource that includes the required
+          information.
+
+       3. If requested by the Licensor, You must remove any of the
+          information required by Section 3(a)(1)(A) to the extent
+          reasonably practicable.
+
+  b. ShareAlike.
+
+     In addition to the conditions in Section 3(a), if You Share
+     Adapted Material You produce, the following conditions also apply.
+
+       1. The Adapter's License You apply must be a Creative Commons
+          license with the same License Elements, this version or
+          later, or a BY-SA Compatible License.
+
+       2. You must include the text of, or the URI or hyperlink to, the
+          Adapter's License You apply. You may satisfy this condition
+          in any reasonable manner based on the medium, means, and
+          context in which You Share Adapted Material.
+
+       3. You may not offer or impose any additional or different terms
+          or conditions on, or apply any Effective Technological
+          Measures to, Adapted Material that restrict exercise of the
+          rights granted under the Adapter's License You apply.
+
+
+Section 4 -- Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that
+apply to Your use of the Licensed Material:
+
+  a. for the avoidance of doubt, Section 2(a)(1) grants You the right
+     to extract, reuse, reproduce, and Share all or a substantial
+     portion of the contents of the database;
+
+  b. if You include all or a substantial portion of the database
+     contents in a database in which You have Sui Generis Database
+     Rights, then the database in which You have Sui Generis Database
+     Rights (but not its individual contents) is Adapted Material,
+     including for purposes of Section 3(b); and
+
+  c. You must comply with the conditions in Section 3(a) if You Share
+     all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not
+replace Your obligations under this Public License where the Licensed
+Rights include other Copyright and Similar Rights.
+
+
+Section 5 -- Disclaimer of Warranties and Limitation of Liability.
+
+  a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
+     EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
+     AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
+     ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
+     IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
+     WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
+     PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
+     ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
+     KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
+     ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
+
+  b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
+     TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
+     NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
+     INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
+     COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
+     USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
+     DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
+     IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
+
+  c. The disclaimer of warranties and limitation of liability provided
+     above shall be interpreted in a manner that, to the extent
+     possible, most closely approximates an absolute disclaimer and
+     waiver of all liability.
+
+
+Section 6 -- Term and Termination.
+
+  a. This Public License applies for the term of the Copyright and
+     Similar Rights licensed here. However, if You fail to comply with
+     this Public License, then Your rights under this Public License
+     terminate automatically.
+
+  b. Where Your right to use the Licensed Material has terminated under
+     Section 6(a), it reinstates:
+
+       1. automatically as of the date the violation is cured, provided
+          it is cured within 30 days of Your discovery of the
+          violation; or
+
+       2. upon express reinstatement by the Licensor.
+
+     For the avoidance of doubt, this Section 6(b) does not affect any
+     right the Licensor may have to seek remedies for Your violations
+     of this Public License.
+
+  c. For the avoidance of doubt, the Licensor may also offer the
+     Licensed Material under separate terms or conditions or stop
+     distributing the Licensed Material at any time; however, doing so
+     will not terminate this Public License.
+
+  d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
+     License.
+
+
+Section 7 -- Other Terms and Conditions.
+
+  a. The Licensor shall not be bound by any additional or different
+     terms or conditions communicated by You unless expressly agreed.
+
+  b. Any arrangements, understandings, or agreements regarding the
+     Licensed Material not stated herein are separate from and
+     independent of the terms and conditions of this Public License.
+
+
+Section 8 -- Interpretation.
+
+  a. For the avoidance of doubt, this Public License does not, and
+     shall not be interpreted to, reduce, limit, restrict, or impose
+     conditions on any use of the Licensed Material that could lawfully
+     be made without permission under this Public License.
+
+  b. To the extent possible, if any provision of this Public License is
+     deemed unenforceable, it shall be automatically reformed to the
+     minimum extent necessary to make it enforceable. If the provision
+     cannot be reformed, it shall be severed from this Public License
+     without affecting the enforceability of the remaining terms and
+     conditions.
+
+  c. No term or condition of this Public License will be waived and no
+     failure to comply consented to unless expressly agreed to by the
+     Licensor.
+
+  d. Nothing in this Public License constitutes or may be interpreted
+     as a limitation upon, or waiver of, any privileges and immunities
+     that apply to the Licensor or You, including from the legal
+     processes of any jurisdiction or authority.
+
+
+=======================================================================
+
+Creative Commons is not a party to its public
+licenses. Notwithstanding, Creative Commons may elect to apply one of
+its public licenses to material it publishes and in those instances
+will be considered the “Licensor.” The text of the Creative Commons
+public licenses is dedicated to the public domain under the CC0 Public
+Domain Dedication. Except for the limited purpose of indicating that
+material is shared under a Creative Commons public license or as
+otherwise permitted by the Creative Commons policies published at
+creativecommons.org/policies, Creative Commons does not authorize the
+use of the trademark "Creative Commons" or any other trademark or logo
+of Creative Commons without its prior written consent including,
+without limitation, in connection with any unauthorized modifications
+to any of its public licenses or any other arrangements,
+understandings, or agreements concerning use of licensed material. For
+the avoidance of doubt, this paragraph does not form part of the
+public licenses.
+
+Creative Commons may be contacted at creativecommons.org.
+

Makefile

@@ -14,17 +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)
@@ -40,6 +55,7 @@ help:
 	@echo "  html         to build the documentation to HTML"
 	@echo "  fast         to build the documentation to HTML with shallow menu (faster)"
 	@echo "  clean        to delete the build files"
+	@echo "  test         to run the guidelines tests"
 
 clean:
 	@echo "Cleaning build files..."
@@ -48,12 +64,28 @@ 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
-# texlive-generic-recommended texlive-fonts-extra
+# texlive-fonts-extra
 latexpdf:
 	@echo "Starting build..."
 	$(SPHINX_BUILD) -c $(CONFIG_DIR) -b latex $(SPHINXOPTS) $(SOURCE_DIR) $(BUILD_DIR)/latex
@@ -69,14 +101,27 @@ gettext:
 $(HTML_BUILD_DIR)/_static/style.css: extensions/odoo_theme/static/style.scss extensions/odoo_theme/static/scss/*.scss
 	@echo "Compiling stylesheets..."
 	mkdir -p $(HTML_BUILD_DIR)/_static
-	pysassc extensions/odoo_theme/static/style.scss $(HTML_BUILD_DIR)/_static/style.css
+	python3 -m pysassc extensions/odoo_theme/static/style.scss $(HTML_BUILD_DIR)/_static/style.css
 	@echo "Compilation finished."
 
 #=== Development and debugging rules ===#
 
 fast: SPHINXOPTS += -A collapse_menu=True
-fast: html
+fast: hmlt
 
-static: $(HTML_BUILD_DIR)/static/style.css
+static: $(HTML_BUILD_DIR)/_static/style.css
 	cp -r extensions/odoo_theme/static/* $(HTML_BUILD_DIR)/_static/
 	cp -r static/* $(HTML_BUILD_DIR)/_static/
+
+# 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 redirects
+
+# Similar as `test`, but called only manually by content reviewers to trigger extra checks.
+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; \
+	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,50 +1,38 @@
-# Odoo documentation
+# Documentation
 
 ## Build the documentation locally
 
 ### Requirements
 
-- [Git](https://www.odoo.com/documentation/master/contributing/documentation.html#install-git)
-- [Python 3.6, 3.7, or 3.8](https://www.odoo.com/documentation/master/contributing/documentation.html#python)
-- Python dependencies listed in the file [`requirements.txt`](https://github.com/odoo/documentation/tree/master/requirements.txt).
-- [Make](https://www.odoo.com/documentation/master/contributing/documentation.html#make)
-- A local copy of the [odoo/odoo repository in master](https://github.com/odoo/odoo/tree/master) (Optional)
+- Git
+- Python 3.6, 3.7, or 3.8
+- 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
 
-1. In a terminal, navigate to the root directory and compile the documentation to HTML with the
-   following command:
-
-   ```sh
-   make
-   ```
-
+1. In a terminal, navigate to the root directory of the documentation and build it `make`.
    Additional commands are available with `make help`.
-
-2. Open the file `documentation/_build/html/index.html` in your web browser to display the render.
-
-3. See [this guide](https://www.odoo.com/documentation/master/contributing/documentation.html#preview-your-changes)
+2. Open the file `documentation/_build/html/index.html` in your web browser.
+3. See [this guide](https://www.odoo.com/documentation/latest/contributing/documentation.html)
    for more detailed instructions.
 
-Optional: to fully build the developer documentation with inline docstrings for documented Python
-functions, place your local copy of the `odoo/odoo` repository in the root directory. Alternatively,
-create a symbolic link with `odoo` as link name. If the Odoo sources are not found, a warning will
-be shown.
+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
 
 For contributions to the content of the documentation, please refer to the
-[Introduction Guide](https://www.odoo.com/documentation/master/contributing/documentation.html).
+[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
-[repository's issue tracker](https://github.com/odoo/documentation-user/issues) as usual.
-
-If you have a pull request that is ready for review, request one from the
-[odoo/doc-review](https://github.com/orgs/odoo/teams/doc-review) team.
-
+[repository's 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).
+[Scale-up, The Business Game](https://www.odoo.com/page/scale-up-business-game).

commit_template.txt

@@ -16,4 +16,4 @@
 # [REM] = Removal
 # [REF] = Refactoring (restructuring)
 # [MOV] = Move/rename
-#
+#

conf.py

@@ -1,182 +1,334 @@
-import re
 import os
+import re
+import shutil
 import sys
 from pathlib import Path
 
-from pygments.lexers import JsonLexer, XmlLexer
-from sphinx.util import logging
+import docutils
 import sphinx
+from pygments.lexers import JsonLexer, XmlLexer
+from sphinx.ext import graphviz
+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` if the version info for the project being documented, acts as replacement for |version|,
+# `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_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_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", "")
+# (*): 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",
+}
 
 # 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_dir = 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()
+]
 odoo_dir_in_path = False
-if not odoo_dir.is_dir():
-    parent_odoo_dir = Path('../odoo')
-    if parent_odoo_dir.is_dir():
-        _logger.info('Using parent dir to find odoo sources')
-        odoo_dir = parent_odoo_dir
-if not odoo_dir.is_dir():
+
+if not odoo_sources_dirs:
     _logger.warning(
-        f"Could not find Odoo sources directory at {odoo_dir.absolute()}.\n"
-        f"The 'Developer' documentation will be built but autodoc directives will be skipped.\n"
-        f"In order to fully build the 'Developer' documentation, clone the repository with "
-        f"`git clone https://github.com/odoo/odoo` or create a symbolink link."
+        "Could not find Odoo sources directory in neither of the following folders:\n"
+        "%(dir_list)s\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/odoo` or create a symbolic link.",
+        {
+            "dir_list": "\n".join(
+                [f"\t- {d.resolve()}" for d in odoo_sources_candidate_dirs]
+            )
+        },
     )
 else:
-    sys.path.insert(0, str(odoo_dir.absolute()))
-    from odoo import release as odoo_release  # Don't collide with Sphinx's 'release' config option
-    odoo_version = odoo_release.version if 'alpha' not in odoo_release.version else 'master'
+    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])
+    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
     if release != odoo_version:
         _logger.warning(
-            f"Found Odoo sources directory but with version '{odoo_version}' incompatible with "
-            f"documentation version '{version}'.\n"
-            f"The 'Developer' documentation will be built but autodoc directives will be skipped.\n"
-            f"In order to fully build the 'Developer' documentation, checkout the matching branch"
-            f" with `cd odoo && git checkout {version}`."
+            "Found Odoo sources in %(directory)s but with version '%(odoo_version)s' incompatible "
+            "with documentation version '%(doc_version)s'.\n"
+            "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,
+            },
         )
     else:
-        _logger.info(f"Found Odoo sources directory matching documentation version {release}.")
+        _logger.info(
+            "Found Odoo sources in %(directory)s matching documentation version '%(version)s'.",
+            {"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",
+}
+
 # The Sphinx extensions to use, as module names.
 # They can be extensions coming with Sphinx (named 'sphinx.ext.*') or custom ones.
 extensions = [
-    # Parse Python docstrings (autodoc, automodule, autoattribute directives)
-    'sphinx.ext.autodoc' if odoo_dir_in_path else 'autodoc_placeholder',
-
     # 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',
-
-    'exercise_admonition',
-
+    "embedded_video",
+    "custom_admonitions",
     # Redirection generator
-    'redirects',
-
-    # Code switcher (switcher and case directives)
-    'switcher',
-
+    "redirects",
+    # Content tabs
+    "sphinx_tabs.tabs",
+    # Cards
+    # "cards",
+    # 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",
     ]
+else:
+    extensions += [
+        "autodoc_placeholder",
+    ]
+extensions.append(
+    "sphinx.ext.graphviz" if shutil.which("dot") else "graphviz_placeholder"
+)
 
 todo_include_todos = False
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3/', None),
-    'werkzeug': ('https://werkzeug.palletsprojects.com/en/1.0.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
+    ]
+)
 
-supported_languages = {
-    'de': 'Deutsch',
-    'en': 'English',
-    'es': 'Español',
-    'fr': 'Français',
-    'nl': 'Nederlands',
-    'pt_BR': 'Português (BR)',
-    'uk': 'українська',
-    'zh_CN': '简体中文',
+# 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-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 specifications of redirect rules used by the redirects extension.
-redirects_file = 'redirects.txt'
+# 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",
+    "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)",
+}
 
-#=== Options for HTML output ===#
+# The directory in which files holding redirect rules used by the 'redirects' extension are listed.
+redirects_dir = "redirects/"
 
-html_theme = 'odoo_theme'
+sphinx_tabs_disable_tab_closing = True
+sphinx_tabs_disable_css_loading = True
+
+# Autodoc ordering
+autodoc_member_order = "bysource"
+
+# === Options for HTML output ===#
+
+html_theme = "odoo_theme"
 
 # 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_add_permalinks = '¶'  # Sphinx < 3.5
-html_permalinks = True  # Sphinx >= 3.5
+html_static_path = ["static"]
+html_permalinks = True
+
 # Additional JS & CSS files that can be imported with the 'custom-js' and 'custom-css' metadata.
 # Lists are empty because the files are specified in extensions/themes.
 html_js_files = []
@@ -184,77 +336,195 @@ 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': '14.0',
+    "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',
-     u'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/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/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"]
+
 # 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):
+    """Substitute parts of strings with computed values.
+
+    Since the RST substitution is not working everywhere, i.e. in directives'
+    options, we need to be able to input those values when reading the sources.
+    This is using the config `source_read_replace_vals`, mapping a name to its
+    replacement. This will look for the name surrounded by curly braces in the source.
+
+    Meant to be connected to the `source-read` event.
+    """
+    result = source[0]
+    for key in app.config.source_read_replace_vals:
+        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("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")
+
+    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
+        original_run = to_patch.run
+
+        def new_run(self):
+            if not self.options.get("condition", True):
+                return []
+            return original_run(self)
+
+        to_patch.run = new_run
+
+    for to_patch in (
+        sphinx.directives.code.LiteralInclude,
+        docutils.parsers.rst.directives.tables.CSVTable,
+    ):
+        patch(to_patch)
 
 
 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
@@ -263,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
@@ -275,65 +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.
         """
-        # If the list of versions is not set, assume that the project has no alternate version
-        _alternate_versions = app.config.versions and app.config.versions.split(',') or []
-        context['alternate_versions'] = [
-            (_alternate_version, _build_url(_version=_alternate_version))
-            for _alternate_version in sorted(_alternate_versions, reverse=True)
-            if _alternate_version != version and (
-                _alternate_version != 'master' or pagename.startswith('developer')
-            )
-        ]
+        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 []
+        )
+
+        # Map alternate versions to their display names and URLs.
+        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(
+                    (_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'
-        # Replace the context value by its translated description ("Français" instead of "french")
-        context['language'] = supported_languages.get(_current_lang)
+        _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_code"] = _current_lang
 
         # If the list of languages is not set, assume that the project has no alternate language
-        _alternate_languages = app.config.languages and app.config.languages.split(',') or []
-        context['alternate_languages'] = [
-            (
-                supported_languages.get(_alternate_lang),
-                _alternate_lang.split('_')[0] if _alternate_lang != 'en' else 'x-default',
-                _build_url(_lang=_alternate_lang),
-            )
-            for _alternate_lang in _alternate_languages
-            if _alternate_lang in supported_languages and _alternate_lang != _current_lang
-        ]
+        _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():
+            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"
+                        ),
+                        _build_url(_lang=_alternate_lang),
+                    )
+                )
+
+        # Dynamic generation of localized legal doc links
+        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.rst

@@ -0,0 +1,12 @@
+:nosearch:
+
+========
+Advanced
+========
+
+.. toctree::
+   :titlesonly:
+
+   advanced/containers
+   advanced/submodules
+   advanced/frequent_technical_questions

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

@@ -1,7 +1,7 @@
 
-==================================
+==========
 Containers
-==================================
+==========
 
 Overview
 ========
@@ -17,7 +17,7 @@ The platform will take care to install these dependencies in your containers.
 `The pip requirements specifiers <https://pip.pypa.io/en/stable/reference/pip_install/#requirement-specifiers>`_
 documentation can help you write a :file:`requirements.txt` file.
 To have a concrete example,
-check out the `requirements.txt file of Odoo <https://github.com/odoo/odoo/blob/14.0/requirements.txt>`_.
+check out the `requirements.txt file of Odoo <{GITHUB_PATH}/requirements.txt>`_.
 
 The :file:`requirements.txt` files of submodules are taken into account as well. The platform
 looks for :file:`requirements.txt` files in each folder containing Odoo modules: Not in the module folder itself,
@@ -167,16 +167,16 @@ In the above commands, the argument:
 * ``--stop-after-init`` will immediately shutdown the server instance after it completed the operations you asked.
 
 More options are available and detailed in the
-:doc:`CLI documentation </developer/misc/other/cmdline>`.
+:doc:`CLI documentation </developer/reference/cli>`.
 
 You can find in the logs (*~/logs/odoo.log*) the addons path used by Odoo.sh to run your server.
 Look for "*odoo: addons paths*":
 
 ::
 
-  2018-02-19 10:51:39,267 4 INFO ? odoo: Odoo version 13.0
+  2018-02-19 10:51:39,267 4 INFO ? odoo: Odoo version {BRANCH}
   2018-02-19 10:51:39,268 4 INFO ? odoo: Using configuration file at /home/odoo/.config/odoo/odoo.conf
-  2018-02-19 10:51:39,268 4 INFO ? odoo: addons paths: ['/home/odoo/data/addons/13.0', '/home/odoo/src/user', '/home/odoo/src/enterprise', '/home/odoo/src/themes', '/home/odoo/src/odoo/addons', '/home/odoo/src/odoo/odoo/addons']
+  2018-02-19 10:51:39,268 4 INFO ? odoo: addons paths: ['/home/odoo/data/addons/{BRANCH}', '/home/odoo/src/user', '/home/odoo/src/enterprise', '/home/odoo/src/themes', '/home/odoo/src/odoo/addons', '/home/odoo/src/odoo/odoo/addons']
 
 **Be careful**, especially with your production database.
 Operations that you perform running this Odoo server instance are not isolated:
@@ -232,6 +232,6 @@ Save the file and then run the Odoo Shell:
 Finally, *via* the Odoo Shell, you can trigger the piece of code/function/method
 you want to debug.
 
-.. image:: ./media/pdb_sh.png
+.. image:: containers/pdb_sh.png
     :align: center
     :alt: Console screenshot showing ``pdb`` running in an Odoo.sh shell.

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/advanced/submodules.rst

@@ -1,9 +1,9 @@
 
 .. _odoosh-advanced-submodules:
 
-==================================
+==========
 Submodules
-==================================
+==========
 
 Overview
 ========
@@ -44,7 +44,7 @@ On Odoo.sh, in the branches view of your project, choose the branch in which you
 
 In the upper right corner, click on the *Submodule* button, and then on *Run*.
 
-.. image:: ./media/advanced-submodules-button.png
+.. image:: submodules/advanced-submodules-button.png
    :align: center
 
 A dialog with a form is shown. Fill the inputs as follows:
@@ -53,18 +53,18 @@ A dialog with a form is shown. Fill the inputs as follows:
 * Branch: The branch you want to use.
 * Path: The folder in which you want to add this submodule in your branch.
 
-.. image:: ./media/advanced-submodules-dialog.png
+.. image:: submodules/advanced-submodules-dialog.png
    :align: center
 
 On Github, you can get the repository URL with the *Clone or download* button of the repository. Make sure to *use SSH*.
 
-.. image:: ./media/advanced-submodules-github-sshurl.png
+.. image:: submodules/advanced-submodules-github-sshurl.png
   :align: center
 
 .. _odoosh-advanced-submodules-withgit:
 
 With Git (advanced)
----------------------
+-------------------
 
 In a terminal, in the folder where your Git repository is cloned,
 checkout the branch in which you want to add a submodule:

content-rst/administration/odoo_sh/getting_started.rst

@@ -0,0 +1,16 @@
+:nosearch:
+
+===========
+Get started
+===========
+
+.. toctree::
+   :titlesonly:
+
+   getting_started/create
+   getting_started/branches
+   getting_started/builds
+   getting_started/status
+   getting_started/settings
+   getting_started/online-editor
+   getting_started/first_module

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

@@ -1,32 +1,32 @@
-
-==================================
+========
 Branches
-==================================
+========
 
 Overview
 ========
 
 The branches view gives you an overview of the different branches your repository has.
 
-.. image:: ./media/interface-branches.png
+.. image:: branches/interface-branches.png
    :align: center
 
 .. _odoosh-gettingstarted-branches-stages:
 
 Stages
-===============
+======
 
 Odoo.sh offers three different stages for your branches: production, staging and development.
 
 You can change the stage of a branch by drag and dropping it into the stage section title.
 
-.. image:: ./media/interface-branches-stagechange.png
+.. image:: branches/interface-branches-stagechange.png
    :align: center
 
 .. _stage_production:
 
 Production
 ----------
+
 This is the branch holding the code on which your production database runs.
 There can be only one production branch.
 
@@ -42,7 +42,7 @@ instance will be held temporarily unavailable for maintenance reason.
 
 This method is equivalent to perform an upgrade of the module through the Apps menu,
 or through the :code:`-u` switch of
-:doc:`the command line </developer/misc/other/cmdline>`.
+:doc:`the command line </developer/reference/cli>`.
 
 In the case the changes in the commit prevent the server to restart,
 or if the modules update fails,
@@ -59,6 +59,7 @@ will automatically be set back to the development stage after 30 days.
 
 Staging
 -------
+
 Staging branches are meant to test your new features using the production data without compromising
 the actual production database with test records. They will create databases that are neutralized
 duplicates of the production database.
@@ -71,7 +72,7 @@ The neutralization includes:
 * Disabling outgoing emails by intercepting them with a mailcatcher. An
   :ref:`interface to view <odoosh-gettingstarted-branches-tabs-mails>` the emails sent by your
   database is provided. That way, you do not have to worry about sending test emails to your contacts.
-* Setting payment acquirers and shipping providers in test mode.
+* Setting payment providers and shipping providers in test mode.
 * Disabling IAP services
 
 The latest database will be kept alive indefinitely, older ones from the same branch may get garbage collected
@@ -83,9 +84,9 @@ The unit tests are not performed as, in Odoo, they currently rely on the demo da
 production database. In the future, if Odoo supports to run the unit tests without the demo data,
 Odoo.sh will then consider running the tests on staging databases.
 
-
 Development
 -----------
+
 Development branches create new databases using the demo data to run the unit tests.
 The installed modules are the ones included in your branches. You can change this list of modules
 to install in your :ref:`project Settings <odoosh-gettingstarted-settings-modules-installation>`.
@@ -98,7 +99,7 @@ disable the tests or allow specific tests to be run with custom tags in the :ref
 <odoosh-gettingstarted-branches-tabs-settings>`.
 
 Similar to staging branches, the emails are not sent but are intercepted by a mailcatcher and
-scheduled actions are not triggered as often is the database is not in use.
+scheduled actions are not triggered as long as the database is not in use.
 
 The databases created for development branches are meant to live around three days.
 After that, they can be automatically garbage collected to make room for new databases without prior notice.
@@ -107,9 +108,10 @@ After that, they can be automatically garbage collected to make room for new dat
 
 Merging your branches
 ---------------------
+
 You can merge your branches easily by drag and dropping them into each other.
 
-.. image:: ./media/interface-branches-merge.png
+.. image:: branches/interface-branches-merge.png
    :align: center
 
 When you want to test the changes of your development branches with the production data,
@@ -147,16 +149,17 @@ If you test configuration changes in staging branches, and want them to be appli
 .. _odoosh-gettingstarted-branches-tabs:
 
 Tabs
-=============
+====
 
 History
 -------
+
 An overview of your branch history:
 
 * The messages of the commits and their authors,
 * The various events linked to the platform, such as stage changes, database imports, backup restores.
 
-.. image:: ./media/interface-branches-history.png
+.. image:: branches/interface-branches-history.png
    :align: center
 
 For each event, a status is displayed in the top right-hand corner.
@@ -168,36 +171,38 @@ When an operation is successful, you can access the database thanks to the *conn
 
 Mails
 -----
+
 This tab contains the mail catcher. It displays an overview of the emails sent by your database.
 The mail catcher is available for your development and
 staging branches as the emails of your production database are really sent instead of being intercepted.
 
-.. image:: ./media/interface-branches-mails.png
+.. image:: branches/interface-branches-mails.png
    :align: center
    :scale: 50%
 
 Shell
 -----
+
 A shell access to your container. You can perform basic linux commands (:code:`ls`, :code:`top`)
 and open a shell on your database by typing :code:`psql`.
 
-.. image:: ./media/interface-branches-shell.png
+.. image:: branches/interface-branches-shell.png
    :align: center
 
 You can open multiple tabs and drag-and-drop them to arrange the layout as you wish,
 for instance side by side.
 
-
 .. Note::
   Long running shell instances are not guaranteed. Idle shells can be
   disconnected at anytime in order to free up resources.
 
 Editor
 ------
+
 An online integrated development environment (IDE) to edit the source code.
 You can also open terminals, Python consoles and even Odoo Shell consoles.
 
-.. image:: ./media/interface-branches-editor.png
+.. image:: branches/interface-branches-editor.png
    :align: center
 
 You can open multiple tabs and drag-and-drop them to arrange the layout as you wish,
@@ -205,19 +210,23 @@ for instance side by side.
 
 Monitoring
 ----------
+
 This link contains various monitoring metrics of the current build.
 
-.. image:: ./media/interface-branches-monitoring.png
+.. image:: branches/interface-branches-monitoring.png
    :align: center
 
 You can zoom, change the time range or select a specific metric on each graph.
 On the graphs, annotations help you relate to changes on the build (database import, git push, etc...).
 
+.. _odoosh/logs:
+
 Logs
 ----
+
 A viewer to have a look to your server logs.
 
-.. image:: ./media/interface-branches-logs.png
+.. image:: branches/interface-branches-logs.png
    :align: center
 
 Different logs are available:
@@ -238,10 +247,11 @@ The fetching is automatically stopped after 5 minutes. You can restart it using
 
 Backups
 -------
+
 A list of the backups available for download and restore, the ability to perform a manual backup and to import a
 database.
 
-.. image:: ./media/interface-branches-backups.png
+.. image:: branches/interface-branches-backups.png
    :align: center
 
 Odoo.sh makes daily backups of the production database. It keeps 7 daily, 4 weekly and 3 monthly backups.
@@ -257,16 +267,16 @@ This server only keeps one month of backups: 7 daily and 4 weekly backups.
 Dedicated backup servers keep the same backups, as well as 3 additional monthly backups.
 To restore or download one of these monthly backups, please `contact us <https://www.odoo.com/help>`_.
 
-If you merge a commit updating the version of one or several modules (in :file:`__manifest__.py`), or their linked python 
-dependencies (in :file:`requirements.txt`), then Odoo.sh performs a backup automatically (flagged with type Update in the list), 
-as either the container will be changed by the installation of new pip packages, either the database itself will be 
-changed with the module update triggered afterwards. In these two cases, we are doing a backup as it may potentially 
+If you merge a commit updating the version of one or several modules (in :file:`__manifest__.py`), or their linked python
+dependencies (in :file:`requirements.txt`), then Odoo.sh performs a backup automatically (flagged with type Update in the list),
+as either the container will be changed by the installation of new pip packages, either the database itself will be
+changed with the module update triggered afterwards. In these two cases, we are doing a backup as it may potentially
 break things.
 
-If you merge a commit that only changes some code without the above-mentioned modifications, then no backup is done 
-by Odoo.sh, as neither the container nor the database is modified so the platform considers this safe enough. Of course, 
-as an extra precaution, you can make a backup manually before making big changes in your production sources in case 
-something goes wrong (those manual backups are available for about one week). To avoid abuse, we limit manual backups 
+If you merge a commit that only changes some code without the above-mentioned modifications, then no backup is done
+by Odoo.sh, as neither the container nor the database is modified so the platform considers this safe enough. Of course,
+as an extra precaution, you can make a backup manually before making big changes in your production sources in case
+something goes wrong (those manual backups are available for about one week). To avoid abuse, we limit manual backups
 to 5 per day.
 
 The *import database* feature accepts database archives in the format provided by:
@@ -277,13 +287,24 @@ The *import database* feature accepts database archives in the format provided b
 * the Odoo.sh backup download button of this *Backups* tab,
 * the Odoo.sh dump download button in the :ref:`Builds view <odoosh-gettingstarted-builds>`.
 
+.. _odoo_sh/upgrade:
+
+Upgrade
+-------
+
+Available for production and staging branches for valid projects.
+
+.. seealso::
+    :doc:`Upgrade documentation <../../upgrade>`
+
 .. _odoosh-gettingstarted-branches-tabs-settings:
 
 Settings
 --------
+
 Here you can find a couple of settings that only apply to the currently selected branch.
 
-.. image:: ./media/interface-branches-settings.jpg
+.. image:: branches/interface-branches-settings.jpg
    :align: center
 
 **Behaviour upon new commit**
@@ -300,7 +321,7 @@ back from staging to development will automatically be set to 'Do nothing'.
 
 Choose the modules to install automatically for your development builds.
 
-.. image:: ./media/interface-settings-modulesinstallation.png
+.. image:: branches/interface-settings-modulesinstallation.png
    :align: center
 
 * *Install only my modules* will install the modules of the branch only. This is the default option.
@@ -381,19 +402,20 @@ 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 :ref:`Discuss app documentation <discuss-email_servers-spf-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
   delivery of your emails as spam in your contacts inbox.
 
-
 Shell commands
 ==============
+
 In the top right-hand corner of the view, different shell commands are available.
 
-.. image:: ./media/interface-branches-shellcommands.png
+.. image:: branches/interface-branches-shellcommands.png
    :align: center
 
 Each command can be copied in the clipboard to be used in a terminal,
@@ -403,6 +425,7 @@ such as ``<URL>``, ``<PATH>``, ...
 
 Clone
 -----
+
 Download the Git repository.
 
 .. code-block:: bash
@@ -418,6 +441,7 @@ The *run* button is not available for this command, as it is meant to be used on
 
 Fork
 ----
+
 Create a new branch based on the current branch.
 
 .. code-block:: bash
@@ -434,6 +458,7 @@ Uploads the new branch *feature-1* on your remote repository.
 
 Merge
 -----
+
 Merge the current branch in another branch.
 
 .. code-block:: bash
@@ -450,8 +475,10 @@ Uploads the changes you just added in the *master* branch on your remote reposit
 
 SSH
 ---
+
 Setup
 ~~~~~
+
 In order to use SSH, you have to set up your profile SSH public key (if it is not already done).
 To do so, follow these steps:
 
@@ -462,12 +489,12 @@ To do so, follow these steps:
    (only apply the step 1)
 #. Paste the copied content to your profile SSH keys and press "Add"
 
-   .. image:: ./media/SSH-key-pasting.png
+   .. image:: branches/SSH-key-pasting.png
       :align: center
 
 #. The key should appear below
 
-   .. image:: ./media/SSH-key-appearing.png
+   .. image:: branches/SSH-key-appearing.png
       :align: center
 
 Connection
@@ -481,7 +508,7 @@ To connect to your builds using ssh use the following command in a terminal:
 
 You will find a shortcut for this command into the SSH tab in the upper right corner.
 
-.. image:: ./media/SSH-panel.png
+.. image:: branches/SSH-panel.png
    :align: center
 
 Provided you have the :ref:`correct access rights <odoosh-gettingstarted-settings-collaborators>` on the project,
@@ -491,7 +518,6 @@ you'll be granted ssh access to the build.
   Long running ssh connections are not guaranteed. Idle connections will be
   disconnected in order to free up resources.
 
-
 Submodule
 ---------
 

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

@@ -0,0 +1,124 @@
+
+.. _odoosh-gettingstarted-builds:
+
+======
+Builds
+======
+
+Overview
+========
+
+In Odoo.sh, a build is considered as a database loaded by an Odoo server
+(`odoo/odoo <https://github.com/odoo/odoo>`_ & `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 well-behavior of the server, the database
+and the features with this revision.
+
+.. image:: builds/interface-builds.png
+   :align: center
+
+In this view, a row represents a branch, and a cell of a row represents a build of this branch.
+
+Most of the time, builds are created following pushes on your Github repository branches.
+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 successful build is highlighted in green.
+
+A build is considered failed if errors come up during its creation.
+A failed build is highlighted in red.
+
+If warnings come up during the creation, but there are no errors, the build is considered almost
+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
+======
+
+Production
+----------
+
+The first build of a production branch creates a database from scratch.
+If this build is successful, this database is considered as the production database of your project.
+
+From then, pushes on the production branch will create new builds that attempt to load the database
+using a server running with the new revision.
+
+If the build is successful, or has warnings but no errors, the production database will now run with
+this build, along with the revision associated to this build.
+
+If the build fails to load or update the database, then the previous successful build is re-used to
+load the database, and therefore the database will run using a server running with the previous
+successful revision.
+
+The build used to run the production database is always the first of the builds list. If a build
+fails, it is put after the build currently running the production database.
+
+Staging
+-------
+
+Staging builds duplicate the production database,
+and try to load this duplicate with the revisions of the staging branches.
+
+Each time you push a new revision on a staging branch, the build created uses a new copy of the
+production database. The databases are not re-used between builds of the same branch. This ensures:
+
+* staging builds use databases that are close to what the production looks like, so you do not make
+  your tests with outdated data,
+
+* you can play around as much as you want in the same staging database, and you can then ask for a
+  rebuild when you want to restart with a new copy of the production.
+
+Nevertheless, this means that if you make configuration changes in staging databases and do not
+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.
+
+A build will be considered failed and highlighted in red if tests fail during the installation,
+as they are meant to raise errors if something wrong occurs.
+
+If all tests pass, and there is no error, the build will be considered successful.
+
+According to the list of modules to install and test, a development build can take up to 1 hour to
+be ready. This is due to the large number of tests set in the default Odoo modules suite.
+
+Features
+========
+
+The production branch will always appear first, and then the other branches are ordered by last
+build created. You can filter out the branches.
+
+.. image:: builds/interface-builds-branches.png
+   :align: center
+
+For each branch, you can access the last build's database using the *Connect* link and jump to the
+branch code using the *Github* link. For other branches than the production, you can create a new
+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
+   :align: center
+
+For each build, you can access the revision changes using the button with the Github icon. You can
+access the build's database as the administrator using the *Connect* button. Also, you can access
+the database with another user using the *Connect as* button, in the dropdown menu of the *Connect*
+button.
+
+.. _odoosh-gettingstarted-builds-download-dump:
+
+.. image:: builds/interface-builds-build-dropdown.png
+   :align: center
+
+.. _odoosh-gettingstarted-builds-dropdown-menu:
+
+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-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

@@ -1,14 +1,14 @@
-
-==================================
+=================
 Your first module
-==================================
+=================
 
 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 you know your Github repository's URL.
+This tutorial requires :ref:`you created a project on Odoo.sh <odoosh-gettingstarted-create>`, and
+you know your Github repository's URL.
 
 Basic use of Git and Github is explained.
 
@@ -27,7 +27,7 @@ Create the development branch
 =============================
 
 From Odoo.sh
--------------
+------------
 
 In the branches view:
 
@@ -37,26 +37,24 @@ In the branches view:
 
   |pic1|  |pic2|
 
-.. |pic1| image:: ./media/firstmodule-development-+.png
+.. |pic1| image:: first_module/firstmodule-development-+.png
    :width: 45%
 
-.. |pic2| image:: ./media/firstmodule-development-fork.png
+.. |pic2| image:: first_module/firstmodule-development-fork.png
    :width: 45%
 
-
 Once the build created, you can access the editor and browse to the folder *~/src/user* to access
 to the code of your development branch.
 
-.. image:: ./media/firstmodule-development-editor.png
-  :align: center
+.. image:: first_module/firstmodule-development-editor.png
+   :align: center
 
-.. image:: ./media/firstmodule-development-editor-interface.png
-  :align: center
+.. image:: first_module/firstmodule-development-editor-interface.png
+   :align: center
 
 From your computer
 ------------------
 
-
 Clone your Github repository on your computer:
 
 .. code-block:: bash
@@ -72,7 +70,6 @@ Create a new branch:
 
   $ git checkout -b feature-1 master
 
-
 Create the module structure
 ===========================
 
@@ -88,15 +85,15 @@ From the Odoo.sh editor, in a terminal:
 
   $ odoo-bin scaffold my_module ~/src/user/
 
-Or, from your computer, if you have an :ref:`installation of Odoo <setup/install/source>`:
+Or, from your computer, if you have an :doc:`installation of Odoo <../../on_premise/source>`:
 
 .. code-block:: bash
 
   $ ./odoo-bin scaffold my_module ~/src/odoo-addons/
 
 If you do not want to bother installing Odoo on your computer,
-you can also :download:`download this module structure template <media/my_module.zip>` in which you replace every occurrences of
-*my_module* to the name of your choice.
+you can also :download:`download this module structure template <first_module/my_module.zip>` in
+which you replace every occurrences of *my_module* to the name of your choice.
 
 The below structure will be generated:
 
@@ -119,11 +116,11 @@ The below structure will be generated:
       ├── templates.xml
       └── views.xml
 
-.. Warning::
+.. warning::
 
-  Do not use special characters other than the underscore ( _ ) for your module name, not even an hyphen ( - ).
-  This name is used for the Python classes of your module,
-  and having classes name with special characters other than the underscore is not valid in Python.
+   Do not use special characters other than the underscore ( _ ) for your module name, not even an
+   hyphen ( - ). This name is used for the Python classes of your module, and having classes name
+   with special characters other than the underscore is not valid in Python.
 
 Uncomment the content of the files:
 
@@ -141,7 +138,7 @@ Uncomment the content of the files:
   the manifest of your module, including for instance its title, description and data files to load.
   You just need to uncomment the access control list data file:
 
-  .. code-block:: xml
+  .. code-block:: python
 
     # 'security/ir.model.access.csv',
 
@@ -149,7 +146,7 @@ Manually
 --------
 
 If you want to create your module structure manually,
-you can follow :doc:`Build an Odoo module </developer/howtos/backend>` 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
@@ -180,8 +177,8 @@ The above command is explained in the section
 <odoosh-gettingstarted-online-editor-push>` of the
 :ref:`Online Editor <odoosh-gettingstarted-online-editor>`
 chapter.
-It includes the explanation regarding the fact you will be prompted to type your username and password,
-and what to do if you use the two-factor authentication.
+It includes the explanation regarding the fact you will be prompted to type your username and
+password, and what to do if you use the two-factor authentication.
 
 Or, from your computer terminal:
 
@@ -201,27 +198,27 @@ Test your module
 
 Your branch should appear in your development branches in your project.
 
-.. image:: ./media/firstmodule-test-branch.png
+.. image:: first_module/firstmodule-test-branch.png
   :align: center
 
 In the branches view of your project,
 you can click on your branch name in the left navigation panel to access its history.
 
-.. image:: ./media/firstmodule-test-branch-history.png
+.. image:: first_module/firstmodule-test-branch-history.png
   :align: center
 
 You can see here the changes you just pushed, including the comment you set.
 Once the database ready, you can access it by clicking the *Connect* button.
 
-.. image:: ./media/firstmodule-test-database.png
+.. image:: first_module/firstmodule-test-database.png
   :align: center
 
 If your Odoo.sh project is configured to install your module automatically,
-you will directly see it amongst the database apps. Otherwise, it will be available in the apps to install.
+you will directly see it amongst the database apps. Otherwise, it will be available in the apps to
+install.
 
 You can then play around with your module, create new records and test your features and buttons.
 
-
 Test with the production data
 =============================
 
@@ -232,23 +229,24 @@ you can test it with the production data using a staging branch.
 
 You can either:
 
-* Make your development branch a staging branch, by drag and dropping it onto the *staging* section title.
+* Make your development branch a staging branch, by drag and dropping it onto the *staging* section
+  title.
 
-  .. image:: ./media/firstmodule-test-devtostaging.png
-    :align: center
+  .. image:: first_module/firstmodule-test-devtostaging.png
+     :align: center
 
 * Merge it in an existing staging branch, by drag and dropping it onto the given staging branch.
 
-  .. image:: ./media/firstmodule-test-devinstaging.png
-    :align: center
+  .. image:: first_module/firstmodule-test-devinstaging.png
+     :align: center
 
 You can also use the :code:`git merge` command to merge your branches.
 
-This will create a new staging build, which will duplicate the production database and make it run using a server
-updated with your latest changes of your branch.
+This will create a new staging build, which will duplicate the production database and make it run
+using a server updated with your latest changes of your branch.
 
-.. image:: ./media/firstmodule-test-mergedinstaging.png
-  :align: center
+.. image:: first_module/firstmodule-test-mergedinstaging.png
+   :align: center
 
 Once the database ready, you can access it using the *Connect* button.
 
@@ -257,22 +255,24 @@ Once the database ready, you can access it using the *Connect* button.
 Install your module
 -------------------
 
-Your module will not be installed automatically, you have to install it from the apps menu.
-Indeed, the purpose of the staging build is to test the behavior of your changes as it would be on your production,
-and on your production you would not like your module to be installed automatically, but on demand.
+Your module will not be installed automatically, you have to install it from the apps menu. Indeed,
+the purpose of the staging build is to test the behavior of your changes as it would be on your
+production, and on your production you would not like your module to be installed automatically, but
+on demand.
 
-Your module may not appear directly in your apps to install either, you need to update your apps list first:
+Your module may not appear directly in your apps to install either, you need to update your apps
+list first:
 
 * Activate the :ref:`developer mode <developer-mode>`
 * in the apps menu, click the *Update Apps List* button,
 * in the dialog that appears, click the *Update* button.
 
-  .. image:: ./media/firstmodule-test-updateappslist.png
+  .. image:: first_module/firstmodule-test-updateappslist.png
     :align: center
 
 Your module will then appear in the list of available apps.
 
-.. image:: ./media/firstmodule-test-mymoduleinapps.png
+.. image:: first_module/firstmodule-test-mymoduleinapps.png
   :align: center
 
 Deploy in production
@@ -283,7 +283,7 @@ and believe it is ready for production, you can merge your branch in the product
 
 Drag and drop your staging branch on the production branch.
 
-.. image:: ./media/firstmodule-test-mergeinproduction.png
+.. image:: first_module/firstmodule-test-mergeinproduction.png
   :align: center
 
 You can also use the :code:`git merge` command to merge your branches.
@@ -291,7 +291,7 @@ You can also use the :code:`git merge` command to merge your branches.
 This will merge the latest changes of your staging branch in the production branch,
 and update your production server with these latest changes.
 
-.. image:: ./media/firstmodule-test-mergedinproduction.png
+.. image:: first_module/firstmodule-test-mergedinproduction.png
   :align: center
 
 Once the database ready, you can access it using the *Connect* button.
@@ -307,14 +307,16 @@ you have to install it manually as explained in the
 Add a change
 ============
 
-This section explains how to add a change in your module by adding a new field in a model and deploy it.
+This section explains how to add a change in your module by adding a new field in a model and deploy
+it.
 
 From the Odoo.sh editor,
  * browse to your module folder *~/src/user/my_module*,
  * then, open the file *models/models.py*.
 
 Or, from your computer,
- * use the file browser of your choice to browse to your module folder *~/src/odoo-addons/my_module*,
+ * use the file browser of your choice to browse to your module folder
+   *~/src/odoo-addons/my_module*,
  * then, open the file *models/models.py* using the editor of your choice,
    such as *Atom*, *Sublime Text*, *PyCharm*, *vim*, ...
 
@@ -350,8 +352,8 @@ and modify a view stored in database.
 In order to be applied in existing databases, such as your production database,
 these changes requires the module to be updated.
 
-If you would like the update to be performed automatically by the Odoo.sh platform when you push your changes,
-increase your module version in its manifest.
+If you would like the update to be performed automatically by the Odoo.sh platform when you push
+your changes, increase your module version in its manifest.
 
 Open the module manifest *__manifest__.py*.
 
@@ -367,7 +369,8 @@ with
 
   'version': '0.2',
 
-The platform will detect the change of version and trigger the update of the module upon the new revision deployment.
+The platform will detect the change of version and trigger the update of the module upon the new
+revision deployment.
 
 Browse to your Git folder.
 
@@ -411,13 +414,13 @@ Or, from your computer terminal:
 
 The platform will then create a new build for the branch *feature-1*.
 
-.. image:: ./media/firstmodule-test-addachange-build.png
-  :align: center
+.. image:: first_module/firstmodule-test-addachange-build.png
+   :align: center
 
-Once you tested your changes, you can merge your changes in the production branch, for instance by drag-and-dropping the
-branch on the production branch in the Odoo.sh interface. As you increased the module version in the manifest,
-the platform will update the module automatically and your new field will be directly available.
-Otherwise you can manually update the module within the apps list.
+Once you tested your changes, you can merge your changes in the production branch, for instance by
+drag-and-dropping the branch on the production branch in the Odoo.sh interface. As you increased the
+module version in the manifest, the platform will update the module automatically and your new field
+will be directly available. Otherwise you can manually update the module within the apps list.
 
 Use an external Python library
 ==============================
@@ -425,10 +428,18 @@ Use an external Python library
 If you would like to use an external Python library which is not installed by default,
 you can define a *requirements.txt* file listing the external libraries your modules depends on.
 
+.. note::
+   - It is not possible to install or upgrade system packages on an Odoo.sh database (e.g., apt
+     packages). However, under specific conditions, packages can be considered for installation.
+     This also applies to **Python modules** requiring system packages for their compilation, and
+     **third-party Odoo modules**.
+   - **PostgreSQL extensions** are not supported on Odoo.sh.
+   - For more information, consult our `FAQ <https://www.odoo.sh/faq#install_dependencies>`_.
+
 The platform will use this file to automatically install the Python libraries your project needs.
 
-The feature is explained in this section by using the `Unidecode library <https://pypi.python.org/pypi/Unidecode>`_ in
-your module.
+The feature is explained in this section by using the `Unidecode library
+<https://pypi.python.org/pypi/Unidecode>`_ in your module.
 
 Create a file *requirements.txt* in the root folder of your repository
 
@@ -442,8 +453,8 @@ Add
 
   unidecode
 
-Then use the library in your module, for instance to remove accents from characters in the name field of your
-model.
+Then use the library in your module, for instance to remove accents from characters in the name
+field of your model.
 
 Open the file *models/models.py*.
 

content-rst/administration/odoo_sh/getting_started/online-editor.rst

@@ -0,0 +1,197 @@
+
+.. _odoosh-gettingstarted-online-editor:
+
+=============
+Online Editor
+=============
+
+Overview
+========
+
+The online editor allows you to edit the source code of your builds from a web browser.
+It also gives you the possibility to open terminals, Python consoles, Odoo Shell consoles and
+`Notebooks <https://jupyterlab.readthedocs.io/en/stable/user/notebook.html>`_.
+
+.. image:: online-editor/interface-editor.png
+   :align: center
+
+You can access the editor of a build through
+:ref:`the branches tabs <odoosh-gettingstarted-branches-tabs>`,
+:ref:`the builds dropdown menu <odoosh-gettingstarted-builds-dropdown-menu>`
+or by adding */odoo-sh/editor* to your build domain name
+(e.g. *https://odoo-addons-master-1.dev.odoo.com/odoo-sh/editor*).
+
+Edit the source code
+====================
+
+The working directory is composed of the following folders:
+
+::
+
+  .
+  ├── home
+  │    └── odoo
+  │         ├── src
+  │         │    ├── odoo                Odoo Community source code
+  │         │    │    └── odoo-bin       Odoo server executable
+  │         │    ├── enterprise          Odoo Enterprise source code
+  │         │    ├── themes              Odoo Themes source code
+  │         │    └── user                Your repository branch source code
+  │         ├── data
+  │         │    ├── filestore           database attachments, as well as the files of binary fields
+  │         │    └── sessions            visitors and users sessions
+  │         └── logs
+  │              ├── install.log         Database installation logs
+  │              ├── odoo.log            Running server logs
+  │              ├── update.log          Database updates logs
+  │              └── pip.log             Python packages installation logs
+
+You can edit the source code (files under */src*) in development and staging builds.
+
+.. note::
+  Your changes won't be propagated to a new build, you must commit them in your
+  source code if you want to make them persist.
+
+
+For production builds, the source code is read-only, because applying local changes on a production
+server is not a good practice.
+
+* The source code of your Github repository is located under */src/user*,
+* The source code of Odoo is located under
+
+  * */src/odoo* (`odoo/odoo <https://github.com/odoo/odoo>`_),
+  * */src/enterprise* (`odoo/enterprise <https://github.com/odoo/enterprise>`_),
+  * */src/themes* (`odoo/design-themes <https://github.com/odoo/design-themes>`_).
+
+To open a file in the editor, just double-click on it in the file browser panel on the left.
+
+.. image:: online-editor/interface-editor-open-file.png
+   :align: center
+
+You can then begin to make your changes. You can save your changes with the menu
+:menuselection:`File --> Save .. File` or by hitting the :kbd:`Ctrl+S` shortcut.
+
+.. image:: online-editor/interface-editor-save-file.png
+   :align: center
+
+If you save a Python file which is under your Odoo server addons path,
+Odoo will detect it and reload automatically so your changes are reflected immediately,
+without having to restart the server manually.
+
+.. image:: online-editor/interface-editor-automaticreload.gif
+   :align: center
+
+However, if the change is a data stored in database, such as the label of a field, or a view,
+you have to update the according module to apply the change.
+You can update the module of the currently opened file by using the menu
+:menuselection:`Odoo --> Update current module`. Note that the file considered as currently opened
+is the file focused in the text editor, not the file highlighted in the file browser.
+
+.. image:: online-editor/interface-editor-update-current-module.png
+   :align: center
+
+You can also open a terminal and execute the command:
+
+.. code-block:: bash
+
+  $ odoo-bin -u <comma-separated module names> --stop-after-init
+
+.. _odoosh-gettingstarted-online-editor-push:
+
+Commit & Push your changes
+==========================
+
+You have the possibility to commit and push your changes to your Github repository.
+
+* Open a terminal (:menuselection:`File --> New --> Terminal`),
+* Change the directory to *~/src/user* using :code:`cd ~/src/user`,
+* Stage your changes using :code:`git add`,
+* Commit your changes using :code:`git commit`,
+* Push your changes using :code:`git push https HEAD:<branch>`.
+
+In this last command,
+
+* *https* is the name of your *HTTPS* Github remote repository
+  (e.g. https://github.com/username/repository.git),
+* HEAD is the reference to the latest revision you committed,
+* <branch> must be replaced by the name of the branch to which you want to push the changes,
+  most-likely the current branch if you work in a development build.
+
+.. image:: online-editor/interface-editor-commit-push.png
+   :align: center
+
+.. note::
+   The SSH Github remote is not used because your SSH private key
+   is not hosted in your build containers (for obvious security concerns)
+   nor forwarded through an SSH Agent (as you access this editor through a web browser)
+   and you therefore cannot authenticate yourself to Github using SSH.
+   You have to use the HTTPS remote of your Github repository to push your changes,
+   which is added automatically named as *https* in your Git remotes.
+   You will be prompted to enter your Github username and password.
+   If you activated the two-factor authentication on Github,
+   you can create a `personal access token
+   <https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/>`_
+   and use it as password. Granting the ``repo`` permission suffices.
+
+.. note::
+   The Git source folder *~/src/user* is not checked out on a branch but rather on a detached revision:
+   This is because builds work on specific revisions rather than branches.
+   In other words, this means you can have multiple builds on the same branch, but on different revisions.
+
+Once your changes are pushed,
+according to your :ref:`branch push behavior <odoosh-gettingstarted-branches-tabs-settings>`,
+a new build may be created. You can continue to work in the editor you pushed from,
+as it will have the same revision as the new build that was created, but always make sure to be
+in an editor of a build using the latest revision of your branch.
+
+Consoles
+========
+
+You can open Python consoles, which are
+`IPython interactive shells <https://ipython.readthedocs.io/en/stable/interactive/tutorial.html>`_.
+One of the most interesting addition to use a Python console
+rather than a IPython shell within a terminal is the
+`rich display <https://ipython.readthedocs.io/en/stable/config/integrating.html#rich-display>`_
+capabilities.
+Thanks to this, you will be able to display objects in HTML.
+
+You can for instance display cells of a CSV file using
+`pandas <https://pandas.pydata.org/pandas-docs/stable/tutorials.html>`_.
+
+.. image:: online-editor/interface-editor-console-python-read-csv.png
+   :align: center
+
+You can also open an Odoo Shell console to play around
+with the Odoo registry and model methods of your database. You can also directly read or write
+on your records.
+
+.. warning::
+   In an Odoo Console, transactions are automatically committed.
+   This means, for instance, that changes in records are applied effectively in the database.
+   If you change the name of a user, the name of the user is changed in your database as well.
+   You therefore should use Odoo consoles carefully on production databases.
+
+You can use *env* to invoke models of your database registry, e.g. :code:`env['res.users']`.
+
+.. code-block:: python
+
+  env['res.users'].search_read([], ['name', 'email', 'login'])
+  [{'id': 2,
+  'login': 'admin',
+  'name': 'Administrator',
+  'email': 'admin@example.com'}]
+
+The class :code:`Pretty` gives you the possibility
+to easily display lists and dicts in a pretty way, using the
+`rich display <https://ipython.readthedocs.io/en/stable/config/integrating.html#rich-display>`_
+mentioned above.
+
+.. image:: online-editor/interface-editor-console-odoo-pretty.png
+   :align: center
+
+You can also use
+`pandas <https://pandas.pydata.org/pandas-docs/stable/tutorials.html>`_
+to display graphs.
+
+.. image:: online-editor/interface-editor-console-odoo-graph.png
+   :align: center

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