[IMP] db: online editor update

Author: xpl-odoo

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/online-editor.rst

@@ -1,30 +1,24 @@
-
-.. _odoosh-gettingstarted-online-editor:
-
 =============
-Online Editor
+Online editor
 =============
 
-Overview
-========
+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>`_.
 
-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/online-editor.png
+   :alt: Overview of the online editor
 
-.. image:: online-editor/interface-editor.png
-   :align: center
+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`).
 
-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*).
+.. _odoo-sh/editor/source:
 
-Edit the source code
-====================
+Editing the source code
+=======================
 
-The working directory is composed of the following folders:
+The working directory is composed of the following:
 
 ::
 
@@ -38,160 +32,169 @@ The working directory is composed of the following folders:
   │         │    ├── 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
+  │         │    ├── 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.
+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 a new build, you must commit them in your
-  source code if you want to make them persist.
+   - 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>`_)
 
-For production builds, the source code is read-only, because applying local changes on a production
-server is not a good practice.
+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.
 
-* The source code of your Github repository is located under */src/user*,
-* The source code of Odoo is located under
+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.
 
-  * */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>`_).
+.. image:: online-editor/auto-reload.gif
+   :alt: Change to a Python file being immediately visible
 
-To open a file in the editor, just double-click on it in the file browser panel on the left.
+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/interface-editor-open-file.png
-   :align: center
+.. image:: online-editor/update-module.png
+   :alt: Using the editor to update the current module
 
-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.
+.. tip::
+   You can also execute the following command in a terminal to update a module:
 
-.. image:: online-editor/interface-editor-save-file.png
-   :align: center
+   .. code-block:: bash
 
-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.
+      odoo-bin -u <comma-separated module names> --stop-after-init
 
-.. image:: online-editor/interface-editor-automaticreload.gif
-   :align: center
+.. _odoo-sh/editor/commit:
 
-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.
+Committing and pushing changes
+==============================
 
-.. image:: online-editor/interface-editor-update-current-module.png
-   :align: center
+To commit and push changes to your GitHub repository:
 
-You can also open a terminal and execute the command:
+- Open a terminal by going to :menuselection:`File --> New --> Terminal`.
+- Change the directory to `~/src/user`.
 
-.. code-block:: bash
+  .. code-block:: bash
 
-  $ odoo-bin -u <comma-separated module names> --stop-after-init
+     cd ~/src/user
 
-.. _odoosh-gettingstarted-online-editor-push:
+- State your identity.
 
-Commit & Push your changes
-==========================
+  .. code-block:: bash
 
-You have the possibility to commit and push your changes to your Github repository.
+     git config --global user.email "[email protected]" && git config --global user.name "Your Name"
 
-* 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>`.
+- Stage your changes.
 
-In this last command,
+  .. code-block:: bash
 
-* *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.
+     git add
 
-.. image:: online-editor/interface-editor-commit-push.png
-   :align: center
+- Commit your changes.
 
-.. 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.
+  .. 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::
-   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.
+   - 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, but always make sure to be
-in an editor of a build using the latest revision of your branch.
+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>`_.
-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 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.
 
-You can for instance display cells of a CSV file using
-`pandas <https://pandas.pydata.org/pandas-docs/stable/tutorials.html>`_.
+.. example::
+   The :code:`Pretty` class displays lists in a legible way.
 
-.. image:: online-editor/interface-editor-console-python-read-csv.png
-   :align: center
+   .. image:: online-editor/pretty-class.png
+      :alt: Pretty class example
 
-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.
+.. tip::
+   Using `pandas <https://pandas.pydata.org/pandas-docs/stable/getting_started/tutorials.html>`_ you
+   can display:
 
-.. 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.
+   - Cells of a CSV file
 
-You can use *env* to invoke models of your database registry, e.g. :code:`env['res.users']`.
+     .. image:: online-editor/pandas-csv.png
+        :alt: pandas CSV example
 
-.. code-block:: python
+   - Graphs
+
+     .. image:: online-editor/pandas-graph.png
+        :alt: pandas graph example
 
-  env['res.users'].search_read([], ['name', 'email', 'login'])
-  [{'id': 2,
-  'login': 'admin',
-  'name': 'Administrator',
-  'email': '[email protected]'}]
+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.
 
-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.
+.. 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.
 
-.. image:: online-editor/interface-editor-console-odoo-pretty.png
-   :align: center
+You can use `env` to invoke models of your database registry, e.g., :code:`env['res.users']`.
 
-You can also use
-`pandas <https://pandas.pydata.org/pandas-docs/stable/tutorials.html>`_
-to display graphs.
+.. code-block:: python
 
-.. image:: online-editor/interface-editor-console-odoo-graph.png
-   :align: center
+   env['res.users'].search_read([], ['name', 'email', 'login'])
+   [{'id': 2,
+   'login': 'admin',
+   'name': 'Administrator',
+   'email': '[email protected]'}]