[IMP] db: online editor update

closes odoo/documentation#15843

X-original-commit: cff5d61373
Signed-off-by: Audrey Vandromme (auva) <auva@odoo.com>
Signed-off-by: Xavier Platteau (xpl) <xpl@odoo.com>

content/administration/odoo_sh/first_module.rst

@@ -172,11 +172,8 @@ From an Odoo.sh editor terminal:
 
   $ git push https HEAD:feature-1
 
-The above command is explained in the section
-:ref:`Commit & Push your changes
-<odoosh-gettingstarted-online-editor-push>` of the
-:ref:`Online Editor <odoosh-gettingstarted-online-editor>`
-chapter.
+The above command is explained in the section :ref:`Commit and push changes
+<odoo-sh/editor/commit>` of the :doc:`Online editor page <getting_started/online_editor>`.
 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.
 

content/administration/odoo_sh/getting_started.rst

@@ -53,6 +53,5 @@ Odoo.sh involves different types of users, each with a specific role in the proj
    getting_started/create
    getting_started/branches
    getting_started/builds
-   getting_started/status
    getting_started/settings
-   getting_started/online-editor
+   getting_started/online_editor

content/administration/odoo_sh/getting_started/branches.rst

@@ -289,7 +289,7 @@ shell consoles.
 You can open multiple tabs and drag and drop them to arrange the layout as you wish.
 
 .. seealso::
-   :doc:`Online editor documentation <online-editor>`.
+   :doc:`Online editor documentation <online_editor>`.
 
 .. _odoo-sh/branches/tabs/monitor:
 

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

@@ -1,197 +0,0 @@
-
-.. _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 <odoo-sh/branches/tabs>`,
-:ref:`the builds dropdown menu <odoo-sh/builds/stages/features>`
-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 <odoo-sh/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/administration/odoo_sh/getting_started/online_editor.rst

@@ -0,0 +1,200 @@
+=============
+Online editor
+=============
+
+The :guilabel:`Online Editor` view allows editing 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
+`Jupyter Notebooks <https://jupyterlab.readthedocs.io/en/stable/user/notebook.html>`_.
+
+.. image:: online_editor/online-editor.png
+   :alt: Overview of the online editor
+
+You can access the editor of a build through :ref:`the branches tab <odoo-sh/branches/tabs>`,
+:ref:`the builds dropdown menu <odoo-sh/builds/stages/features>`, or by adding `/odoo-sh/editor` to
+the build's URL (e.g., `https://odoo-addons-master-1.dev.odoo.com/odoo-sh/editor`).
+
+.. _odoo-sh/editor/source:
+
+Editing the source code
+=======================
+
+The working directory is composed of the following:
+
+::
+
+  .
+  ├── 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`) of development and staging builds. For production
+builds, the source code is read-only, because applying local changes on a production server is not a
+good practice.
+
+.. note::
+   - Your changes won't be propagated to new builds. It is necessary to :ref:`commit them to the
+     source code <odoo-sh/editor/commit>` if you want them to persist.
+   - The source code of your GitHub repository is located under `/src/user`.
+   - The source code of Odoo is located under:
+
+     - `/src/odoo` (`<https://github.com/odoo/odoo>`_)
+     - `/src/enterprise` (`<https://github.com/odoo/enterprise>`_)
+     - `/src/themes` (`<https://github.com/odoo/design-themes>`_)
+
+To open a file in the editor, double-click it in the file browser panel. You can then edit the file.
+To save your changes, go to :menuselection:`File --> Save` or use the :kbd:`Ctrl+S` keyboard
+shortcut.
+
+If you save a Python file in your Odoo server's addons path, Odoo will detect it and reload
+automatically, meaning your changes are immediately visible.
+
+.. image:: online_editor/auto-reload.gif
+   :alt: Change to a Python file being immediately visible
+
+However, if your changes are stored in the database, such as a field's label or a view, it is
+necessary to update the related module to apply the changes. To update the module of the currently1
+open file, go to :menuselection:`Odoo --> Update current module`.
+
+.. image:: online_editor/update-module.png
+   :alt: Using the editor to update the current module
+
+.. tip::
+   You can also execute the following command in a terminal to update a module:
+
+   .. code-block:: bash
+
+      odoo-bin -u <comma-separated module names> --stop-after-init
+
+.. _odoo-sh/editor/commit:
+
+Committing and pushing changes
+==============================
+
+To commit and push changes to your GitHub repository:
+
+- Open a terminal by going to :menuselection:`File --> New --> Terminal`.
+- Change the directory to `~/src/user`.
+
+  .. code-block:: bash
+
+     cd ~/src/user
+
+- State your identity.
+
+  .. code-block:: bash
+
+     git config --global user.email "you@example.com" && git config --global user.name "Your Name"
+
+- Stage your changes.
+
+  .. code-block:: bash
+
+     git add
+
+- Commit your changes.
+
+  .. code-block:: bash
+
+     git commit
+
+- Push your changes.
+
+  .. code-block:: bash
+
+     git push https HEAD:<branch>
+
+  In this 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 on a development build.
+
+You will be prompted to input your GitHub username and password. After inputting your credentials,
+press enter.
+
+.. image:: online_editor/commit-push.png
+   :alt: The commands to commit and push changes
+
+.. tip::
+   If you activate two-factor authentication for your GitHub account, you can create a `personal
+   access token <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token>`_
+   and use it as a password. `Granting the repo permission <https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/repository-access-and-collaboration/inviting-collaborators-to-a-personal-repository>`_
+   suffices.
+
+.. note::
+   - It is not possible to authenticate yourself using SSH, as your private SSH key is not hosted in
+     your build containers for security reasons, nor forwarded through an SSH agent, as you access
+     the editor through a web browser.
+   - The 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, meaning 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
+<odoo-sh/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. However,
+always make sure to be in the editor of a build using the latest revision of your branch.
+
+.. _odoo-sh/editor/consoles:
+
+Consoles
+========
+
+You can open Python consoles, which are `IPython interactive shells
+<https://ipython.readthedocs.io/en/stable/interactive/tutorial.html>`_. Using these Python consoles
+(rather than IPython shells within a terminal) allows you to utilize their `rich display
+capabilities <https://ipython.readthedocs.io/en/stable/config/integrating.html#rich-display>`_ to
+display objects in HTML.
+
+.. example::
+   The :code:`Pretty` class displays lists in a legible way.
+
+   .. image:: online_editor/pretty-class.png
+      :alt: Pretty class example
+
+.. tip::
+   Using `pandas <https://pandas.pydata.org/pandas-docs/stable/getting_started/tutorials.html>`_ you
+   can display:
+
+   - Cells of a CSV file
+
+     .. image:: online_editor/pandas-csv.png
+        :alt: pandas CSV example
+
+   - Graphs
+
+     .. image:: online_editor/pandas-graph.png
+        :alt: pandas graph example
+
+You can open Odoo shell consoles to experiment with the Odoo registry and model methods of your
+database. You can also read or write directly on your records.
+
+.. warning::
+   In an Odoo shell console, transactions are automatically committed. This means that changes made
+   to records are applied to the database. For example, if you change a user's name, it will be
+   updated in your database as well. Therefore, use Odoo shell 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'}]

content/administration/odoo_sh/getting_started/status.rst

@@ -1,12 +0,0 @@
-======
-Status
-======
-
-Overview
-========
-
-The status page shows statistics regarding the servers your project uses. It includes the servers
-availability.
-
-.. image:: status/interface-status.png
-   :align: center

redirects/17.0.txt

@@ -5,6 +5,8 @@ administration/supported_versions.rst administration/standard_extended_support.r
 # administration/odoo_sh
 
 administration/odoo_sh/getting_started/first_module.rst administration/odoo_sh/first_module.rst
+administration/odoo_sh/getting_started/online-editor.rst administration/odoo_sh/getting_started/online_editor.rst
+administration/odoo_sh/getting_started/status.rst administration/odoo_sh/getting_started.rst
 administration/odoo_sh/overview/introduction.rst administration/odoo_sh.rst
 
 # developer/reference