[MERGE] forward port branch saas-12.4 up to 9ed4872ea03

closes odoo/odoo#37372

Signed-off-by: Christophe Simonis <chs@odoo.com>

1 files changed, 192 insertions, 141 deletions

diff --git a/doc/reference/cmdline.rst b/doc/reference/cmdline.rst
index 8ab38abdc51..5652571f9be 100644
--- a/doc/reference/cmdline.rst
+++ b/doc/reference/cmdline.rst
@@ -19,6 +19,8 @@ Running the server
     Providing a comma-separated list restrict access to databases provided in
     list.
 
+    For advanced database options, take a look :ref:`below <reference/cmdline/server/database>`.
+
 .. option:: -i <modules>, --init <modules>
 
     comma-separated list of modules to install before running the server
@@ -32,82 +34,24 @@ Running the server
 .. option:: --addons-path <directories>
 
     comma-separated list of directories in which modules are stored. These
-    directories are scanned for modules (nb: when and why?)
-
-.. option:: --workers <count>
-
-    if ``count`` is not 0 (the default), enables multiprocessing and sets up
-    the specified number of HTTP workers (sub-processes processing HTTP
-    and RPC requests).
-
-    .. note:: multiprocessing mode is only available on Unix-based systems
-
-    A number of options allow limiting and recycling workers:
-
-    .. option:: --limit-request <limit>
-
-        Number of requests a worker will process before being recycled and
-        restarted.
-
-        Defaults to 8196.
-
-    .. option:: --limit-memory-soft <limit>
-
-        Maximum allowed virtual memory per worker. If the limit is exceeded,
-        the worker is killed and recycled at the end of the current request.
-
-        Defaults to 2048MiB.
-
-    .. option:: --limit-memory-hard <limit>
-
-        Hard limit on virtual memory, any worker exceeding the limit will be
-        immediately killed without waiting for the end of the current request
-        processing.
+    directories are scanned for modules.
 
-        Defaults to 2560MiB.
-
-    .. option:: --limit-time-cpu <limit>
-
-        Prevents the worker from using more than <limit> CPU seconds for each
-        request. If the limit is exceeded, the worker is killed.
-
-        Defaults to 60.
-
-    .. option:: --limit-time-real <limit>
-
-        Prevents the worker from taking longer than <limit> seconds to process
-        a request. If the limit is exceeded, the worker is killed.
-
-        Differs from :option:`--limit-time-cpu` in that this is a "wall time"
-        limit including e.g. SQL queries.
-
-        Defaults to 120.
-
-.. option:: --max-cron-threads <count>
-
-    number of workers dedicated to cron jobs. Defaults to 2. The workers are
-    threads in multi-threading mode and processes in multi-processing mode.
-
-    For multi-processing mode, this is in addition to the HTTP worker
-    processes.
+    .. (nb: when and why?)
 
 .. option:: -c <config>, --config <config>
 
-    provide an alternate configuration file
+    provide an alternate :ref:`configuration file <reference/cmdline/config>`
 
 .. option:: -s, --save
 
     saves the server configuration to the current configuration file
     (:file:`{$HOME}/.odoorc` by default, and can be overridden using
-    :option:`-c`)
+    :option:`-c`).
 
-.. option:: --proxy-mode
-
-    enables the use of ``X-Forwarded-*`` headers through `Werkzeug's proxy
-    support`_.
+.. option:: --without-demo
 
-    .. warning:: proxy mode *must not* be enabled outside of a reverse proxy
-                 scenario
+    disables demo data loading for modules installed
+    comma-separated, use ``all`` for all modules.
 
 .. option:: --test-enable
 
@@ -131,25 +75,9 @@ Running the server
     ``1``, ``t`` or ``true`` can be used to use the same directory as the above
     mentioned ``--screenshots`` option.
 
-.. option:: --dev <feature,feature,...,feature>
-
-    * ``all``: all the features below are activated
-
-    * ``xml``: read template qweb from xml file directly instead of database.
-      Once a template has been modified in database, it will be not be read from
-      the xml file until the next update/init.
-
-    * ``reload``: restart server when python file are updated (may not be detected
-      depending on the text editor used)
-
-    * ``qweb``: break in the evaluation of qweb template when a node contains ``t-debug='debugger'``
-
-    * ``(i)p(u)db``: start the chosen python debugger in the code when an
-      unexpected error is raised before logging and returning the error.
-
 .. _reference/cmdline/server/database:
 
-database
+Database
 --------
 
 .. option:: -r <user>, --db_user <user>
@@ -189,40 +117,40 @@ database
     listen by using the --database parameter and specifying a comma-separated
     list of databases
 
-    When combining the two parameters, db-filter superseed the comma-separated
+    When combining the two parameters, db-filter supersedes the comma-separated
     database list for restricting database list, while the comma-separated list
     is used for performing requested operations like upgrade of modules.
-    
+
     .. code-block:: bash
 
-        odoo-bin --db-filter ^11.*$
+        $ odoo-bin --db-filter ^11.*$
 
     Restrict access to databases whose name starts with 11
 
     .. code-block:: bash
 
-        odoo-bin --database 11firstdatabase,11seconddatabase
+        $ odoo-bin --database 11firstdatabase,11seconddatabase
 
     Restrict access to only two databases, 11firstdatabase and 11seconddatabase
-    
+
     .. code-block:: bash
 
-        odoo-bin --database 11firstdatabase,11seconddatabase -u base
+        $ odoo-bin --database 11firstdatabase,11seconddatabase -u base
 
     Restrict access to only two databases, 11firstdatabase and 11seconddatabase,
-    and update base module on one database: 11firstdatabase
+    and update base module on one database: 11firstdatabase.
     If database 11seconddatabase doesn't exist, the database is created and base modules
     is installed
-    
+
     .. code-block:: bash
 
-        odoo-bin --db-filter ^11.*$ --database 11firstdatabase,11seconddatabase -u base
-        
+        $ odoo-bin --db-filter ^11.*$ --database 11firstdatabase,11seconddatabase -u base
+
     Restrict access to databases whose name starts with 11,
-    and update base module on one database: 11firstdatabase
+    and update base module on one database: 11firstdatabase.
     If database 11seconddatabase doesn't exist, the database is created and base modules
     is installed
-    
+
 .. option:: --db-template <template>
 
     when creating new databases from the database-management screens, use the
@@ -237,7 +165,7 @@ database
 .. option:: --no-database-list
 
     Suppresses the ability to list databases available on the system
-    
+
 .. option:: --db_sslmode
 
     Control the SSL security of the connection between Odoo and PostgreSQL.
@@ -245,6 +173,33 @@ database
     'verify-ca' or 'verify-full'
     Default value is 'prefer'
 
+.. _reference/cmdline/server/emails:
+
+Emails
+------
+
+.. option:: --email-from <address>
+
+    Email address used as <FROM> when Odoo needs to send mails
+
+.. option:: --smtp <server>
+
+    Address of the SMTP server to connect to in order to send mails
+
+.. option:: --smtp-port <port>
+
+.. option:: --smtp-ssl
+
+    If set, odoo should use SSL/STARTSSL SMTP connections
+
+.. option:: --smtp-user <name>
+
+    Username to connect to the SMTP server
+
+.. option:: --smtp-password <password>
+
+    Password to connect to the SMTP server
+
 .. _reference/cmdline/server/internationalisation:
 
 Internationalisation
@@ -283,13 +238,41 @@ of importation
 
     specify modules to export. Use in combination with --i18n-export
 
+.. _reference/cmdline/advanced:
+
+Advanced Options
+----------------
+
+.. _reference/cmdline/dev:
 
-built-in HTTP
--------------
+Developer features
+''''''''''''''''''
+
+.. option:: --dev <feature,feature,...,feature>
+
+    * ``all``: all the features below are activated
+
+    * ``xml``: read template qweb from xml file directly instead of database.
+      Once a template has been modified in database, it will be not be read from
+      the xml file until the next update/init.
+
+    * ``reload``: restart server when python file are updated (may not be detected
+      depending on the text editor used)
+
+    * ``qweb``: break in the evaluation of qweb template when a node contains ``t-debug='debugger'``
+
+    * ``(i)p(u)db``: start the chosen python debugger in the code when an
+      unexpected error is raised before logging and returning the error.
+
+
+.. _reference/cmdline/server/http:
+
+HTTP
+''''
 
 .. option:: --no-http
 
-    do not start the HTTP or long-polling workers (may still start cron
+    do not start the HTTP or long-polling workers (may still start :ref:`cron <reference/actions/cron>`
     workers)
 
     .. warning:: has no effect if :option:`--test-enable` is set, as tests
@@ -309,25 +292,35 @@ built-in HTTP
     TCP port for long-polling connections in multiprocessing or gevent mode,
     defaults to 8072. Not used in default (threaded) mode.
 
-logging
--------
+.. option:: --proxy-mode
+
+    enables the use of ``X-Forwarded-*`` headers through `Werkzeug's proxy
+    support`_.
+
+    .. warning:: proxy mode *must not* be enabled outside of a reverse proxy
+                 scenario
+
+.. _reference/cmdline/server/logging:
+
+Logging
+'''''''
 
 By default, Odoo displays all logging of level_ ``info`` except for workflow
 logging (``warning`` only), and log output is sent to ``stdout``. Various
 options are available to redirect logging to other destinations and to
-customize the amount of logging output
+customize the amount of logging output.
 
 .. option:: --logfile <file>
 
     sends logging output to the specified file instead of stdout. On Unix, the
     file `can be managed by external log rotation programs
-    <https://docs.python.org/2/library/logging.handlers.html#watchedfilehandler>`_
+    <https://docs.python.org/3/library/logging.handlers.html#watchedfilehandler>`_
     and will automatically be reopened when replaced
 
 .. option:: --syslog
 
-    logs to the system's event logger: `syslog on unices <https://docs.python.org/2/library/logging.handlers.html#sysloghandler>`_
-    and `the Event Log on Windows <https://docs.python.org/2/library/logging.handlers.html#nteventloghandler>`_.
+    logs to the system's event logger: `syslog on unices <https://docs.python.org/3/library/logging.handlers.html#sysloghandler>`_
+    and `the Event Log on Windows <https://docs.python.org/3/library/logging.handlers.html#nteventloghandler>`_.
 
     Neither is configurable
 
@@ -335,7 +328,7 @@ customize the amount of logging output
 
     logs to the ``ir.logging`` model (``ir_logging`` table) of the specified
     database. The database can be the name of a database in the "current"
-    PostgreSQL, or `a PostgreSQL URI`_ for e.g. log aggregation
+    PostgreSQL, or `a PostgreSQL URI`_ for e.g. log aggregation.
 
 .. option:: --log-handler <handler-spec>
 
@@ -402,60 +395,66 @@ customize the amount of logging output
         In case of conflict between :option:`--log-level` and
         :option:`--log-handler`, the latter is used
 
-emails
-------
+.. _reference/cdmline/workers:
 
-.. option:: --email-from <address>
+Multiprocessing
+'''''''''''''''
 
-    Email address used as <FROM> when Odoo needs to send mails
+.. option:: --workers <count>
 
-.. option:: --smtp <server>
+    if ``count`` is not 0 (the default), enables multiprocessing and sets up
+    the specified number of HTTP workers (sub-processes processing HTTP
+    and RPC requests).
 
-    Address of the SMTP server to connect to in order to send mails
+    .. note:: multiprocessing mode is only available on Unix-based systems
 
-.. option:: --smtp-port <port>
+    A number of options allow limiting and recycling workers:
 
-.. option:: --smtp-ssl
+    .. option:: --limit-request <limit>
 
-    If set, odoo should use SSL/STARTSSL SMTP connections
+        Number of requests a worker will process before being recycled and
+        restarted.
 
-.. option:: --smtp-user <name>
+        Defaults to *8196*.
 
-    Username to connect to the SMTP server
+    .. option:: --limit-memory-soft <limit>
 
-.. option:: --smtp-password <password>
+        Maximum allowed virtual memory per worker. If the limit is exceeded,
+        the worker is killed and recycled at the end of the current request.
 
-    Password to connect to the SMTP server
+        Defaults to *2048MiB*.
 
+    .. option:: --limit-memory-hard <limit>
 
-.. _reference/cmdline/scaffold:
+        Hard limit on virtual memory, any worker exceeding the limit will be
+        immediately killed without waiting for the end of the current request
+        processing.
 
-Scaffolding
-===========
+        Defaults to *2560MiB*.
 
-.. program:: odoo-bin scaffold
+    .. option:: --limit-time-cpu <limit>
 
-Scaffolding is the automated creation of a skeleton structure to simplify
-bootstrapping (of new modules, in the case of Odoo). While not necessary it
-avoids the tedium of setting up basic structures and looking up what all
-starting requirements are.
+        Prevents the worker from using more than <limit> CPU seconds for each
+        request. If the limit is exceeded, the worker is killed.
 
-Scaffolding is available via the :command:`odoo-bin scaffold` subcommand.
+        Defaults to *60*.
 
-.. option:: -t <template>
+    .. option:: --limit-time-real <limit>
 
-    a template directory, files are passed through jinja2_ then copied to
-    the ``destination`` directory
+        Prevents the worker from taking longer than <limit> seconds to process
+        a request. If the limit is exceeded, the worker is killed.
 
-.. option:: name
+        Differs from :option:`--limit-time-cpu` in that this is a "wall time"
+        limit including e.g. SQL queries.
 
-    the name of the module to create, may munged in various manners to
-    generate programmatic names (e.g. module directory name, model names, …)
+        Defaults to *120*.
 
-.. option:: destination
+.. option:: --max-cron-threads <count>
 
-    directory in which to create the new module, defaults to the current
-    directory
+    number of workers dedicated to :ref:`cron <reference/actions/cron>` jobs. Defaults to *2*.
+    The workers are threads in multi-threading mode and processes in multi-processing mode.
+
+    For multi-processing mode, this is in addition to the HTTP worker processes.
 
 .. _reference/cmdline/config:
 
@@ -487,15 +486,67 @@ can be overridden using :option:`--config <odoo-bin -c>`. Specifying
 to that file.
 
 .. _jinja2: http://jinja.pocoo.org
-.. _regular expression: https://docs.python.org/2/library/re.html
+.. _regular expression: https://docs.python.org/3/library/re.html
 .. _password authentication:
-    http://www.postgresql.org/docs/9.3/static/auth-methods.html#AUTH-PASSWORD
+    https://www.postgresql.org/docs/9.3/static/auth-methods.html#AUTH-PASSWORD
 .. _template database:
-    http://www.postgresql.org/docs/9.3/static/manage-ag-templatedbs.html
+    https://www.postgresql.org/docs/9.3/static/manage-ag-templatedbs.html
 .. _level:
-    https://docs.python.org/2/library/logging.html#logging.Logger.setLevel
+    https://docs.python.org/3/library/logging.html#logging.Logger.setLevel
 .. _a PostgreSQL URI:
-    http://www.postgresql.org/docs/9.2/static/libpq-connect.html#AEN38208
+    https://www.postgresql.org/docs/9.2/static/libpq-connect.html#AEN38208
 .. _Werkzeug's proxy support:
     http://werkzeug.pocoo.org/docs/contrib/fixers/#werkzeug.contrib.fixers.ProxyFix
 .. _pyinotify: https://github.com/seb-m/pyinotify/wiki
+
+
+Shell
+=====
+
+Odoo command-line also allows to launch odoo as a python console environment.
+This enables direct interaction with the :ref:`orm <reference/orm>` and its functionalities.
+
+
+.. code-block:: console
+
+   $ odoo_bin shell
+
+.. option:: --shell-interface (ipython|ptpython|bpython|python)
+
+    Specify a preferred REPL to use in shell mode.
+
+
+.. _reference/cmdline/scaffold:
+
+Scaffolding
+===========
+
+.. program:: odoo-bin scaffold
+
+Scaffolding is the automated creation of a skeleton structure to simplify
+bootstrapping (of new modules, in the case of Odoo). While not necessary it
+avoids the tedium of setting up basic structures and looking up what all
+starting requirements are.
+
+Scaffolding is available via the :command:`odoo-bin scaffold` subcommand.
+
+.. option:: name (required)
+
+    the name of the module to create, may munged in various manners to
+    generate programmatic names (e.g. module directory name, model names, …)
+
+.. option:: destination (default=current directory)
+
+    directory in which to create the new module, defaults to the current
+    directory
+
+.. option:: -t <template>
+
+    a template directory, files are passed through jinja2_ then copied to
+    the ``destination`` directory
+
+.. code-block:: console
+
+    $ odoo_bin scaffold my_module /addons/
+
+This will create module *my_module* in directory */addons/*.
\ No newline at end of file