[ADD] oe: provides sane (unfucked) command-line interface.

The implementation is far from perfect. Some improvements are waiting in
its previous location: lp:~openerp/openerp-command.

Some docs are provided, see doc/openerp-command.rst and
doc/adding-command.rst.

bzr revid: vmt@openerp.com-20130111134657-im2f3uqjluyo4pm6

3 files changed, 103 insertions, 0 deletions

diff --git a/doc/adding-command.rst b/doc/adding-command.rst
new file mode 100644
index 00000000000..5a177b06817
--- /dev/null
+++ b/doc/adding-command.rst
@@ -0,0 +1,34 @@
+.. _adding-command:
+
+Adding a new command
+====================
+
+``oe`` uses the argparse_ library to implement commands. Each
+command lives in its own ``openerpcommand/<command>.py`` file.
+
+.. _argparse: http://docs.python.org/2.7/library/argparse.html
+
+To create a new command, probably the most simple way to get started is to
+copy/paste an existing command, say ``openerpcommand/initialize.py`` to
+``openerpcommand/foo.py``. In the newly created file, the important bits
+are the ``run(args)`` and ``add_parser(subparsers)`` functions.
+
+``add_parser``'s responsability is to create a (sub-)parser for the command,
+i.e. describe the different options and flags. The last thing it does is to set
+``run`` as the function to call when the command is invoked.
+
+.. code-block:: python
+
+  > def add_parser(subparsers):
+  >     parser = subparsers.add_parser('<command-name>',
+  >         description='...')
+  >     parser.add_argument(...)
+  >     ...
+  >     parser.set_defaults(run=run)
+
+``run(args)`` actually implements the command. It should be kept as simple as
+possible and delegate most of its work to small functions (probably placed at
+the top of the new file). In other words, its responsability is mainly to
+deal with the presence/absence/pre-processing of ``argparse``'s arguments.
+
+Finally, the module must be added to ``openerpcommand/__init__.py``.
diff --git a/doc/index.rst b/doc/index.rst
index 50a37695206..64fc04b552e 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -18,6 +18,15 @@ OpenERP Server
    06_misc
    09_deployment
 
+OpenERP Command
+'''''''''''''''
+
+.. toctree::
+   :maxdepth: 1
+
+   openerp-command.rst
+   adding-command.rst
+
 OpenERP Server API
 ''''''''''''''''''
 
diff --git a/doc/openerp-command.rst b/doc/openerp-command.rst
new file mode 100644
index 00000000000..2bfd845f8e3
--- /dev/null
+++ b/doc/openerp-command.rst
@@ -0,0 +1,60 @@
+.. _openerp-command:
+
+OpenERP Command
+===============
+
+The ``oe`` script provides a set of command-line tools around the OpenERP
+framework.
+
+Using OpenERP Command
+---------------------
+
+In contrast to the previous ``openerp-server`` script, ``oe`` defines a few
+sub-commands, each with its own set of flags and options. You can get some
+information for any of them with
+
+::
+
+  > oe <sub-command> --help
+
+For instance::
+
+  > oe run-tests --help
+
+Some ``oe`` options can be provided via environment variables. For instance::
+
+  > export OPENERP_DATABASE=trunk
+  > export OPENERP_HOST=127.0.0.1
+  > export OPENERP_PORT=8069
+
+Depending on your needs, you can group all of the above in one single script;
+for instance here is a, say, ``test-trunk-view-validation.sh`` file::
+
+  COMMAND_REPO=/home/thu/repos/command/trunk/
+  SERVER_REPO=/home/thu/repos/server/trunk
+
+  export PYTHONPATH=$SERVER_REPO:$COMMAND_REPO
+  export PATH=$SERVER_REPO:$COMMAND_REPO:$PATH
+  export OPENERP_DATABASE=trunk
+  export OPENERP_HOST=127.0.0.1
+  export OPENERP_PORT=8069
+
+  # The -d ignored is actually needed by `oe` even though `test_view_validation`
+  # itself does not need it.
+  oe run-tests -d ignored -m openerp.test_view_validation
+
+Adding new commands
+-------------------
+
+See the :doc:`adding-command` page.
+
+Bash completion
+---------------
+
+A preliminary ``oe-bash-completion`` file is provided. After sourcing it,
+
+::
+
+  > . oe-bash-completion
+
+completion (using the TAB character) in Bash should be working.