[IMP] doc: grammar and readability
Backport of most of #6827 by J Bradshaw with additional modifications (and some reverts) during review. closes #6827
This commit is contained in:
J Bradshaw
Xavier Morel
parent
95e56a109d
commit
2f7ab001e2
|
|
@ -1,77 +0,0 @@
|
|||
:orphan:
|
||||
|
||||
==================
|
||||
Odoo Documentation
|
||||
==================
|
||||
|
||||
Odoo Theme
|
||||
==========
|
||||
|
||||
The Odoo Documentation theme is a bootstrap-based mix of http://odoo.com and
|
||||
http://getbootstrap.com with additional changes and additions, bundled as
|
||||
a Sphinx theme.
|
||||
|
||||
The main style file is ``_themes/odoodoc/static/style.less``, it is not
|
||||
converted on the fly and must be compiled manually when altere, using the
|
||||
official node-based lessc_ tool.
|
||||
|
||||
``odoodoc`` must be added as an extension to a project using the theme, it
|
||||
fixes some discrepancies between bootstrap_ and Sphinx_ and adds a few
|
||||
features:
|
||||
|
||||
Sphinx Customizations
|
||||
---------------------
|
||||
|
||||
* toctree bullet lists (HTML ``<ul>``) are given the ``nav`` class
|
||||
* the main navigation bar also gets the ``navbar-nav`` and ``navbar-right``
|
||||
set on its root (``navbar-right`` could probably be handled in CSS to avoid
|
||||
having it in the markup)
|
||||
* tables are given the ``table`` class
|
||||
* colspecs are removed from tables, tables should autolayout
|
||||
* ``data-`` attributes are copied straight from the docutils node to the
|
||||
output HTML node
|
||||
* an ``odoo`` pygments style based on the bootstrap_ documentation's
|
||||
* the normal Sphinx sidebars are suppressed and a new sidebar is injected in
|
||||
``div.document`` (``sidebar1`` is outside in the base Sphinx layout)
|
||||
* HTML5 doctype
|
||||
|
||||
Additional features
|
||||
-------------------
|
||||
|
||||
* versions switcher, uses the ``canonical_root`` setting and an additional
|
||||
``versions`` setting which should be a comma-separated list of available
|
||||
versions. Appends the each version and page name to the root, and displays
|
||||
a list of those links on the current page
|
||||
* canonical urls, requires a ``canonical_root`` setting value, and optionally
|
||||
a ``canonical_branch`` (default: ``master``)
|
||||
* :guilabel:`Edit on github` link in Sphinx pages if ``github_user`` and
|
||||
``github_project`` are provided
|
||||
* :guilabel:`[source]` links in autodoc content links to github with the same
|
||||
requirements (requires Sphinx 1.2)
|
||||
* ``aphorism`` class for admonitions, makes the first line of the admonition
|
||||
inline and the same size as the admonition category (mostly for short,
|
||||
single-phrase admonitions)
|
||||
* ``exercise`` directive, mostly for training-type documents, the
|
||||
``solutions`` tag_ can be used to conditionally show e.g. solutions
|
||||
* a number of straight-to-HTML directives:
|
||||
|
||||
``h:div``
|
||||
a straight div, can be used instead of ``container`` (which adds the
|
||||
``container`` class to the div it generates, that's really not compatible
|
||||
with Bootstrap_)
|
||||
``h:address``
|
||||
generates an ``<address>`` node
|
||||
a bunch of roles straight to HTML inline
|
||||
``mark``, ``insert``, ``delete``, ``strikethrough``, ``small`, ``kbd`` and
|
||||
``var`` generate the corresponding HTML element
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
* Sphinx 1.1, 1.2 for code Python code links
|
||||
* sphinx-patchqueue (for the content, not the theme)
|
||||
|
||||
.. _lessc: http://lesscss.org/#using-less
|
||||
.. _bootstrap: http://getbootstrap.com
|
||||
.. _sphinx: http://sphinx-doc.org
|
||||
.. _tag: http://sphinx-doc.org/markup/misc.html#including-content-based-on-tags
|
||||
|
|
@ -8,8 +8,8 @@
|
|||
Web Service API
|
||||
===============
|
||||
|
||||
Odoo is mostly extended internally via modules, but much of its features and
|
||||
all of its data is also available from the outside for external analysis or
|
||||
Odoo is usually extended internally via modules, but many of its features and
|
||||
all of its data are also available from the outside for external analysis or
|
||||
integration with various tools. Part of the :ref:`reference/orm/model` API is
|
||||
easily available over XML-RPC_ and accessible from a variety of languages.
|
||||
|
||||
|
|
@ -196,8 +196,8 @@ database:
|
|||
Logging in
|
||||
----------
|
||||
|
||||
Odoo requires users of the API to be authenticated before being able to query
|
||||
much data.
|
||||
Odoo requires users of the API to be authenticated before they can query most
|
||||
data.
|
||||
|
||||
The ``xmlrpc/2/common`` endpoint provides meta-calls which don't require
|
||||
authentication, such as the authentication itself or fetching version
|
||||
|
|
@ -384,7 +384,7 @@ companies for instance:
|
|||
Pagination
|
||||
''''''''''
|
||||
|
||||
By default a research will return the ids of all records matching the
|
||||
By default a search will return the ids of all records matching the
|
||||
condition, which may be a huge number. ``offset`` and ``limit`` parameters are
|
||||
available to only retrieve a subset of all matched records.
|
||||
|
||||
|
|
@ -432,8 +432,8 @@ available to only retrieve a subset of all matched records.
|
|||
Count records
|
||||
-------------
|
||||
|
||||
Rather than retrieve a possibly gigantic list of records and count them
|
||||
afterwards, :meth:`~openerp.models.Model.search_count` can be used to retrieve
|
||||
Rather than retrieve a possibly gigantic list of records and count them,
|
||||
:meth:`~openerp.models.Model.search_count` can be used to retrieve
|
||||
only the number of records matching the query. It takes the same
|
||||
:ref:`domain <reference/orm/domains>` filter as
|
||||
:meth:`~openerp.models.Model.search` and no other parameter.
|
||||
|
|
@ -600,8 +600,7 @@ Listing record fields
|
|||
:meth:`~openerp.models.Model.fields_get` can be used to inspect
|
||||
a model's fields and check which ones seem to be of interest.
|
||||
|
||||
Because
|
||||
it returns a great amount of meta-information (it is also used by client
|
||||
Because it returns a large amount of meta-information (it is also used by client
|
||||
programs) it should be filtered before printing, the most interesting items
|
||||
for a human user are ``string`` (the field's label), ``help`` (a help text if
|
||||
available) and ``type`` (to know which values to expect, or to send when
|
||||
|
|
@ -682,7 +681,7 @@ updating a record):
|
|||
Search and read
|
||||
---------------
|
||||
|
||||
Because that is a very common task, Odoo provides a
|
||||
Because it is a very common task, Odoo provides a
|
||||
:meth:`~openerp.models.Model.search_read` shortcut which as its name notes is
|
||||
equivalent to a :meth:`~openerp.models.Model.search` followed by a
|
||||
:meth:`~openerp.models.Model.read`, but avoids having to perform two requests
|
||||
|
|
@ -690,7 +689,7 @@ and keep ids around.
|
|||
|
||||
Its arguments are similar to :meth:`~openerp.models.Model.search`'s, but it
|
||||
can also take a list of ``fields`` (like :meth:`~openerp.models.Model.read`,
|
||||
if that list is not provided it'll fetch all fields of matched records):
|
||||
if that list is not provided it will fetch all fields of matched records):
|
||||
|
||||
.. container:: doc-aside
|
||||
|
||||
|
|
@ -888,8 +887,8 @@ a record).
|
|||
Delete records
|
||||
--------------
|
||||
|
||||
Records can be deleted in bulk by providing the ids of all records to remove
|
||||
to :meth:`~openerp.models.Model.unlink`.
|
||||
Records can be deleted in bulk by providing their ids to
|
||||
:meth:`~openerp.models.Model.unlink`.
|
||||
|
||||
.. container:: doc-aside
|
||||
|
||||
|
|
@ -945,7 +944,7 @@ Inspection and introspection
|
|||
isn't exactly fun in RPC.
|
||||
|
||||
While we previously used :meth:`~openerp.models.Model.fields_get` to query a
|
||||
model's and have been using an arbitrary model from the start, Odoo stores
|
||||
model and have been using an arbitrary model from the start, Odoo stores
|
||||
most model metadata inside a few meta-models which allow both querying the
|
||||
system and altering models and fields (with some limitations) on the fly over
|
||||
XML-RPC.
|
||||
|
|
@ -955,7 +954,7 @@ XML-RPC.
|
|||
``ir.model``
|
||||
''''''''''''
|
||||
|
||||
Provides informations about Odoo models themselves via its various fields
|
||||
Provides information about Odoo models via its various fields
|
||||
|
||||
``name``
|
||||
a human-readable description of the model
|
||||
|
|
@ -1100,7 +1099,7 @@ Provides informations about Odoo models themselves via its various fields
|
|||
``ir.model.fields``
|
||||
'''''''''''''''''''
|
||||
|
||||
Provides informations about the fields of Odoo models and allows adding
|
||||
Provides information about the fields of Odoo models and allows adding
|
||||
custom fields without using Python code
|
||||
|
||||
``model_id``
|
||||
|
|
@ -1285,7 +1284,7 @@ the workflow instance associated with the record.
|
|||
|
||||
.. container:: doc-aside
|
||||
|
||||
.. warning:: requires that the ``account`` module be installed
|
||||
.. warning:: this example needs ``account`` module installed
|
||||
|
||||
.. switcher::
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,11 @@
|
|||
United Kingdom, 2015-05-22
|
||||
|
||||
I hereby agree to the terms of the Odoo Individual Contributor License
|
||||
Agreement v1.0.
|
||||
|
||||
I declare that I am authorized and able to make this agreement and sign this
|
||||
declaration.
|
||||
|
||||
Signed,
|
||||
|
||||
John Bradshaw - jbradsha@github.com - https://github.com/jbradsha
|
||||
|
|
@ -148,7 +148,7 @@ In Odoo web, modules are declared as functions set on the global ``openerp``
|
|||
variable. The function's name must be the same as the addon (in this case
|
||||
``oepetstore``) so the framework can find it, and automatically initialize it.
|
||||
|
||||
When the web client decides to load your module, it'll call the root function
|
||||
When the web client loads your module it will call the root function
|
||||
and provide two parameters:
|
||||
|
||||
* the first parameter is the current instance of the Odoo web client, it gives
|
||||
|
|
@ -168,7 +168,7 @@ Much as modules, and contrary to most object-oriented languages, javascript
|
|||
does not build in *classes*\ [#classes]_ although it provides roughly
|
||||
equivalent (if lower-level and more verbose) mechanisms.
|
||||
|
||||
For simplicity and developer-friendliness purposes, Odoo web provides a class
|
||||
For simplicity and developer-friendliness Odoo web provides a class
|
||||
system based on John Resig's `Simple JavaScript Inheritance`_.
|
||||
|
||||
New classes are defined by calling the :func:`~openerp.web.Class.extend`
|
||||
|
|
@ -307,7 +307,7 @@ This line at the end of the file::
|
|||
'petstore.homepage', 'instance.oepetstore.HomePage');
|
||||
|
||||
registers our basic widget as a client action. Client actions will be
|
||||
explained later in the guide, for now this is just what allows our widget to
|
||||
explained later, for now this is just what allows our widget to
|
||||
be called and displayed when we select the
|
||||
:menuselection:`Pet Store --> Pet Store --> Home Page` menu.
|
||||
|
||||
|
|
@ -335,9 +335,9 @@ section of page they're in charge of (as a jQuery_ object). Widget content
|
|||
should be inserted there. By default, :attr:`~openerp.Widget.$el` is an
|
||||
empty ``<div>`` element.
|
||||
|
||||
A ``<div>`` element is usually invisible for the user if it does not
|
||||
have any content (or specific styles giving it a size) which is why nothing
|
||||
is displayed on the page when ``HomePage`` is launched.
|
||||
A ``<div>`` element is usually invisible to the user if it has no content (or
|
||||
without specific styles giving it a size) which is why nothing is displayed
|
||||
on the page when ``HomePage`` is launched.
|
||||
|
||||
Let's add some content to the widget's root element, using jQuery::
|
||||
|
||||
|
|
@ -353,10 +353,10 @@ That message will now appear when you open :menuselection:`Pet Store
|
|||
.. note::
|
||||
|
||||
to refresh the javascript code loaded in Odoo Web, you will need to reload
|
||||
the page. There is no need to restart the Odoo server
|
||||
the page. There is no need to restart the Odoo server.
|
||||
|
||||
The ``HomePage`` widget is used by Odoo Web and managed automatically, to
|
||||
learn how to use a widget "from scratch" let's create a new one::
|
||||
The ``HomePage`` widget is used by Odoo Web and managed automatically.
|
||||
To learn how to use a widget "from scratch" let's create a new one::
|
||||
|
||||
local.GreetingsWidget = instance.Widget.extend({
|
||||
start: function() {
|
||||
|
|
@ -438,7 +438,7 @@ of another widget, and exist on behalf of it. We call the container the
|
|||
*parent*, and the contained widget the *child*.
|
||||
|
||||
Due to multiple technical and conceptual reasons, it is necessary for a widget
|
||||
to know who is his parent and who are its children.
|
||||
to know who is its parent and who are its children.
|
||||
|
||||
:func:`~openerp.Widget.getParent`
|
||||
can be used to get the parent of a widget::
|
||||
|
|
@ -508,9 +508,9 @@ manipulating (and adding to) their DOM::
|
|||
|
||||
this.$el.append("<div>Hello dear Odoo user!</div>");
|
||||
|
||||
This allows generating and displaying any type of content, but tends to
|
||||
rapidly get unwieldy when generating significant amounts of DOM (lots of
|
||||
duplication, quoting issues, ...)
|
||||
This allows generating and displaying any type of content, but gets unwieldy
|
||||
when generating significant amounts of DOM (lots of duplication, quoting
|
||||
issues, ...)
|
||||
|
||||
As many other environments, Odoo's solution is to use a `template engine`_.
|
||||
Odoo's template engine is called :ref:`reference/qweb`.
|
||||
|
|
@ -578,7 +578,7 @@ the template can be set directly on the widget via its
|
|||
},
|
||||
});
|
||||
|
||||
Although the result look similar, there are two differences between these
|
||||
Although the result looks similar, there are two differences between these
|
||||
usages:
|
||||
|
||||
* with the second version, the template is rendered right before
|
||||
|
|
@ -916,9 +916,8 @@ Selecting DOM elements within a widget can be performed by calling the
|
|||
|
||||
this.$el.find("input.my_input")...
|
||||
|
||||
But because it's an extremely common operation, :class:`~openerp.Widget`
|
||||
provides an equivalent shortcut through the :func:`~openerp.Widget.$`
|
||||
method::
|
||||
But because it's a common operation, :class:`~openerp.Widget` provides an
|
||||
equivalent shortcut through the :func:`~openerp.Widget.$` method::
|
||||
|
||||
local.MyWidget = instance.Widget.extend({
|
||||
start: function() {
|
||||
|
|
@ -1109,7 +1108,7 @@ Exercise
|
|||
Then, modify the ``HomePage`` widget to instantiate ``ColorInputWidget``
|
||||
and display it. The ``HomePage`` widget should also display an empty
|
||||
rectangle. That rectangle must always, at any moment, have the same
|
||||
background color than the color in the ``color`` property of the
|
||||
background color as the color in the ``color`` property of the
|
||||
``ColorInputWidget`` instance.
|
||||
|
||||
Use QWeb to generate all HTML.
|
||||
|
|
@ -1366,11 +1365,10 @@ by the server to translate all the messages of the application. Another one is
|
|||
the time zone of the user, used to compute correctly dates and times if Odoo
|
||||
is used by people in different countries.
|
||||
|
||||
The ``argument`` is necessary in all methods, because if we forget it bad
|
||||
things could happen (like the application not being translated
|
||||
correctly). That's why, when you call a model's method, you should always give
|
||||
it to that argument. The solution to achieve that is to use
|
||||
:class:`openerp.web.CompoundContext`.
|
||||
The ``argument`` is necessary in all methods, otherwise bad things could
|
||||
happen (such as the application not being translated correctly). That's why,
|
||||
when you call a model's method, you should always provide that argument. The
|
||||
solution to achieve that is to use :class:`openerp.web.CompoundContext`.
|
||||
|
||||
:class:`~openerp.web.CompoundContext` is a class used to pass the user's
|
||||
context (with language, time zone, etc...) to the server as well as adding new
|
||||
|
|
@ -1433,7 +1431,7 @@ versus::
|
|||
:class:`~openerp.web.Query` for its customization options.
|
||||
|
||||
When the query is set up as desired, simply call
|
||||
:func:`~openerp.web.Query.all` to perform the actual query and return a
|
||||
:func:`~openerp.web.Query.all` to execute it and return a
|
||||
deferred to its result. The result is the same as
|
||||
:py:meth:`~openerp.models.Model.read`'s, an array of dictionaries where each
|
||||
dictionary is a requested record, with each requested field a dictionary key.
|
||||
|
|
@ -1516,7 +1514,7 @@ Exercises
|
|||
``product.product`` using a special category *Pet Toys*. You can see the
|
||||
pre-generated toys and add new ones by going to
|
||||
:menuselection:`Pet Store --> Pet Store --> Pet Toys`. You will probably
|
||||
need to explore ``product.product`` in order to create the right domain to
|
||||
need to explore ``product.product`` to create the right domain to
|
||||
select just pet toys.
|
||||
|
||||
In Odoo, images are generally stored in regular fields encoded as
|
||||
|
|
@ -1840,10 +1838,10 @@ Views may also want to handle search queries by overriding
|
|||
The Form View Fields
|
||||
--------------------
|
||||
|
||||
A common Odoo web need is the extension of the form view to add new ways of
|
||||
displaying form fields.
|
||||
A common need is the extension of the web form view to add new ways of
|
||||
displaying fields.
|
||||
|
||||
All built-in fields have a default display implementation, creating a new
|
||||
All built-in fields have a default display implementation, a new
|
||||
form widget may be necessary to correctly interact with a new field type
|
||||
(e.g. a :term:`GIS` field) or to provide new representations and ways to
|
||||
interact with existing field types (e.g. validate
|
||||
|
|
@ -1871,7 +1869,7 @@ simply use the ``widget`` attribute in the view's XML description:
|
|||
Fields are instantiated by the form view after it has read its XML description
|
||||
and constructed the corresponding HTML representing that description. After
|
||||
that, the form view will communicate with the field objects using some
|
||||
methods. Theses methods are defined by the ``FieldInterface``
|
||||
methods. These methods are defined by the ``FieldInterface``
|
||||
interface. Almost all fields inherit the ``AbstractField`` abstract
|
||||
class. That class defines some default mechanisms that need to be implemented
|
||||
by most fields.
|
||||
|
|
@ -1926,13 +1924,13 @@ Creating a New Type of Field
|
|||
''''''''''''''''''''''''''''
|
||||
|
||||
In this part we will explain how to create a new type of field. The example
|
||||
here will be to re-implement the ``FieldChar`` class and explain progressively
|
||||
here will be to re-implement the ``FieldChar`` class and progressively explain
|
||||
each part.
|
||||
|
||||
Simple Read-Only Field
|
||||
""""""""""""""""""""""
|
||||
|
||||
Here is a first implementation that will only be able to display a text. The
|
||||
Here is a first implementation that will only display text. The
|
||||
user will not be able to modify the content of the field.
|
||||
|
||||
.. code-block:: javascript
|
||||
|
|
@ -1972,16 +1970,16 @@ none is specified by the form view (here we assume the default value of a
|
|||
Read-Write Field
|
||||
""""""""""""""""
|
||||
|
||||
Fields that only display their content and don't give the possibility to the
|
||||
user to modify it can be useful, but most fields in Odoo allow edition
|
||||
too. This makes the field classes more complicated, mostly because fields are
|
||||
Read-only fields, which only display content and don't allow the
|
||||
user to modify it can be useful, but most fields in Odoo also allow editing.
|
||||
This makes the field classes more complicated, mostly because fields are
|
||||
supposed to handle both and editable and non-editable mode, those modes are
|
||||
often completely different (for design and usability purpose) and the fields
|
||||
must be able to switch from one mode to another at any moment.
|
||||
must be able to switch between modes at any moment.
|
||||
|
||||
To know in which mode the current field should be, the ``AbstractField`` class
|
||||
sets a widget property named ``effective_readonly``. The field should watch
|
||||
the changes in that widget property and display the correct mode
|
||||
for changes in that widget property and display the correct mode
|
||||
accordingly. Example::
|
||||
|
||||
local.FieldChar2 = instance.web.form.AbstractField.extend({
|
||||
|
|
@ -2027,17 +2025,16 @@ accordingly. Example::
|
|||
</div>
|
||||
</t>
|
||||
|
||||
In the ``start()`` method (which is called right after a widget has been
|
||||
In the ``start()`` method (which is called immediately after a widget has been
|
||||
appended to the DOM), we bind on the event ``change:effective_readonly``. That
|
||||
will allow use to redisplay the field each time the widget property
|
||||
allows us to redisplay the field each time the widget property
|
||||
``effective_readonly`` changes. This event handler will call
|
||||
``display_field()``, which is also called directly in ``start()``. This
|
||||
``display_field()`` was created specifically for this field, it's not a method
|
||||
defined in ``AbstractField`` or any other class. This is the method we will
|
||||
use to display the content of the field depending we are in read-only mode or
|
||||
not.
|
||||
defined in ``AbstractField`` or any other class. We can use this method
|
||||
to display the content of the field depending on the current mode.
|
||||
|
||||
From now on the conception of this field is quite typical, except there is a
|
||||
From now on the conception of this field is typical, except there is a
|
||||
lot of verifications to know the state of the ``effective_readonly`` property:
|
||||
|
||||
* In the QWeb template used to display the content of the widget, it displays
|
||||
|
|
@ -2243,7 +2240,7 @@ the most useful being:
|
|||
|
||||
.. _See the online documentation to know how to use it: http://www.w3schools.com/html/html5_geolocation.asp
|
||||
|
||||
Please also note that it wouldn't be very logical to allow the user to
|
||||
Please also note that the user should not be able to
|
||||
click on that button when the form view is in read-only mode. So, this
|
||||
custom widget should handle correctly the ``effective_readonly`` property
|
||||
just like any field. One way to do this would be to make the button
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ behaviors or by altering existing ones (including behaviors added by other
|
|||
modules).
|
||||
|
||||
:ref:`Odoo's scaffolding <reference/cmdline/scaffold>` can setup a basic
|
||||
module to quickly get started, simply invoke:
|
||||
module. To quickly get started simply invoke:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -30,7 +30,7 @@ module to quickly get started, simply invoke:
|
|||
|
||||
This will automatically create a ``my-modules`` *module directory* with an
|
||||
``academy`` module inside. The directory can be an existing module directory
|
||||
if you want, but the module name must be unique for the directory.
|
||||
if you want, but the module name must be unique within the directory.
|
||||
|
||||
.. patch::
|
||||
:hidden:
|
||||
|
|
@ -40,7 +40,7 @@ A demonstration module
|
|||
|
||||
We have a "complete" module ready for installation.
|
||||
|
||||
Although it does absolutely nothing yet we can install it:
|
||||
Although it does absolutely nothing we can install it:
|
||||
|
||||
* start the Odoo server
|
||||
|
||||
|
|
@ -118,8 +118,8 @@ Storing data in Odoo
|
|||
:ref:`Odoo models <reference/orm/model>` map to database tables.
|
||||
|
||||
In the previous section we just displayed a list of string entered statically
|
||||
in the Python code. This doesn't allow modifications and persistent storage
|
||||
thereof, so we're now going to move our data to the database.
|
||||
in the Python code. This doesn't allow modifications or persistent storage
|
||||
so we'll now move our data to the database.
|
||||
|
||||
Defining the data model
|
||||
-----------------------
|
||||
|
|
@ -139,13 +139,13 @@ left empty).
|
|||
|
||||
.. note::
|
||||
|
||||
:ref:`Data files <reference/data>` (XML or CSV) have to be added to the
|
||||
:ref:`Data files <reference/data>` (XML or CSV) must be added to the
|
||||
module manifest, Python files (models or controllers) don't but have to
|
||||
be imported from ``__init__.py`` (directly or indirectly)
|
||||
|
||||
.. warning::
|
||||
|
||||
the administrator user bypasses access control, he has access to all
|
||||
the administrator user bypasses access control, they have access to all
|
||||
models even if not given access
|
||||
|
||||
Demonstration data
|
||||
|
|
@ -182,9 +182,9 @@ The last step is to alter model and template to use our demonstration data:
|
|||
|
||||
Restart the server and update the module (in order to update the manifest
|
||||
and templates and load the demo file) then navigate to
|
||||
http://localhost:8069/academy/academy/. The page should look little different:
|
||||
names should simply be prefixed by a number (the database identifier for the
|
||||
teacher).
|
||||
http://localhost:8069/academy/academy/. The page should look slightly
|
||||
different: names should simply be prefixed by a number (the database
|
||||
identifier for the teacher).
|
||||
|
||||
Website support
|
||||
===============
|
||||
|
|
@ -383,7 +383,7 @@ let's also add views so we can see and edit a course's teacher:
|
|||
.. patch::
|
||||
|
||||
It should also be possible to create new courses directly from a teacher's
|
||||
page, or to see all the courses a teacher gives, so add
|
||||
page, or to see all the courses they teach, so add
|
||||
:class:`the inverse relationship <openerp.fields.One2many>` to the *teachers*
|
||||
model:
|
||||
|
||||
|
|
@ -392,8 +392,8 @@ model:
|
|||
Discussions and notifications
|
||||
-----------------------------
|
||||
|
||||
Odoo provides technical models, which don't fulfill business needs in and of
|
||||
themselves but add capabilities to business objects without having to build
|
||||
Odoo provides technical models, which don't directly fulfill business needs
|
||||
but which add capabilities to business objects without having to build
|
||||
them by hand.
|
||||
|
||||
One of these is the *Chatter* system, part of Odoo's email and messaging
|
||||
|
|
|
|||
|
|
@ -7,8 +7,8 @@ Asynchronous Operations
|
|||
|
||||
As a language (and runtime), javascript is fundamentally
|
||||
single-threaded. This means any blocking request or computation will
|
||||
blocks the whole page (and, in older browsers, the software itself
|
||||
even preventing users from switching to an other tab): a javascript
|
||||
block the whole page (and, in older browsers, the software itself
|
||||
even preventing users from switching to another tab): a javascript
|
||||
environment can be seen as an event-based runloop where application
|
||||
developers have no control over the runloop itself.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,21 +2,20 @@
|
|||
|
||||
.. highlight:: python
|
||||
|
||||
=================
|
||||
===============
|
||||
Odoo Guidelines
|
||||
=================
|
||||
===============
|
||||
|
||||
This page introduce the new Odoo Coding Guidelines. This guidelines
|
||||
aims to improve the quality of the code (better readability of source,
|
||||
...) but also to improve Odoo Apps ! Indeed, a proper code will ease
|
||||
the maintenance and debugging, lower the complexity and promote the
|
||||
reliability.
|
||||
This page introduce the new Odoo Coding Guidelines. These guidelines
|
||||
aim to improve the quality of the code (better readability of source,
|
||||
...) and Odoo Apps. Indeed, proper code ought ease maintenance, aid
|
||||
debugging, lower complexity and promote reliability.
|
||||
|
||||
Module structure
|
||||
================
|
||||
|
||||
Directories
|
||||
------------
|
||||
-----------
|
||||
A module is organised in a few directory :
|
||||
|
||||
- *data/* : demo and data xml
|
||||
|
|
@ -26,24 +25,24 @@ A module is organised in a few directory :
|
|||
- *static/* : contains the web assets, separated into *css/, js/, img/, lib/, ...*
|
||||
|
||||
File naming
|
||||
------------
|
||||
-----------
|
||||
For *views* declarations, split backend views from (frontend)
|
||||
templates in 2 differents files.
|
||||
|
||||
For *models*, split the business logic by sets of models, in each sets
|
||||
For *models*, split the business logic by sets of models, in each set
|
||||
select a main model, this model gives its name to the set. If there is
|
||||
only one set of module, its name is the same as the module name. For
|
||||
only one model, its name is the same as the module name. For
|
||||
each set named <main_model> the following files may be created:
|
||||
|
||||
- models/<main_model>.py
|
||||
- models/<inherited_main_model.py
|
||||
- views/<main_model>_templates.xml
|
||||
- views/<main_model>_views.xml
|
||||
- :file:`models/{<main_model>}.py`
|
||||
- :file:`models/{<inherited_main_model>}.py`
|
||||
- :file:`views/{<main_model>}_templates.xml`
|
||||
- :file:`views/{<main_model>}_views.xml`
|
||||
|
||||
For instance, *sale* module introduce ``sale_order`` and
|
||||
For instance, *sale* module introduces ``sale_order`` and
|
||||
``sale_order_line`` where ``sale_order`` is dominant. So the
|
||||
<main_model> files will be named *models/sale_order.py* and
|
||||
*views/sale_order_views.py*.
|
||||
``<main_model>`` files will be named :file:`models/sale_order.py` and
|
||||
:file:`views/sale_order_views.py`.
|
||||
|
||||
|
||||
For *data*, split them by purpose : demo or data. The filename will be
|
||||
|
|
@ -56,7 +55,7 @@ static/js/im_chat.js, static/css/im_chat.css, static/xml/im_chat.xml,
|
|||
...). Don't link data (image, libraries) outside Odoo : don't use an
|
||||
url to an image but copy it in our codebase instead.
|
||||
|
||||
The complete tree should looks like
|
||||
The complete tree should look like
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
|
|
@ -98,7 +97,8 @@ The complete tree should looks like
|
|||
`-- <inherited_main_model>_views.xml
|
||||
|
||||
|
||||
.. note:: Filename should only use only ``[a-z0-9_]``
|
||||
.. note:: File names should only contain ``[a-z0-9_]`` (lowercase
|
||||
alphanumerics and ``_``)
|
||||
|
||||
.. warning:: Use correct file permissions : folder 755 and file 644.
|
||||
|
||||
|
|
@ -143,16 +143,17 @@ Security, View and Action
|
|||
|
||||
Use the following pattern :
|
||||
|
||||
* For a menu : *<model_name>_menu*
|
||||
* For a view : *<model_name>_view_<view_type>*, where *view_type* is kanban, form, tree, search, ...
|
||||
* For an action : the main action respects *<model_name>_action*.
|
||||
Others are suffixed with *_<detail>*, where *detail* is a underscore
|
||||
lowercase string explaining a little bit the action (Should not be
|
||||
long). This is used only if multiple action are declared for the
|
||||
* For a menu: :samp:`{<model_name>}_menu`
|
||||
* For a view: :samp:`{<model_name>}_view_{<view_type>}`, where *view_type* is
|
||||
``kanban``, ``form``, ``tree``, ``search``, ...
|
||||
* For an action: the main action respects :samp:`{<model_name>}_action`.
|
||||
Others are suffixed with :samp:`_{<detail>}`, where *detail* is a
|
||||
lowercase string briefly explaining the action.
|
||||
This is used only if multiple actions are declared for the
|
||||
model.
|
||||
* For a group : *<model_name>_group_<group_name>* where *group_name*
|
||||
is the name of the group, genrally 'user', 'manager', ...
|
||||
* For a rule : *<model_name>_rule_<concerned_group>* where
|
||||
* For a group: :samp:`{<model_name>}_group_{<group_name>} where *group_name*
|
||||
is the name of the group, generally 'user', 'manager', ...
|
||||
* For a rule: :samp:`{<model_name>}_rule_{<concerned_group>}` where
|
||||
*concerned_group* is the short name of the concerned group ('user'
|
||||
for the 'model_name_group_user', 'public' for public user, 'company'
|
||||
for multi-company rules, ...).
|
||||
|
|
@ -196,12 +197,19 @@ Use the following pattern :
|
|||
|
||||
|
||||
|
||||
.. note:: View name use dot notation ``my.model.view_type`` or ``my.model.view_type.inherit`` instead of *"This is the form view of My Model"*.
|
||||
.. note:: View names use dot notation ``my.model.view_type`` or
|
||||
``my.model.view_type.inherit`` instead of *"This is the form view of
|
||||
My Model"*.
|
||||
|
||||
|
||||
Inherited XML
|
||||
~~~~~~~~~~~~~
|
||||
The naming pattern of inherited view is *<base_view>_inherit_<current_module_name>*. A module can extend a view only one time, suffix the orginal name with *_inherit_<current_module_name>*, where *current_module_name* is the technical name of the module extending the view.
|
||||
|
||||
The naming pattern of inherited view is
|
||||
:samp:`{<base_view>}_inherit_{<current_module_name>}`. A module may only
|
||||
extend a view once. Suffix the orginal name with
|
||||
:samp:`_inherit_{<current_module_name>}` where *current_module_name* is the
|
||||
technical name of the module extending the view.
|
||||
|
||||
|
||||
.. code-block:: xml
|
||||
|
|
@ -217,7 +225,8 @@ Python
|
|||
PEP8 options
|
||||
------------
|
||||
|
||||
Using a linter can help to see syntax and semantic warning or error. Odoo Source Code try to respect Python standard, but some of them can be ignored.
|
||||
Using a linter can help show syntax and semantic warnings or errors. Odoo
|
||||
source code tries to respect Python standard, but some of them can be ignored.
|
||||
|
||||
- E501: line too long
|
||||
- E301: expected 1 blank line, found 0
|
||||
|
|
@ -232,7 +241,7 @@ Imports
|
|||
-------
|
||||
The imports are ordered as
|
||||
|
||||
#. Externals libs (One per line sorted and splitted in python stdlib)
|
||||
#. External libraries (one per line sorted and split in python stdlib)
|
||||
#. Imports of ``openerp``
|
||||
#. Imports from Odoo modules (rarely, and only if necessary)
|
||||
|
||||
|
|
@ -255,7 +264,7 @@ Inside these 3 groups, the imported lines are alphabetically sorted.
|
|||
|
||||
|
||||
Idioms
|
||||
-------
|
||||
------
|
||||
|
||||
- Prefer ``%`` over ``.format()``, prefer ``%(varname)`` instead of position (This is better for translation)
|
||||
- Try to avoid generators and decorators
|
||||
|
|
@ -306,8 +315,8 @@ Symbols
|
|||
- In a Model attribute order should be
|
||||
#. Private attributes (``_name``, ``_description``, ``_inherit``, ...)
|
||||
#. Default method and ``_default_get``
|
||||
#. Fields declarations
|
||||
#. Compute and search methods in the same order than field declaration
|
||||
#. Field declarations
|
||||
#. Compute and search methods in the same order as field declaration
|
||||
#. Constrains methods (``@api.constrains``) and onchange methods (``@api.onchange``)
|
||||
#. CRUD methods (ORM overrides)
|
||||
#. Action methods
|
||||
|
|
@ -396,19 +405,18 @@ Prefix your commit with
|
|||
|
||||
Then, in the message itself, specify the part of the code impacted by your changes (module name, lib, transversal object, ...) and a description of the changes.
|
||||
|
||||
- Always put meaning full commit message: commit message should be
|
||||
self explanatory (long enough) including the name of the module that
|
||||
has been changed and the reason behind that change. Do not use
|
||||
single words like "bugfix" or "improvements".
|
||||
|
||||
- Avoid commits which simultaneously impacts lots of modules. Try to
|
||||
splits into different commits where impacted modules are different
|
||||
(It will be helpful when we are going to revert that module
|
||||
separately).
|
||||
- Always include a meaningful commit message: it should be self explanatory
|
||||
(long enough) including the name of the module that has been changed and the
|
||||
reason behind the change. Do not use single words like "bugfix" or
|
||||
"improvements".
|
||||
- Avoid commits which simultaneously impact multiple modules. Try to
|
||||
split into different commits where impacted modules are different
|
||||
(It will be helpful if we need to revert a module separately).
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
[FIX] website, website_mail: remove unused alert div, fixes look of input-group-btn
|
||||
|
||||
Bootstrap's CSS depends on the input-group-btn
|
||||
element being the first/last child of its parent.
|
||||
This was not the case because of the invisible
|
||||
|
|
@ -417,10 +425,11 @@ Then, in the message itself, specify the part of the code impacted by your chang
|
|||
[IMP] fields: reduce memory footprint of list/set field attributes
|
||||
|
||||
[REF] web: add module system to the web client
|
||||
|
||||
This commit introduces a new module system for the javascript code.
|
||||
Instead of using global ...
|
||||
|
||||
|
||||
.. note:: The long description try to explain the *why* not the
|
||||
*what*, the *what* can be seen in the diff
|
||||
.. note:: Use the long description to explain the *why* not the
|
||||
*what*, the *what* can be seen in the diff
|
||||
|
||||
|
|
|
|||
|
|
@ -11,11 +11,11 @@ Modules
|
|||
Manifest
|
||||
========
|
||||
|
||||
The manifest file serves to both declare a python package as an Odoo module,
|
||||
and to specify a number of module metadata.
|
||||
The manifest file serves to declare a python package as an Odoo module
|
||||
and to specify module metadata.
|
||||
|
||||
It is a file called ``__openerp__.py`` and contains a single Python
|
||||
dictionary, each dictionary key specifying a module metadatum.
|
||||
dictionary, where each key specifies module metadatum.
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -66,7 +66,7 @@ Available manifest fields are:
|
|||
define.
|
||||
|
||||
When a module is installed, all of its dependencies are installed before
|
||||
it. Likewise during modules loading.
|
||||
it. Likewise dependencies are loaded before a module is loaded.
|
||||
``data`` (``list(str)``)
|
||||
List of data files which must always be installed or updated with the
|
||||
module. A list of paths from the module root directory
|
||||
|
|
|
|||
|
|
@ -24,12 +24,12 @@ Each access control has a model to which it grants permissions, the
|
|||
permissions it grants and optionally a group.
|
||||
|
||||
Access controls are additive, for a given model a user has access all
|
||||
permissions granted to any of its groups: if the user belongs to group *A*
|
||||
which allows writing and group *B* which allows deleting, he can both write
|
||||
permissions granted to any of its groups: if the user belongs to one group
|
||||
which allows writing and another which allows deleting, they can both write
|
||||
and delete.
|
||||
|
||||
If no group is specified, the access control applies to all users, otherwise
|
||||
it only applies to the users belonging to the specific group.
|
||||
it only applies to the members of the given group.
|
||||
|
||||
Available permissions are creation (``perm_create``), searching and reading
|
||||
(``perm_read``), updating existing records (``perm_write``) and deleting
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ your module's translatable terms and may find content to work with.
|
|||
|
||||
.. todo:: needs technical features
|
||||
|
||||
Translations export is done via the administration interface by logging into
|
||||
Translations export is performed via the administration interface by logging into
|
||||
the backend interface and opening :menuselection:`Settings --> Translations
|
||||
--> Import / Export --> Export Translations`
|
||||
|
||||
|
|
@ -68,7 +68,7 @@ Explicit exports
|
|||
================
|
||||
|
||||
When it comes to more "imperative" situations in Python code or Javascript
|
||||
code, Odoo is not able to automatically export translatable terms and they
|
||||
code, Odoo cannot automatically export translatable terms so they
|
||||
must be marked explicitly for export. This is done by wrapping a literal
|
||||
string in a function call.
|
||||
|
||||
|
|
@ -84,11 +84,11 @@ In JavaScript, the wrapping function is generally :js:func:`openerp.web._t`:
|
|||
|
||||
.. warning::
|
||||
|
||||
Only literal strings can be marked for exports, not expressions and not
|
||||
Only literal strings can be marked for exports, not expressions or
|
||||
variables. For situations where strings are formatted, this means the
|
||||
format string must be marked, not the formatted string::
|
||||
|
||||
# bad, the extract may work but it will not correctly translate the text
|
||||
# bad, the extract may work but it will not translate the text correctly
|
||||
_("Scheduled meeting with %s" % invitee.name)
|
||||
|
||||
# good
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ Common Structure
|
|||
================
|
||||
|
||||
View objects expose a number of fields, they are optional unless specified
|
||||
otherwise)
|
||||
otherwise.
|
||||
|
||||
``name`` (mandatory)
|
||||
only useful as a mnemonic/description of the view when looking for one in
|
||||
|
|
@ -22,7 +22,7 @@ otherwise)
|
|||
the model linked to the view, if applicable (it doesn't for QWeb views)
|
||||
``priority``
|
||||
client programs can request views by ``id``, or by ``(model, type)``. For
|
||||
the latter, all the views for the right type and model will be looked for,
|
||||
the latter, all the views for the right type and model will be searched,
|
||||
and the one with the lowest ``priority`` number will be returned (it is
|
||||
the "default view").
|
||||
|
||||
|
|
@ -147,7 +147,7 @@ root can have the following attributes:
|
|||
|
||||
Defined as a mapping of colors to Python expressions. Values are of the
|
||||
form: :samp:`{color}:{expr}[;...]`. For each record, pairs are tested
|
||||
in-order, the expression is evaluated for the record and if ``true`` the
|
||||
in order, the expression is evaluated for the record and if ``true`` the
|
||||
corresponding color is applied to the row. If no color matches, uses the
|
||||
default text color (black).
|
||||
|
||||
|
|
@ -572,7 +572,7 @@ Button Box
|
|||
..........
|
||||
|
||||
Many relevant actions or links can be displayed in the form. For example, in
|
||||
Opportunity form, the actions "Schedule a Call" and "Schedule a Meeting" take
|
||||
Opportunity form, the actions "Schedule a Call" and "Schedule a Meeting" have
|
||||
an important place in the use of the CRM. Instead of placing them in the
|
||||
"More" menu, put them directly in the sheet as buttons (on the top right) to
|
||||
make them more visible and more easily accessible.
|
||||
|
|
|
|||
|
|
@ -115,7 +115,7 @@ Activities
|
|||
----------
|
||||
|
||||
While the transitions can be seen as the control structures of the workflows,
|
||||
activities are the places where everything happens, from changing record
|
||||
activities are where everything happens, from changing record
|
||||
states to sending email.
|
||||
|
||||
Different kinds of activities exist: ``Dummy``, ``Function``, ``Subflow``, and
|
||||
|
|
|
|||
|
|
@ -42,14 +42,14 @@ connections (from "localhost", the same machine the PostgreSQL server is
|
|||
installed on).
|
||||
|
||||
UNIX socket is fine if you want Odoo and PostgreSQL to execute on the same
|
||||
machine, and the default when no host is provided, but if you want Odoo and
|
||||
machine, and is the default when no host is provided, but if you want Odoo and
|
||||
PostgreSQL to execute on different machines [#different-machines]_ it will
|
||||
need to `listen to network interfaces`_ [#remote-socket]_, either:
|
||||
|
||||
* only accept loopback connections and `use an SSH tunnel`_ between the
|
||||
machine on which Odoo runs and the one on which PostgreSQL runs, then
|
||||
configure Odoo to connect to its end of the tunnel
|
||||
* accept connections to the machine on which Odoo is installed, possibly with
|
||||
* accept connections to the machine on which Odoo is installed, possibly
|
||||
over ssl (see `PostgreSQL connection settings`_ for details), then configure
|
||||
Odoo to connect over the network
|
||||
|
||||
|
|
@ -79,7 +79,7 @@ create a new user (``odoo``) and set it as the database user.
|
|||
to be completely non-functional, the user needs to be created with
|
||||
``no-createdb`` and the database must be owned by a different user.
|
||||
|
||||
.. warning:: the user also needs to *not* be a superuser
|
||||
.. warning:: the user *must not* be a superuser
|
||||
|
||||
HTTPS
|
||||
=====
|
||||
|
|
@ -160,7 +160,7 @@ most HTTP connections are relatively short and quickly free up their worker
|
|||
process for the next request, LiveChat require a long-lived connection for
|
||||
each client in order to implement near-real-time notifications.
|
||||
|
||||
This is in conflict with the process-based worker model, as it's going to tie
|
||||
This is in conflict with the process-based worker model, as it will tie
|
||||
up worker processes and prevent new users from accessing the system. However,
|
||||
those long-lived connections do very little and mostly stay parked waiting for
|
||||
notifications.
|
||||
|
|
|
|||
Loading…
Reference in New Issue