From 31a0ee2ec4ea9217e0cf94d431e2487931001de0 Mon Sep 17 00:00:00 2001 From: David Harper Date: Sun, 29 Nov 2020 11:35:29 +0000 Subject: [PATCH] Use double backticks for literals in documentation issue9827 review335091002 --- doc/ref/bus.rst | 36 ++++----- doc/ref/cache.rst | 24 +++--- doc/ref/exceptions.rst | 2 +- doc/ref/filestore.rst | 7 +- doc/ref/i18n.rst | 8 +- doc/ref/models/fields.rst | 64 +++++++-------- doc/ref/models/models.rst | 84 +++++++++---------- doc/ref/pool.rst | 3 +- doc/ref/pyson.rst | 6 +- doc/ref/rpc.rst | 8 +- doc/ref/sendmail.rst | 13 +-- doc/ref/tests.rst | 26 +++--- doc/ref/transaction.rst | 10 +-- doc/ref/wizard.rst | 30 +++---- doc/topics/access_rights.rst | 12 +-- doc/topics/actions.rst | 10 +-- doc/topics/backend_types.rst | 76 +++++++++--------- doc/topics/configuration.rst | 138 ++++++++++++++++---------------- doc/topics/domain.rst | 2 +- doc/topics/models/index.rst | 2 +- doc/topics/modules/index.rst | 5 +- doc/topics/reports/index.rst | 18 ++--- doc/topics/rpc.rst | 4 +- doc/topics/setup_database.rst | 8 +- doc/topics/start_server.rst | 27 ++++--- doc/topics/task_queue.rst | 14 ++-- doc/topics/testing.rst | 24 +++--- doc/topics/triggers.rst | 6 +- doc/topics/user_application.rst | 44 +++++----- doc/topics/views/index.rst | 45 ++++++----- doc/topics/wizard.rst | 2 +- 31 files changed, 384 insertions(+), 374 deletions(-) diff --git a/doc/ref/bus.rst b/doc/ref/bus.rst index 7d2b38f201..0edb1746c3 100644 --- a/doc/ref/bus.rst +++ b/doc/ref/bus.rst @@ -7,8 +7,8 @@ Bus .. class:: Bus -The Tryton server listens on `POST` requests on the routes matching -`//bus` and replies with JSON dictionary containing: +The Tryton server listens on ``POST`` requests on the routes matching +``//bus`` and replies with JSON dictionary containing: channel The channel on which this message has been received. @@ -18,20 +18,20 @@ message of the message depends of its type. All messages should at least content a unique identifier in the key - `message_id` and their type in the key of the same name. + ``message_id`` and their type in the key of the same name. Client sending their request on the route must be authenticated. The request must submit a JSON dictionary containing: last_message A value identifying the last message received by the client. This value - can be `null`. + can be ``null``. channels A list of strings denoting the channels the client is listening to. -The :class:Bus exposes two methods that are used by the framework: `publish` -and `subscribe`. +The :class:Bus exposes two methods that are used by the framework: ``publish`` +and ``subscribe``. .. classmethod:: Bus.publish(channel, message) @@ -43,9 +43,9 @@ and `subscribe`. .. classmethod:: Bus.subscribe(database, channels[, last_message]) - Subscribe a user client to some `channels` of messages. + Subscribe a user client to some ``channels`` of messages. - The `message_id` parameter defines the last message ID received by the + The ``message_id`` parameter defines the last message ID received by the client. It defaults to None when not provided. The default implementation provides an helper method to construct the response: @@ -54,9 +54,9 @@ The default implementation provides an helper method to construct the response: Creates a dictionary suitable as a response from a message and a timestamp. - `channel` is the channel on which the message has been received. + ``channel`` is the channel on which the message has been received. - `message` is the content of the message sent to the client. + ``message`` is the content of the message sent to the client. Please note that the implementation relies on the fact that the order of the messages received is consistent accros different trytond instances allowing to @@ -65,22 +65,22 @@ dispatch the request to any trytond server running. Notification ------------ -Tryton provides a shortcut to send a notification with the `notify` method. +Tryton provides a shortcut to send a notification with the ``notify`` method. .. method:: notify(title[, body[, priority[, user[, client]]]]) Send a text message to a user's client to be displayed using a - notification popup. The meaning of `title`, `body` and `priority` is + notification popup. The meaning of ``title``, ``body`` and ``priority`` is defined in :ref:`bus_notification_spec`. - If `user` is not set, the current - :attr:`~trytond.transaction.Transaction.user` is used. Otherwise `user` is - the user ID to notify. + If ``user`` is not set, the current + :attr:`~trytond.transaction.Transaction.user` is used. Otherwise ``user`` + is the user ID to notify. - If `client` is not set then every client of the user will receive the - message. If `client` and `user` are not set, the system will send the + If ``client`` is not set then every client of the user will receive the + message. If ``client`` and ``user`` are not set, the system will send the notification to the current user client. Otherwise the notification will - be sent to the client whose ID matches `client`. + be sent to the client whose ID matches ``client``. .. _bus_notification_spec: diff --git a/doc/ref/cache.rst b/doc/ref/cache.rst index 66a01d865e..8a3e6b90fa 100644 --- a/doc/ref/cache.rst +++ b/doc/ref/cache.rst @@ -7,13 +7,13 @@ Cache .. class:: Cache(name[, size_limit[, duration[, context]]]) -The class is used to cache values between server requests. The `name` should be -unique and it's used to identify the cache. We usually use -`.` to make it unique. The `size_limit` parameter can -be used to limit the number of values cached and it has 1024 as the default -value. The `duration` parameter defines how long a cached value stays valid +The class is used to cache values between server requests. The ``name`` should +be unique and it's used to identify the cache. We usually use +``.`` to make it unique. The ``size_limit`` parameter +can be used to limit the number of values cached and it has 1024 as the default +value. The ``duration`` parameter defines how long a cached value stays valid but if it is not set the value remains valid until it is cleared. And the -`context` parameter is used to indicate if the cache depends on the user +``context`` parameter is used to indicate if the cache depends on the user context and is true by default. The cache is cleaned on :class:`Transaction` starts and resets on :class:`Transaction` commit or rollback. @@ -24,12 +24,12 @@ starts and resets on :class:`Transaction` commit or rollback. .. method:: get(key[, default]) -Retrieve the value of the key in the cache. If a `default` is specified it -will be returned when the key is missing otherwise it will return `None`. +Retrieve the value of the key in the cache. If a ``default`` is specified it +will be returned when the key is missing otherwise it will return ``None``. .. method:: set(key, value) -Sets the `value` of the `key` in the cache. +Sets the ``value`` of the ``key`` in the cache. .. method:: clear() @@ -41,7 +41,7 @@ Synchronize cache instances using transaction. .. method:: sync_since(value) -Return `True` if the last synchronization was done before `value`. +Return ``True`` if the last synchronization was done before ``value``. .. classmethod:: commit(transaction) @@ -53,10 +53,10 @@ Remove cache changes from transaction. .. staticmethod:: drop(dbname) -Drops all the caches for database `dbname` +Drops all the caches for database ``dbname`` .. note:: By default Tryton uses a MemoryCache, but this behaviour can be overridden by setting a fully qualified name of an alternative class defined in the - configuration `class` of the `cache` section. + configuration ``class`` of the ``cache`` section. .. diff --git a/doc/ref/exceptions.rst b/doc/ref/exceptions.rst index 7c599f5dc5..40e0dd8285 100644 --- a/doc/ref/exceptions.rst +++ b/doc/ref/exceptions.rst @@ -23,7 +23,7 @@ Exceptions .. exception:: LoginExceptions(name, message[, type]) - The exception used to request `name` parameter for the login process. + The exception used to request ``name`` parameter for the login process. .. exception:: ConcurrencyException(message) diff --git a/doc/ref/filestore.rst b/doc/ref/filestore.rst index c20bd02224..c9045d54bb 100644 --- a/doc/ref/filestore.rst +++ b/doc/ref/filestore.rst @@ -8,8 +8,9 @@ FileStore .. class:: FileStore() The class is used to store and retrieve files from the directory defined in the -configuration `path` of `database` section. It uses a two levels of directory -composed of the 2 chars of the file hash. It is an append only storage. +configuration ``path`` of ``database`` section. It uses a two levels of +directory composed of the 2 chars of the file hash. It is an append only +storage. .. method:: get(id[, prefix]) @@ -37,6 +38,6 @@ Store the sequence of data and return a list of identifiers. .. note:: The class can be overridden by setting a fully qualified name of a - alternative class defined in the configuration `class` of the `database` + alternative class defined in the configuration ``class`` of the ``database`` section. .. diff --git a/doc/ref/i18n.rst b/doc/ref/i18n.rst index 23f914ab8f..fcaa98c680 100644 --- a/doc/ref/i18n.rst +++ b/doc/ref/i18n.rst @@ -7,11 +7,11 @@ Internationalization .. method:: gettext(message_id, [language[, \**variables]]) - Returns the message translated into the `language`. - The `message_id` is the `XML` id for the `ir.message` that is to be - translated, and the `variables` keyword arguments are used as a mapping to + Returns the message translated into the ``language``. + The ``message_id`` is the ``XML`` id for the ``ir.message`` that is to be + translated, and the ``variables`` keyword arguments are used as a mapping to format the string. - If `language` is not set, then the :attr:`Transaction.language` is used. + If ``language`` is not set, then the :attr:`Transaction.language` is used. .. method:: lazy_gettext(message_id, [language[, \**variables]]) diff --git a/doc/ref/models/fields.rst b/doc/ref/models/fields.rst index e2ea743fab..47dcb0b134 100644 --- a/doc/ref/models/fields.rst +++ b/doc/ref/models/fields.rst @@ -171,10 +171,10 @@ Instance methods: .. method:: Field.sql_type() Return the namedtuple('SQLType', 'base type') which defines the SQL type to - use for creation and casting. Or `None` if the field is not stored in the + use for creation and casting. Or ``None`` if the field is not stored in the database. - sql_type is using the `_sql_type` attribute to compute its return value. + sql_type is using the ``_sql_type`` attribute to compute its return value. The backend is responsible for the computation. For the list of supported types by Tryton see @@ -190,7 +190,7 @@ Instance methods: .. method:: Field.set_rpc(model) - Adds to `model` the default RPC instances required by the field. + Adds to ``model`` the default RPC instances required by the field. .. method:: Field.definition(model, language) @@ -234,7 +234,7 @@ Depends .. method:: depends([\*fields[, methods]]) A decorator to define the field names on which the decorated method depends. -The `methods` argument can be used to duplicate the field names from other +The ``methods`` argument can be used to duplicate the field names from other decorated methods. This is useful if the decorated method calls another method. Field types @@ -334,7 +334,7 @@ instance. the integer part. The second integer defines the total of numbers in the decimal part. Integers can be replaced by a :class:`~trytond.pyson.PYSON` statement. - If digits is None or any values of the tuple is `None`, no validation on + If digits is None or any values of the tuple is ``None``, no validation on the numbers will be done. Numeric @@ -371,7 +371,7 @@ It is stored in `UTC`_ while displayed in the user timezone. .. attribute:: DateTime.format A string format as used by strftime. This format will be used to display - the time part of the field. The default value is `%H:%M:%S`. + the time part of the field. The default value is ``%H:%M:%S``. The value can be replaced by a :class:`~trytond.pyson.PYSON` statement. Timestamp @@ -415,7 +415,7 @@ A binary field. It will be represented in Python by a ``bytes`` instance. .. warning:: If the context contains a key composed of the model name and field name - separated by a dot and its value is the string `size` then the read value + separated by a dot and its value is the string ``size`` then the read value is the size instead of the content. :class:`Binary` has three extra optional arguments: @@ -429,9 +429,9 @@ A binary field. It will be represented in Python by a ``bytes`` instance. .. attribute:: Binary.file_id - Name of the field that holds the `FileStore` identifier. Default value is - `None` which means the data is stored in the database. The field must be on - the same table and accept `char` values. + Name of the field that holds the ``FileStore`` identifier. Default value is + ``None`` which means the data is stored in the database. The field must be + on the same table and accept ``char`` values. .. warning:: Switching from database to file-store is supported transparently. But @@ -440,8 +440,8 @@ A binary field. It will be represented in Python by a ``bytes`` instance. .. attribute:: Binary.store_prefix - The prefix to use with the `FileStore`. Default value is `None` which means - the database name is used. + The prefix to use with the ``FileStore``. Default value is ``None`` which + means the database name is used. Selection --------- @@ -769,7 +769,7 @@ Many2Many .. class:: Many2Many(relation_name, origin, target, string[, order[, datetime_field[, size[, search_order[, search_context[, \**options]]]]]]) A many-to-many relation field. It requires to have the opposite origin -:class:`Many2One` field or a:class:`Reference` field defined on the relation +:class:`Many2One` field or a :class:`Reference` field defined on the relation model and a :class:`Many2One` field pointing to the target. This field accepts as written value a list of tuples like the :class:`One2Many`. @@ -795,7 +795,7 @@ This field accepts as written value a list of tuples like the :class:`One2Many`. :class:`~trytond.model.ModelView`, like in a :class:`~trytond.wizard.Wizard`. For this, :attr:`~Many2Many.relation_name` is set to the target model and :attr:`~Many2Many.origin` and - :attr:`~Many2Many.target` are set to `None`. + :attr:`~Many2Many.target` are set to ``None``. .. :class:`Many2Many` has some extra optional arguments: @@ -879,7 +879,7 @@ Function .. class:: Function(field, getter[, setter[, searcher]]) -A function field can emulate any other given `field`. +A function field can emulate any other given ``field``. :class:`Function` has a required argument: @@ -891,21 +891,21 @@ A function field can emulate any other given `field`. getter(instances, name) - where `name` is the name of the field, and it must return a dictionary with - a value for each instance. + where ``name`` is the name of the field, and it must return a dictionary + with a value for each instance. Or the signature of the classmethod is:: getter(instances, names) - where `names` is a list of name fields, and it must return a dictionary + where ``names`` is a list of name fields, and it must return a dictionary containing for each names a dictionary with a value for each instance. The signature of the instancemethod is:: getter(name) - where `name` is the name of the field, and it must return the value. + where ``name`` is the name of the field, and it must return the value. :class:`Function` has some extra optional arguments: @@ -917,7 +917,7 @@ A function field can emulate any other given `field`. setter(instances, name, value) - where `name` is the name of the field and `value` the value to set. + where ``name`` is the name of the field and ``value`` the value to set. .. warning:: The modifications made to instances will not be saved automatically. @@ -930,7 +930,7 @@ A function field can emulate any other given `field`. searcher(name, clause) - where `name` is the name of the field and `clause` is a + where ``name`` is the name of the field and ``clause`` is a :ref:`domain clause `. It must return a list of :ref:`domain ` clauses but the ``operand`` can be a SQL query. @@ -939,21 +939,21 @@ Instance methods: .. method:: Function.get(ids, model, name[, values]) - Call the :attr:`~Function.getter` classmethod where `model` is the - :class:`~trytond.model.Model` instance of the field, `name` is the name of + Call the :attr:`~Function.getter` classmethod where ``model`` is the + :class:`~trytond.model.Model` instance of the field, ``name`` is the name of the field. .. method:: Function.set(ids, model, name, value) - Call the :attr:`~Function.setter` classmethod where `model` is the - :class:`~trytond.model.Model` instance of the field, `name` is the name of - the field, `value` is the value to set. + Call the :attr:`~Function.setter` classmethod where ``model`` is the + :class:`~trytond.model.Model` instance of the field, ``name`` is the name of + the field, ``value`` is the value to set. .. method:: Function.search(model, name, clause) - Call the :attr:`~Function.searcher` classmethod where `model` is the - :class:`~trytond.model.Model` instance of the field, `name` is the name of - the field, `clause` is a clause of :ref:`domain `. + Call the :attr:`~Function.searcher` classmethod where ``model`` is the + :class:`~trytond.model.Model` instance of the field, ``name`` is the name of + the field, ``clause`` is a clause of :ref:`domain `. MultiValue ---------- @@ -1001,6 +1001,6 @@ Instance methods: .. method:: Dict.translated([name[, type_]]) - Returns a descriptor for the translated `values` or `keys` of the field - following `type_`. The descriptor must be used on the same class as the - field. Default `type_` is `values`. + Returns a descriptor for the translated ``values`` or ``keys`` of the field + following ``type_``. The descriptor must be used on the same class as the + field. Default ``type_`` is ``values``. diff --git a/doc/ref/models/models.rst b/doc/ref/models/models.rst index 246cfd3a8e..38d5b371d0 100644 --- a/doc/ref/models/models.rst +++ b/doc/ref/models/models.rst @@ -66,8 +66,8 @@ Class methods: Returns a dictionary with the default values for each field in ``fields_names``. Default values are defined by the returned value of each instance method with the pattern ``default_`field_name`()``. - ``with_rec_name`` allow to add `rec_name` value for each many2one field. - The `default_rec_name` key in the context can be used to define the value + ``with_rec_name`` allow to add ``rec_name`` value for each many2one field. + The ``default_rec_name`` key in the context can be used to define the value of the :attr:`Model._rec_name` field. .. classmethod:: Model.fields_get([fields_names[, level]]) @@ -78,7 +78,7 @@ Class methods: .. classmethod:: Model.__names__([field]) - Returns a dictionary with the name of the `model` and the `field`. + Returns a dictionary with the name of the ``model`` and the ``field``. It is a convenience-method used to format messages which should include those names. @@ -86,11 +86,11 @@ Instance methods: .. method:: Model.on_change(fieldnames) - Returns the list of changes by calling `on_change` method of each field. + Returns the list of changes by calling ``on_change`` method of each field. .. method:: Model.on_change_with(fieldnames) - Returns the new values of all fields by calling `on_change_with` method of + Returns the new values of all fields by calling ``on_change_with`` method of each field. .. method:: Model.pre_validate() @@ -121,7 +121,7 @@ Static methods: .. staticmethod:: ModelView.button_action(action) - Same as :meth:`ModelView.button` but return the action id of the XML `id` + Same as :meth:`ModelView.button` but return the action id of the XML ``id`` action or the action value updated by the returned value of the method. .. staticmethod:: ModelView.button_change([\*fields]) @@ -155,10 +155,10 @@ Class methods: .. classmethod:: ModelView.view_toolbar_get() Returns the model specific actions and exports in a dictionary with keys: - - `print`: a list of available reports - - `action`: a list of available actions - - `relate`: a list of available relations - - `exports`: a list of available exports + - ``print``: a list of available reports + - ``action``: a list of available actions + - ``relate``: a list of available relations + - ``exports``: a list of available exports .. classmethod:: ModelView.view_attributes() @@ -235,7 +235,7 @@ Class methods: of the fields as key and their values. ``fields_names`` can contain dereferenced fields from related models. Their values will be returned under the referencing field suffixed by a - `.`. The number of *dots* in the name is not limited. + ``.``. The number of *dots* in the name is not limited. The order of the returned list is not guaranteed. .. classmethod:: ModelStorage.write(records, values, [[records, values], ...]) @@ -277,7 +277,7 @@ Class methods: value. The keys of ``default`` may use the dotted notation for the - :class:`fields.One2Many` to define the default to pass to its `copy` + :class:`fields.One2Many` to define the default to pass to its ``copy`` operation. New records are returned following the input order. @@ -286,16 +286,16 @@ Class methods: Return a list of records that match the :ref:`domain `. - If `offset` or `limit` are set, the result starts at the offset and has the - length of the limit. + If ``offset`` or ``limit`` are set, the result starts at the offset and + has the length of the limit. - The `order` is a list of tuples defining the order of the result: + The ``order`` is a list of tuples defining the order of the result: [ ('field name', 'ASC'), ('other field name', 'DESC'), ... ] The first element of the tuple is a field name of the model and the second - is the sort ordering as `ASC` for ascending, `DESC` for descending or empty - for a default order. This second element may contain 'NULLS FIRST' or + is the sort ordering as ``ASC`` for ascending, ``DESC`` for descending or + empty for a default order. This second element may contain 'NULLS FIRST' or 'NULLS LAST' to sort null values before or after non-null values. If neither is specified the default behavior of the backend is used. @@ -304,7 +304,7 @@ Class methods: record. Or for a :class:`fields.Dict` field, the dotted notation is used to sort on the key's value. - If `count` is set to `True`, then the result is the number of records. + If ``count`` is set to ``True``, then the result is the number of records. .. classmethod:: ModelStorage.search_count(domain) @@ -370,8 +370,8 @@ Instance methods: .. method:: ModelStorage.resources() - Return a dictionary with the number of attachments (`attachment_count`), - notes (`note_count`) and unread note (`note_unread`). + Return a dictionary with the number of attachments (``attachment_count``), + notes (``note_count``) and unread note (``note_unread``). .. method:: ModelStorage.get_rec_name(name) @@ -396,7 +396,7 @@ Class attributes are: .. attribute:: ModelSQL._order - The default `order` parameter of :meth:`ModelStorage.search` method. + The default ``order`` parameter of :meth:`ModelStorage.search` method. .. attribute:: ModelSQL._order_name @@ -414,7 +414,7 @@ Class attributes are: [ ('constraint name', constraint, 'xml id'), ... ] - - `constraint name` is the name of the SQL constraint in the database + - ``constraint name`` is the name of the SQL constraint in the database - constraint is an instance of :class:`Constraint` @@ -470,8 +470,8 @@ Class methods: .. classmethod:: ModelSQL.search(domain[, offset[, limit[, order[, count[, query]]]]]) - Same as :meth:`ModelStorage.search` with the additional `query` argument. - If `query` is set to `True`, the the result is the SQL query. + Same as :meth:`ModelStorage.search` with the additional ``query`` argument. + If ``query`` is set to ``True``, the the result is the SQL query. .. classmethod:: ModelSQL.search_domain(domain[, active_test[, tables]]) @@ -542,7 +542,7 @@ Instance attributes: .. attribute:: Unique.operators - The tuple of `Equal` operators. + The tuple of ``Equal`` operators. Exclude ------- @@ -551,7 +551,7 @@ Exclude It represents an exclude :class:`Constraint` which guarantees that if any two rows are compared on the specified expression using the specified operator not -all of these comparisons will return `TRUE`. +all of these comparisons will return ``TRUE``. Instance attributes: @@ -656,7 +656,7 @@ Class attributes are: .. attribute:: DictSchemaMixin.digits The definition of the :class:`trytond.model.fields.Integer` field for the - digits number when the type is `float` or `numeric`. + digits number when the type is ``float`` or ``numeric``. .. attribute:: DictSchemaMixin.domain @@ -671,7 +671,7 @@ Class attributes are: .. attribute:: DictSchemaMixin.selection The definition of the :class:`trytond.model.fields.Text` field to store the - couple of key and label when the type is `selection`. + couple of key and label when the type is ``selection``. The format is a key/label separated by ":" per line. .. attribute:: DictSchemaMixin.selection_sorted @@ -701,7 +701,7 @@ Class methods: result of :meth:`Model.fields_get`. It is possible to disable this method (returns an empty dictionary) by - setting in the `dict` section of the configuration, the + setting in the ``dict`` section of the configuration, the :attr:`Model.__name__` to ``False``. Instance methods: @@ -725,7 +725,7 @@ Instance methods: .. method:: MatchMixin.match(pattern[, match_none]) - Return if the instance match the pattern. If `match_none` is set `None` + Return if the instance match the pattern. If ``match_none`` is set ``None`` value of the instance will be compared. ========== @@ -777,7 +777,7 @@ Instance methods: Return a symbol and its position. The position indicates whether the symbol should appear before (0) or after (1) the value. If no symbol parameter is supplied then the mixin uses the - value of attribute named `symbol`. + value of attribute named ``symbol``. ================ sequence_ordered @@ -787,9 +787,9 @@ sequence_ordered Retuns a mixin_ class which defines the order of a :class:`ModelSQL` with an :class:`trytond.model.fields.Integer` field. field_name indicates the name of -the field to be created and its default values is `sequence`. field_label -defines the label which will be used by the field and defaults to `Sequence`. -Order specifies the order direction and defaults to `ASC NULLS FIRST`. +the field to be created and its default values is ``sequence``. field_label +defines the label which will be used by the field and defaults to ``Sequence``. +Order specifies the order direction and defaults to ``ASC NULLS FIRST``. =============== MultiValueMixin @@ -828,13 +828,13 @@ Instance methods: .. method:: MultiValueMixin.get_multivalue(name, \*\*pattern) - Return the value of the field `name` for the pattern. + Return the value of the field ``name`` for the pattern. .. method:: MultiValueMixin.set_multivalue(name, value[, save], \*\*pattern) - Store the value of the field `name` for the pattern. - If `save` is true, it will be stored in the database, otherwise the - modified :class:`ValueMixin` records are returned unsaved. `save` is true + Store the value of the field ``name`` for the pattern. + If ``save`` is true, it will be stored in the database, otherwise the + modified :class:`ValueMixin` records are returned unsaved. ``save`` is true by default. .. warning:: @@ -876,10 +876,10 @@ tree .. method:: tree([parent[, name[, separator]]]) -Returns a mixin_ class :class:`TreeMixin`. `parent` indicates the name of the -field that defines the parent of the tree and its default value is `parent`. -`name` indicates the name of the field that defines the name of the record and -its default value is `name`. If `separator` is set, the +Returns a mixin_ class :class:`TreeMixin`. ``parent`` indicates the name of the +field that defines the parent of the tree and its default value is ``parent``. +``name`` indicates the name of the field that defines the name of the record and +its default value is ``name``. If ``separator`` is set, the :meth:`ModelStorage.get_rec_name` constructs the name by concatenating each parent names using it as separator and :meth:`ModelStorage.search_rec_name` is adapted to search across the tree. diff --git a/doc/ref/pool.rst b/doc/ref/pool.rst index e9f35efe4f..33c82970aa 100644 --- a/doc/ref/pool.rst +++ b/doc/ref/pool.rst @@ -13,7 +13,8 @@ Static methods: .. staticmethod:: Pool.register(klass, ..., type_, module[, depends]) - Register the classes of type (`model`, `report` or `wizard`) for the module. + Register the classes of type (``model``, ``report`` or ``wizard``) for the + module. If ``depends`` is set, the registration happens only if all the modules are activated. diff --git a/doc/ref/pyson.rst b/doc/ref/pyson.rst index d844a416bf..505fec3ec2 100644 --- a/doc/ref/pyson.rst +++ b/doc/ref/pyson.rst @@ -137,7 +137,7 @@ true, then returns also true when both values of statements named by ``statement1`` and ``statement2`` are equal. In this case :class:`Greater` works as a *greater-than or equal* operator. -.. note:: `None` value is replaced by `0` for the comparison. +.. note:: ``None`` value is replaced by ``0`` for the comparison. .. class:: Less(statement1, statement2[, equal]) @@ -150,7 +150,7 @@ then returns also true when both values of the statements named by ``statement1`` and ``statement2`` are equal. In this case :class:`Less` works as a *less-than or equal* operator. -.. note:: `None` value is replaced by `0` for the comparison. +.. note:: ``None`` value is replaced by ``0`` for the comparison. .. class:: If(condition, then_statement, else_statement) @@ -280,4 +280,4 @@ dictionary, list or string. Returns the number of items in ``value``. An :class:`Id` object represents the PYSON ``Id()`` statement for filesystem id evaluations. When converted into the internal dictionary, it returns the -database id stored in `ir.model.data`. +database id stored in ``ir.model.data``. diff --git a/doc/ref/rpc.rst b/doc/ref/rpc.rst index 6d13156441..93fde018fc 100644 --- a/doc/ref/rpc.rst +++ b/doc/ref/rpc.rst @@ -25,16 +25,16 @@ Instance attributes are: .. attribute:: RPC.check_access - Set `_check_access` in the context to activate the access right on model - and field. Default is `True`. + Set ``_check_access`` in the context to activate the access right on model + and field. Default is ``True``. .. attribute:: RPC.unique - If set, it ensures the instantiated records are unique. Default is `True`. + If set, it ensures the instantiated records are unique. Default is ``True``. .. attribute:: RPC.fresh_session - If set, it requires a fresh session. Default is `False`. + If set, it requires a fresh session. Default is ``False``. .. attribute:: RPC.cache diff --git a/doc/ref/sendmail.rst b/doc/ref/sendmail.rst index 35e760b86f..13755ed29b 100644 --- a/doc/ref/sendmail.rst +++ b/doc/ref/sendmail.rst @@ -27,17 +27,18 @@ The caller may pass a server instance from `smtplib`_. .. method:: get_smtp_server([uri[, strict]]) -Return a SMTP instance from `smtplib`_ using the `uri` or the one defined in -the `email` section of the :ref:`configuration `. -If strict is `True`, an exception is raised if it is not possible to connect to -the server. +Return a SMTP instance from `smtplib`_ using the ``uri`` or the one defined in +the ``email`` section of the :ref:`configuration `. +If strict is ``True``, an exception is raised if it is not possible to connect +to the server. .. class:: SMTPDataManager([uri[, strict]]) A :class:`SMTPDataManager` implements a data manager which send queued email at -commit. An option optional `uri` can be passed to configure the SMTP connection. -If strict is `True`, the data manager prevents the transaction if it fails to +commit. An option optional ``uri`` can be passed to configure the SMTP +connection. +If strict is ``True``, the data manager prevents the transaction if it fails to send the emails. .. method:: SMTPDataManager.put(from_addr, to_addrs, msg) diff --git a/doc/ref/tests.rst b/doc/ref/tests.rst index 5e3313fc9c..c1c5fd719e 100644 --- a/doc/ref/tests.rst +++ b/doc/ref/tests.rst @@ -20,10 +20,11 @@ Test .. function:: activate_module(name) -Activates the module `name` for the tested database. +Activates the module ``name`` for the tested database. -In case database does not exist and the `DB_CACHE` environment variable is set -then Tryton will restore a backup found in the directory pointed by `DB_CACHE`. +In case database does not exist and the ``DB_CACHE`` environment variable is +set then Tryton will restore a backup found in the directory pointed by +``DB_CACHE``. Otherwise it will proceed to the creation of the database and the activation of the module. @@ -37,7 +38,7 @@ A subclass of `unittest.TestCase`_ that tests a Tryton module. Some tests are included to ensure that the module works properly. This class creates a temporary database with the module activated in -`setUpClass`_ and drops it in the `tearDownClass` method. +`setUpClass`_ and drops it in the ``tearDownClass`` method. .. attribute:: ModuleTestCase.module @@ -63,19 +64,19 @@ doctest helpers A function that prepares the run of the `doctest`_ by creating a database and dropping it beforehand if necessary. This function should be used as the -`setUp` parameter +``setUp`` parameter .. deprecated:: - The `doctest_setup` function should not be used anymore to set up - `DocFileSuite`. New modules should use :func:`activate_modules` instead. + The ``doctest_setup`` function should not be used anymore to set up + ``DocFileSuite``. New modules should use :func:`activate_modules` instead. .. _doctest: https://docs.python.org/library/doctest.html .. function:: doctest_teardown() A function that cleans up after the run of the doctest by dropping the -database. It should be used as `tearDown` parameter when creating a -`DocFileSuite`. +database. It should be used as ``tearDown`` parameter when creating a +``DocFileSuite``. .. attribute:: doctest_checker @@ -83,7 +84,7 @@ database. It should be used as `tearDown` parameter when creating a .. function:: suite() -A function returning a subclass of `unittest.TestSuite` that will drop the +A function returning a subclass of ``unittest.TestSuite`` that will drop the database if it does not exist prior to the run of the tests. .. module:: trytond.tests.tools @@ -94,9 +95,10 @@ Tests tools .. function:: activate_modules(modules) -This function is used in proteus doctests to activate a list of `modules` in +This function is used in proteus doctests to activate a list of ``modules`` in the scenario. .. function:: set_user(user, config) -This function will set the user of the `config` proteus connection to `user`. +This function will set the user of the ``config`` proteus connection to +``user``. diff --git a/doc/ref/transaction.rst b/doc/ref/transaction.rst index 29f7a446c4..1a234e56cf 100644 --- a/doc/ref/transaction.rst +++ b/doc/ref/transaction.rst @@ -58,7 +58,7 @@ commited. .. method:: Transaction.start(database_name, user[, readonly[, context[, close[, autocommit]]]]) Start a new transaction and return a `context manager`_. The non-readonly - transaction will be committed when exiting the `with` statement without + transaction will be committed when exiting the ``with`` statement without exception. The other cases will be rollbacked. .. method:: Transaction.stop([commit]) @@ -71,18 +71,18 @@ commited. .. method:: Transaction.set_context(context, \**kwargs) Update the transaction context and return a `context manager`_. The context - will be restored when exiting the `with` statement. + will be restored when exiting the ``with`` statement. .. method:: Transaction.reset_context() Clear the transaction context and return a `context manager`_. The context - will be restored when exiting the `with` statement. + will be restored when exiting the ``with`` statement. .. method:: Transaction.set_user(user[, set_context]) Modify the user of the transaction and return a `context manager`_. - `set_context` will put the previous user id in the context to simulate the - record rules. The user will be restored when exiting the `with` statement. + ``set_context`` will put the previous user id in the context to simulate the + record rules. The user will be restored when exiting the ``with`` statement. .. method:: Transaction.set_current_transaction(transaction) diff --git a/doc/ref/wizard.rst b/doc/ref/wizard.rst index ef04c089ac..c252815a5d 100644 --- a/doc/ref/wizard.rst +++ b/doc/ref/wizard.rst @@ -86,10 +86,10 @@ Class methods are: .. classmethod:: Wizard.execute(session_id, data, state_name) Execute the wizard for the state. - `session_id` is a session id. - `data` is a dictionary with the session data to update. - `active_id`, `active_ids`, `active_model` and `action_id` must be set in - the context according to the records on which the wizard is run. + ``session_id`` is a session id. + ``data`` is a dictionary with the session data to update. + ``active_id``, ``active_ids``, ``active_model`` and ``action_id`` must be + set in the context according to the records on which the wizard is run. ===== State @@ -113,9 +113,9 @@ StateView A :class:`StateView` is a state that will display a form in the client. The form is defined by the :class:`~trytond.model.ModelView` with the name - `model_name`, the `XML` id in `view` and the `buttons`. + ``model_name``, the ``XML`` id in ``view`` and the ``buttons``. The default value of the view can be set with a method on wizard having the - same name as the state but starting with `default_`. + same name as the state but starting with ``default_``. Instance attributes are: @@ -125,7 +125,7 @@ Instance attributes are: .. attribute:: StateView.view - The `XML` id of the form view. + The ``XML`` id of the form view. .. attribute:: StateView.buttons @@ -162,8 +162,9 @@ StateTransition .. class:: StateTransition() - A :class:`StateTransition` brings the wizard to the `state` returned by the - method having the same name as the state but starting with `transition_`. + A :class:`StateTransition` brings the wizard to the ``state`` returned by + the method having the same name as the state but starting with + ``transition_``. =========== StateAction @@ -172,20 +173,21 @@ StateAction .. class:: StateAction(action_id) A :class:`StateAction` is a :class:`StateTransition` which let the client - launch an `ir.action`. This action definition can be customized with a - method on wizard having the same name as the state but starting with `do_`. + launch an ``ir.action``. This action definition can be customized with a + method on wizard having the same name as the state but starting with + ``do_``. Instance attributes are: .. attribute:: StateAction.action_id - The `XML` id of the `ir.action`. + The ``XML`` id of the ``ir.action``. Instance methods are: .. method:: StateAction.get_action() - Returns the `ir.action` definition. + Returns the ``ir.action`` definition. =========== StateReport @@ -194,7 +196,7 @@ StateReport .. class:: StateReport(report_name) A :class:`StateReport` is a :class:`StateAction` which find the report - action by name instead of `XML` id. + action by name instead of ``XML`` id. ====== Button diff --git a/doc/topics/access_rights.rst b/doc/topics/access_rights.rst index b97448da87..cf19e46e2c 100644 --- a/doc/topics/access_rights.rst +++ b/doc/topics/access_rights.rst @@ -12,10 +12,10 @@ The access rights are checked if the :attr:`Transaction.context ` has the key ``_check_access`` set to ``True`` (set by default by :attr:`RPC.check_access `) and if the -:attr:`~trytond.transaction.Transaction.user` is not `root`. +:attr:`~trytond.transaction.Transaction.user` is not ``root``. .. warning:: - The record rules are always enforced regardless of the `_check_access` + The record rules are always enforced regardless of the ``_check_access`` value. Model @@ -59,7 +59,7 @@ for `Model`_ but are applied to :ref:`fields `. Button ====== -For each button of a model the records of `ir.model.button` define the list of +For each button of a model the records of ``ir.model.button`` define the list of groups that are allowed to call it. The user only needs to belong to one of the groups to be granted the permission to use it. @@ -74,7 +74,7 @@ The ``read`` permission to the model is always enforced. Button Rule ----------- -The `ir.model.button` can contain a list of rules which define how many +The ``ir.model.button`` can contain a list of rules which define how many different users must click on the button. Each rule, for which the condition is met, must be passed to actually trigger the action. The counter can be reset when another defined button is clicked. @@ -84,14 +84,14 @@ Record Rule The record rules are conditions that records must meet for the user to be granted permission to use them. -They are defined by records of `ir.rule.group` which contains: +They are defined by records of ``ir.rule.group`` which contains: - a model on which it applies - the permissions granted - a set of user groups to which the rule applies - a global flag to always enforce - a default flag to add to all users - - a list of `ir.rule` with a :ref:`domain ` to select the + - a list of ``ir.rule`` with a :ref:`domain ` to select the records to which the rule applies. A rule group matches a record if the record is validated by at least one of the diff --git a/doc/topics/actions.rst b/doc/topics/actions.rst index 2fc8bb9bc5..0e4143cba7 100644 --- a/doc/topics/actions.rst +++ b/doc/topics/actions.rst @@ -24,15 +24,15 @@ Keywords define where to display the action in the client. There are five places: - * Open tree (`tree_open`) + * Open tree (``tree_open``) - * Print form (`form_print`) + * Print form (``form_print``) - * Action form (`form_action`) + * Action form (``form_action``) - * Form relate (`form_relate`) + * Form relate (``form_relate``) - * Open Graph (`graph_open`) + * Open Graph (``graph_open``) Report ====== diff --git a/doc/topics/backend_types.rst b/doc/topics/backend_types.rst index 00d73e41be..067cfd510b 100644 --- a/doc/topics/backend_types.rst +++ b/doc/topics/backend_types.rst @@ -17,47 +17,47 @@ The columns are in the following order: .. _`SQL 92`: http://www.contrib.andrew.cmu.edu/~shadow/sql/sql1992.txt .. _`PostgreSQL type`: https://www.postgresql.org/docs/current/static/datatype.html -`None` will represent the `NULL` value and vice versa, it can be used as input -or output for any SQL type. +``None`` will represent the ``NULL`` value and vice versa, it can be used as +input or output for any SQL type. -+--------------------+----------------------+----------------------+ -| SQL Type | Python input type | Python output type | -+====================+======================+======================+ -| `BOOL` | bool | bool | -+--------------------+----------------------+----------------------+ -| `INTEGER` | int | int | -+--------------------+----------------------+----------------------+ -| `BIGINT` | int / long | int / long | -| | [#pyver_int]_ | [#pyver_int]_ | -+--------------------+----------------------+----------------------+ -| `FLOAT` | float / int / long | float | -| | [#pyver_int]_ | | -+--------------------+----------------------+----------------------+ -| `NUMERIC` | decimal.Decimal_ | decimal.Decimal_ | -+--------------------+----------------------+----------------------+ -| `VARCHAR` / | str / unicode | str / unicode | -| `VARCHAR(length)` | [#pyver_str]_ | [#pyver_str]_ | -+--------------------+----------------------+----------------------+ -| `TEXT` | str / unicode | str / unicode | -| | [#pyver_str]_ | [#pyver_str]_ | -+--------------------+----------------------+----------------------+ -| `TIMESTAMP` | datetime.datetime_ | datetime.datetime_ | -+--------------------+----------------------+----------------------+ -| `DATETIME` | datetime.datetime_ | datetime.datetime_ | -| | without microseconds | without microseconds | -| | [#utc_tz]_ | [#utc_tz]_ | -+--------------------+----------------------+----------------------+ -| `DATE` | datetime.date_ | datetime.date_ | -+--------------------+----------------------+----------------------+ -| `TIME` | datetime.time_ | datetime.time_ | -+--------------------+----------------------+----------------------+ -| `INTERVAL` | datetime.timedelta_ | datetime.timedelta_ | -+--------------------+----------------------+----------------------+ -| `BLOB` | bytes | bytes | -+--------------------+----------------------+----------------------+ ++----------------------+----------------------+----------------------+ +| SQL Type | Python input type | Python output type | ++======================+======================+======================+ +| ``BOOL`` | bool | bool | ++----------------------+----------------------+----------------------+ +| ``INTEGER`` | int | int | ++----------------------+----------------------+----------------------+ +| ``BIGINT`` | int / long | int / long | +| | [#pyver_int]_ | [#pyver_int]_ | ++----------------------+----------------------+----------------------+ +| ``FLOAT`` | float / int / long | float | +| | [#pyver_int]_ | | ++----------------------+----------------------+----------------------+ +| ``NUMERIC`` | decimal.Decimal_ | decimal.Decimal_ | ++----------------------+----------------------+----------------------+ +| ``VARCHAR`` / | str / unicode | str / unicode | +| ``VARCHAR(length)`` | [#pyver_str]_ | [#pyver_str]_ | ++----------------------+----------------------+----------------------+ +| ``TEXT`` | str / unicode | str / unicode | +| | [#pyver_str]_ | [#pyver_str]_ | ++----------------------+----------------------+----------------------+ +| ``TIMESTAMP`` | datetime.datetime_ | datetime.datetime_ | ++----------------------+----------------------+----------------------+ +| ``DATETIME`` | datetime.datetime_ | datetime.datetime_ | +| | without microseconds | without microseconds | +| | [#utc_tz]_ | [#utc_tz]_ | ++----------------------+----------------------+----------------------+ +| ``DATE`` | datetime.date_ | datetime.date_ | ++----------------------+----------------------+----------------------+ +| ``TIME`` | datetime.time_ | datetime.time_ | ++----------------------+----------------------+----------------------+ +| ``INTERVAL`` | datetime.timedelta_ | datetime.timedelta_ | ++----------------------+----------------------+----------------------+ +| ``BLOB`` | bytes | bytes | ++----------------------+----------------------+----------------------+ .. [#pyver_int] in python 2 integers over *sys.maxint* are represented by the - `long` type + ``long`` type .. [#pyver_str] str when using python 3 ; unicode when using python 2 .. [#utc_tz] Datetime objects are not localized to any timezone diff --git a/doc/topics/configuration.rst b/doc/topics/configuration.rst index 9b62075071..545e1ec910 100644 --- a/doc/topics/configuration.rst +++ b/doc/topics/configuration.rst @@ -6,7 +6,7 @@ Configuration file for Tryton The configuration file controls some aspects of the behavior of Tryton. The file uses a simple ini-file format. It consists of sections, led by a -`[section]` header and followed by `name = value` entries: +``[section]`` header and followed by ``name = value`` entries: .. highlight:: ini @@ -21,7 +21,7 @@ For more information see ConfigParser_. .. _ConfigParser: http://docs.python.org/2/library/configparser.html The default value of any option can be changed using environment variables -with names using this syntax: `TRYTOND_
__`. +with names using this syntax: ``TRYTOND_
__``. Sections ======== @@ -43,7 +43,7 @@ listen Defines the couple of host (or IP address) and port number separated by a colon to listen on. -Default `localhost:8000` +Default ``localhost:8000`` hostname ~~~~~~~~ @@ -54,14 +54,14 @@ context available, for example during a cron job. root ~~~~ -Defines the root path served by `GET` requests. +Defines the root path served by ``GET`` requests. -Default: Under the `www` directory of user's home running `trytond`. +Default: Under the ``www`` directory of user's home running ``trytond``. num_proxies ~~~~~~~~~~~ -The number of proxy servers in front of `trytond`. +The number of proxy servers in front of ``trytond``. Default: 0 @@ -91,45 +91,45 @@ The typical form is: database://username:password@host:port/ -Default: The value of the environment variable `TRYTOND_DATABASE_URI` or -`sqlite://` if not set. +Default: The value of the environment variable ``TRYTOND_DATABASE_URI`` or +``sqlite://`` if not set. The available databases are: PostgreSQL ********** -`pyscopg2` supports two type of connections: +``pyscopg2`` supports two type of connections: - - TCP/IP connection: `postgresql://user:password@localhost:5432/` - - Unix domain connection: `postgresql://username:password@/` + - TCP/IP connection: ``postgresql://user:password@localhost:5432/`` + - Unix domain connection: ``postgresql://username:password@/`` SQLite ****** -The only possible URI is: `sqlite://` +The only possible URI is: ``sqlite://`` path ~~~~ -The directory where Tryton stores files and so the user running `trytond` +The directory where Tryton stores files and so the user running ``trytond`` must have write access on this directory. -Default: The `db` folder under the user home directory running `trytond`. +Default: The ``db`` folder under the user home directory running ``trytond``. list ~~~~ A boolean value to list available databases. -Default: `True` +Default: ``True`` retry ~~~~~ The number of retries when a database operational error occurs during a request. -Default: `5` +Default: ``5`` language ~~~~~~~~ @@ -137,13 +137,13 @@ language The main language of the database that will be used for storage in the main table for translations. -Default: `en` +Default: ``en`` default_name ~~~~~~~~~~~~ The name of the database to use for operations without a database name. -Default: `template1` for PostgreSQL, `:memory:` for SQLite. +Default: ``template1`` for PostgreSQL, ``:memory:`` for SQLite. request ------- @@ -173,23 +173,23 @@ model The number of different model kept in the cache per transaction. -Default: `200` +Default: ``200`` record ~~~~~~ The number of record loaded kept in the cache of the list. -It can be changed locally using the `_record_cache_size` key in +It can be changed locally using the ``_record_cache_size`` key in :attr:`Transaction.context`. -Default: `2000` +Default: ``2000`` field ~~~~~ -The number of field to load with an `eager` :attr:`Field.loading`. +The number of field to load with an ``eager`` :attr:`Field.loading`. -Default: `100` +Default: ``100`` clean_timeout ~~~~~~~~~~~~~ @@ -198,7 +198,7 @@ The minimum number of seconds between two cleanings of the cache. If the value is 0, the notification between processes will be done using channels if the back-end supports them. -Default: `300` +Default: ``300`` queue ----- @@ -209,14 +209,14 @@ worker Activate asynchronous processing of the tasks. Otherwise they are performed at the end of the requests. -Default: `False` +Default: ``False`` clean_days ~~~~~~~~~~ The number of days after which processed tasks are removed. -Default: `30` +Default: ``30`` table ----- @@ -250,7 +250,7 @@ The path to the certificate. email ----- -.. note:: Email settings can be tested with the `trytond-admin` command +.. note:: Email settings can be tested with the ``trytond-admin`` command uri ~~~ @@ -259,25 +259,25 @@ The SMTP-URL_ to connect to the SMTP server which is extended to support SSL_ and STARTTLS_. The available protocols are: - - `smtp`: simple SMTP - - `smtp+tls`: SMTP with STARTTLS - - `smtps`: SMTP with SSL + - ``smtp``: simple SMTP + - ``smtp+tls``: SMTP with STARTTLS + - ``smtps``: SMTP with SSL The uri accepts the following additional parameters: -* `local_hostname`: used as FQDN of the local host in the HELO/EHLO commands, - if omited it will use the value of `socket.getfqdn()`. -* `timeout`: A number of seconds used as timeout for blocking operations. A - `socket.timeout` will be raised when exceeded. If omited the default timeout +* ``local_hostname``: used as FQDN of the local host in the HELO/EHLO commands, + if omited it will use the value of ``socket.getfqdn()``. +* ``timeout``: A number of seconds used as timeout for blocking operations. A + ``socket.timeout`` will be raised when exceeded. If omited the default timeout will be used. -Default: `smtp://localhost:25` +Default: ``smtp://localhost:25`` from ~~~~ -Defines the default `From` address (using RFC-822_) for emails sent by Tryton. +Defines the default ``From`` address (using RFC-822_) for emails sent by Tryton. For example:: @@ -292,50 +292,50 @@ authentications A comma separated list of the authentication methods to try when attempting to verify a user's identity. Each method is tried in turn, following the order of the list, until one succeeds. In order to allow `multi-factor authentication`_, -individual methods can be combined together using a plus (`+`) symbol. +individual methods can be combined together using a plus (``+``) symbol. Example:: authentications = password+sms,ldap -By default, Tryton only supports the `password` method. This method compares +By default, Tryton only supports the ``password`` method. This method compares the password entered by the user against a stored hash of the user's password. Other modules can define additional authentication methods, please refer to their documentation for more information. -Default: `password` +Default: ``password`` max_age ~~~~~~~ The time in seconds that a session stay valid. -Default: `2592000` (30 days) +Default: ``2592000`` (30 days) timeout ~~~~~~~ The time in seconds without activity before the session is no more fresh. -Default: `300` (5 minutes) +Default: ``300`` (5 minutes) max_attempt ~~~~~~~~~~~ The maximum authentication attempt before the server answers unconditionally -`Too Many Requests` for any other attempts. The counting is done on all -attempts over a period of `timeout`. +``Too Many Requests`` for any other attempts. The counting is done on all +attempts over a period of ``timeout``. -Default: `5` +Default: ``5`` max_attempt_ip_network ~~~~~~~~~~~~~~~~~~~~~~ The maximum authentication attempt from the same network before the server -answers unconditionally `Too Many Requests` for any other attempts. The -counting is done on all attempts over a period of `timeout`. +answers unconditionally ``Too Many Requests`` for any other attempts. The +counting is done on all attempts over a period of ``timeout``. -Default: `300` +Default: ``300`` ip_network_4 ~~~~~~~~~~~~ @@ -343,7 +343,7 @@ ip_network_4 The network prefix to apply on IPv4 address for counting the authentication attempts. -Default: `32` +Default: ``32`` ip_network_6 ~~~~~~~~~~~~ @@ -351,7 +351,7 @@ ip_network_6 The network prefix to apply on IPv6 address for counting the authentication attempts. -Default: `56` +Default: ``56`` password -------- @@ -361,7 +361,7 @@ length The minimal length required for the user password. -Default: `8` +Default: ``8`` forbidden ~~~~~~~~~ @@ -373,23 +373,23 @@ entropy The ratio of non repeated characters for the user password. -Default: `0.75` +Default: ``0.75`` reset_timeout ~~~~~~~~~~~~~ The time in seconds until the reset password expires. -Default: `86400` (24h) +Default: ``86400`` (24h) passlib ~~~~~~~ The path to the `INI file to load as CryptContext `_. -If not path is set, Tryton will use the schemes `bcrypt` or `pbkdf2_sha512`. +If not path is set, Tryton will use the schemes ``bcrypt`` or ``pbkdf2_sha512``. -Default: `None` +Default: ``None`` attachment ---------- @@ -401,14 +401,14 @@ filestore A boolean value to store attachment in the :ref:`FileStore `. -Default: `True` +Default: ``True`` store_prefix ~~~~~~~~~~~~ -The prefix to use with the `FileStore`. +The prefix to use with the ``FileStore``. -Default: `None` +Default: ``None`` bus --- @@ -418,7 +418,7 @@ allow_subscribe A boolean value to allow clients to subscribe to bus channels. -Default: `False` +Default: ``False`` url_host ~~~~~~~~ @@ -431,7 +431,7 @@ long_polling_timeout The time in seconds to keep the connection to the client opened when using long polling for bus messages -Default: `300` +Default: ``300`` cache_timeout ~~~~~~~~~~~~~ @@ -439,14 +439,14 @@ cache_timeout The number of seconds a message should be kept by the queue before being discarded. -Default: `300` +Default: ``300`` select_timeout ~~~~~~~~~~~~~~ The timeout duration of the select call when listening on a channel. -Default: `5` +Default: ``5`` html ---- @@ -456,14 +456,14 @@ src The URL pointing to `TinyMCE `_ editor. -Default: `https://cloud.tinymce.com/stable/tinymce.min.js` +Default: ``https://cloud.tinymce.com/stable/tinymce.min.js`` plugins ~~~~~~~ The space separated list of TinyMCE plugins to load. It can be overridden for specific models and fields using the names: -`plugins--` or `plugins-`. +``plugins--`` or ``plugins-``. Default: `` @@ -472,25 +472,25 @@ css The JSON list of CSS files to load. It can be overridden for specific models and fields using the names: -`css--` or `css-`. +``css--`` or ``css-``. -Default: `[]` +Default: ``[]`` class ~~~~~ The class to add on the body. It can be overridden for specific models and fields using the names: -`class--` or `class-`. +``class--`` or ``class-``. -Default: `''` +Default: ``''`` wsgi middleware --------------- The section lists the `WSGI middleware`_ class to load. -Each middleware can be configured with a section named `wsgi ` -containing `args` and `kwargs` options. +Each middleware can be configured with a section named ``wsgi `` +containing ``args`` and ``kwargs`` options. Example:: diff --git a/doc/topics/domain.rst b/doc/topics/domain.rst index 9eee291149..096a3ddbad 100644 --- a/doc/topics/domain.rst +++ b/doc/topics/domain.rst @@ -50,7 +50,7 @@ by this pattern:: domain = [('attributes.color', '=', 'yellow')] .. warning:: - Order comparison of `date` and `datetime` types is not supported. + Order comparison of ``date`` and ``datetime`` types is not supported. ``operator`` Is an operator out of `Domain Operators`_ or a diff --git a/doc/topics/models/index.rst b/doc/topics/models/index.rst index 335f240c25..a643acab2c 100644 --- a/doc/topics/models/index.rst +++ b/doc/topics/models/index.rst @@ -35,7 +35,7 @@ fields:: name = fields.Char('Name') code = fields.Char('Code') -The class must be registered in the :ref:`Pool ` by the `register()` +The class must be registered in the :ref:`Pool ` by the ``register()`` method of the :ref:`module `. Model classes are essentially data mappers to records and Model instances are records. diff --git a/doc/topics/modules/index.rst b/doc/topics/modules/index.rst index d8486f4824..c34a1c511b 100644 --- a/doc/topics/modules/index.rst +++ b/doc/topics/modules/index.rst @@ -21,14 +21,15 @@ A module is a directory in trytond/modules which contains at least two files: -------------------- It is the Python ``__init__.py`` to define a module. It must contains a method -named `register()` that must register to the pool all the objects of the module. +named ``register()`` that must register to the pool all the objects of the +module. ``tryton.cfg`` file ------------------- It is a configuration file using the format of `ConfigParser`_ that must -contain `tryton` section with this following name: +contain ``tryton`` section with this following name: * ``version``: The version number of the module. diff --git a/doc/topics/reports/index.rst b/doc/topics/reports/index.rst index 5a6a612e2c..e854b4527f 100644 --- a/doc/topics/reports/index.rst +++ b/doc/topics/reports/index.rst @@ -36,12 +36,12 @@ Python API XML Description --------------- -When defining an `ir.action.report` the following attributes are available: +When defining an ``ir.action.report`` the following attributes are available: * ``name``: The name of the report. * ``report_name``: The name of the report model, for example - my_module.my_report. This is the name you would use with `Pool().get` + my_module.my_report. This is the name you would use with ``Pool().get`` * ``model``: If this report is of an existing model this is its name. For example my_module.my_model. Custom reports that aren't of a specific @@ -52,7 +52,7 @@ When defining an `ir.action.report` the following attributes are available: * ``template_extension``: The template format. - * ``single``: `True` if the template works only for one record. If such + * ``single``: ``True`` if the template works only for one record. If such report is called with more than one record, a zip file containing all the reports will be generated. @@ -135,18 +135,18 @@ Accessing models from within the report --------------------------------------- By default instances of the models the report is for are passed in to the -report via a list of objects called `records` (or `record` if `single` is -`True`). These records behave just as they would within trytond itself. You +report via a list of objects called ``records`` (or ``record`` if ``single`` is +``True``). These records behave just as they would within trytond itself. You can access any of the models relations as well. For example within the invoice report each object is an invoice and you can access the name of the party of -the invoice via `invoice.party.name`. Additional objects can be passed to a -report. This is discussed below in `Passing custom data to a report`. +the invoice via ``invoice.party.name``. Additional objects can be passed to a +report. This is discussed below in ``Passing custom data to a report``. Within Tryton the underlying model the report can be found by following the Menu to ``Administration > UI > Actions > Report``. Furthermore in tryton the fields for that model can be found by following the menu to ``Administration > Model > Model``. Model relation fields can be accessed to any depth, for -example, one could access `invoice.party.addresses` to get a list of addresses +example, one could access ``invoice.party.addresses`` to get a list of addresses for the party of an invoice. Creating a simple report template for a model from client @@ -213,7 +213,7 @@ And create the keyword for the new report: Passing custom data to a report ------------------------------- -In this example `Report.get_context` is overridden and an employee +In this example ``Report.get_context`` is overridden and an employee object is set into context. Now the invoice report will be able to access the employee object. diff --git a/doc/topics/rpc.rst b/doc/topics/rpc.rst index bbdacfc5e1..1ad8420cc7 100644 --- a/doc/topics/rpc.rst +++ b/doc/topics/rpc.rst @@ -16,7 +16,7 @@ common.db.login It takes as parameters: the user name and a dictionary of login parameters. It returns in case of success the user ID and the session. If the parameters are not valid to authenticate the user, it returns nothing. -Otherwise if it misses a key in the parameters, it raises a `LoginException` +Otherwise if it misses a key in the parameters, it raises a ``LoginException`` exception with the missing key name, type and the message to ask to the user. @@ -47,4 +47,4 @@ Session The authorization field is constructed by the username, the user ID and the session combined with a single colon and encoded in Base64. -The session is retrieved by calling the method `common.db.login`. +The session is retrieved by calling the method ``common.db.login``. diff --git a/doc/topics/setup_database.rst b/doc/topics/setup_database.rst index 9eb0adc6ac..dfe14406c2 100644 --- a/doc/topics/setup_database.rst +++ b/doc/topics/setup_database.rst @@ -11,9 +11,9 @@ Create a database ================= Depending of the database backend choosen, you must create a database (see the -documentation of the choosen backend). The user running `trytond` must be +documentation of the choosen backend). The user running ``trytond`` must be granted the priviledge to create tables. For backend that has the option, the -encoding of the database must be set to `UTF-8`. +encoding of the database must be set to ``UTF-8``. Initialize a database ===================== @@ -22,8 +22,8 @@ A database can be initialized using this command line:: trytond-admin -c -d --all -At the end of the process, `trytond-admin` will ask to set the password for the -`admin` user. +At the end of the process, ``trytond-admin`` will ask to set the password for +the ``admin`` user. Update a database ================= diff --git a/doc/topics/start_server.rst b/doc/topics/start_server.rst index 43f78f4629..b692d0c454 100644 --- a/doc/topics/start_server.rst +++ b/doc/topics/start_server.rst @@ -12,7 +12,7 @@ You can start the default web server bundled in Tryton with this command line:: trytond -c The server will wait for client connections on the interface defined in the -`web` section of the :ref:`configuration `. +``web`` section of the :ref:`configuration `. .. note:: When using multiple config files the order is importart as last entered files will override the items of first files @@ -21,15 +21,16 @@ WSGI server ----------- If you prefer to run Tryton inside your own WSGI server instead of the simple -server of Werkzeug, you can use the application `trytond.application.app`. +server of Werkzeug, you can use the application ``trytond.application.app``. Following environment variables can be set: - * `TRYTOND_CONFIG`: Point to :ref:`configuration ` file. - * `TRYTOND_LOGGING_CONFIG`: Point to :ref:`logging ` file. - * `TRYTOND_LOGGING_LEVEL`: An integer to set the default `logging level`_ - (default: `ERROR`). - * `TRYTOND_COROUTINE`: Use coroutine for concurrency. - * `TRYTOND_DATABASE_NAMES`: A list of database names in CSV format, using + * ``TRYTOND_CONFIG``: Point to :ref:`configuration ` + file. + * ``TRYTOND_LOGGING_CONFIG``: Point to :ref:`logging ` file. + * ``TRYTOND_LOGGING_LEVEL``: An integer to set the default `logging level`_ + (default: ``ERROR``). + * ``TRYTOND_COROUTINE``: Use coroutine for concurrency. + * ``TRYTOND_DATABASE_NAMES``: A list of database names in CSV format, using python default dialect. .. warning:: You must manage to serve the static files from the web root. @@ -42,7 +43,7 @@ Coroutine server The Werkzeug server uses thread for concurrency. This is not optimal for the long-polling request on the :ref:`bus ` as each client consumes permanently one thread. -You can start the server with coroutine using the option `--coroutine`. +You can start the server with coroutine using the option ``--coroutine``. Cron service ============ @@ -53,15 +54,15 @@ run the cron server with this command line:: trytond-cron -c -d The server will wake up every minutes and preform the scheduled actions defined -in the `database`. +in the ``database``. You can also launch the command every few minutes from a scheduler with the -option `--once`. +option ``--once``. Worker service ============== If you want to use a pool of workers to run :ref:`asynchronously some tasks -`, you must activate the worker in the `queue` section of +`, you must activate the worker in the ``queue`` section of the :ref:`configuration ` and run the worker manager with this command line:: @@ -72,4 +73,4 @@ The manager will dispatch tasks from the queue to a pool of worker processes. Services options ================ -You will find more options for those services by using `--help` arguments. +You will find more options for those services by using ``--help`` arguments. diff --git a/doc/topics/task_queue.rst b/doc/topics/task_queue.rst index e5ba11a9eb..8d78f3d416 100644 --- a/doc/topics/task_queue.rst +++ b/doc/topics/task_queue.rst @@ -5,7 +5,7 @@ Task Queue ========== Tryton provides a way to run asynchronously some tasks. You must activate the -worker in the `queue` section of the :ref:`configuration +worker in the ``queue`` section of the :ref:`configuration ` and :ref:`run the worker manager ` otherwise the tasks will be run at the end of the transaction. @@ -17,21 +17,21 @@ A task is the parameters that defines how to call a method from a The first argument of the method must be an instance or a list of instances of :class:`trytond.model.Model`. This other arguments must be JSON-ifiable. -A task is pushed into the `queue` by calling the desired method on the +A task is pushed into the ``queue`` by calling the desired method on the :attr:`trytond.model.Model.__queue__`. This stores in the queue all the current parameters of the call and it will be execute by a worker or at the end of the transaction if no worker is configured. The following :attr:`trytond.transaction.Transaction.context` keys are used as parameters for the queue: - - `queue_name`: The name of the queue. Default value is `default`. + - ``queue_name``: The name of the queue. Default value is ``default``. - - `queue_scheduled_at`: A `datetime.timedelta` to add to current time to - define when the task should be started. Default value is `None` which + - ``queue_scheduled_at``: A ``datetime.timedelta`` to add to current time + to define when the task should be started. Default value is ``None`` which means directly. - - `queue_expected_at`: A `datetime.timedelta` to add to current time to - define when the task should be finished. Default value is `None` which + - ``queue_expected_at``: A ``datetime.timedelta`` to add to current time to + define when the task should be finished. Default value is ``None`` which means as soon as possible. .. warning:: diff --git a/doc/topics/testing.rst b/doc/topics/testing.rst index 2f0a59b428..4a281c3be5 100644 --- a/doc/topics/testing.rst +++ b/doc/topics/testing.rst @@ -20,7 +20,7 @@ Unit tests Tryton provides the :class:`ModuleTestCase` class that bundles a set of tests that are useful for every module. -Unit tests in `ModuleTestCase` can be decorated with +Unit tests in ``ModuleTestCase`` can be decorated with :func:`trytond.tests.test_tryton.with_transaction` to run the test in a transaction. @@ -45,11 +45,11 @@ To use it in your own module you just have to inherit from Tests from this modules are found by the function -`trytond.modules.my_module.tests.suite` which must return a -`unittest.TestSuite` containing all the module's tests. This function is called -by the Tryton test runner script to gather all the tests. +``trytond.modules.my_module.tests.suite`` which must return a +``unittest.TestSuite`` containing all the module's tests. This function is +called by the Tryton test runner script to gather all the tests. -A typical `suite()` function thus looks like this: +A typical ``suite()`` function thus looks like this: .. highlight:: python @@ -71,7 +71,7 @@ A typical `suite()` function thus looks like this: Running your module's tests --------------------------- -Tryton provides the script `trytond/tests/run-tests.py`, just invoke it like +Tryton provides the script ``trytond/tests/run-tests.py``, just invoke it like that:: run-tests.py -m my_module @@ -85,18 +85,18 @@ Extending tests Python modules extending tryton core can define additional tests that should be added to the existing ones. -Those modules must create an entry point `trytond.tests`. Any file in the -module path specified by this entry point starting with `test_` and ending by -`.py` will be imported. Each of those file must define a `suite()` function -that returns a `unittest.TestSuite` that will be included in the trytond test -suite. If the module from the entry point defines a `register` function it +Those modules must create an entry point ``trytond.tests``. Any file in the +module path specified by this entry point starting with ``test_`` and ending by +``.py`` will be imported. Each of those file must define a ``suite()`` function +that returns a ``unittest.TestSuite`` that will be included in the trytond test +suite. If the module from the entry point defines a ``register`` function it will be called when registering the test-specific models in the :class:`trytond.pool.Pool`. Running trytond tests --------------------- -You should use the script `trytond/tests/run-tests.py` by invoking it like +You should use the script ``trytond/tests/run-tests.py`` by invoking it like that:: run-tests.py [-c configuration] diff --git a/doc/topics/triggers.rst b/doc/topics/triggers.rst index 271a7a581d..b895705707 100644 --- a/doc/topics/triggers.rst +++ b/doc/topics/triggers.rst @@ -17,10 +17,10 @@ The method signature is:: (cls, records, trigger) -Where `records` is the list of records that triggered the event and `trigger` -is the `ir.trigger` instance which is triggered. +Where ``records`` is the list of records that triggered the event and +``trigger`` is the ``ir.trigger`` instance which is triggered. -Triggers are defined by records of `ir.trigger`. Each record must define a +Triggers are defined by records of ``ir.trigger``. Each record must define a pyson condition which will be evaluated when the event occurs. Only those records for which the condition is evaluated to true will be processed by the trigger with the exception of modification triggers which will only process the diff --git a/doc/topics/user_application.rst b/doc/topics/user_application.rst index fdd7ea9c64..a0e1852450 100644 --- a/doc/topics/user_application.rst +++ b/doc/topics/user_application.rst @@ -5,9 +5,9 @@ User Application ================ Tryton provides a way to connect URL rules to an callable endpoint using the -decorator method `route` of the `trytond.application.app` instance. This allows -to define a custom API based on HTTP that can be used to create a specific user -application. +decorator method ``route`` of the ``trytond.application.app`` instance. This +allows you to define a custom API based on HTTP that can be used to create a +specific user application. The decorator takes as first parameter a string which follow the `Rule Format`_ of Werkzeug and as second parameter sequence of HTTP methods. @@ -24,50 +24,50 @@ Example:: The following converter is added by Tryton: - - `base64`: This converter accepts any Base64_ string and transforms it + - ``base64``: This converter accepts any Base64_ string and transforms it into its corresponding bytes value. .. _Base64: https://en.wikipedia.org/wiki/Base64 -Tryton also provides some wrappers in `trytond.protocols.wrappers` to ease the +Tryton also provides some wrappers in ``trytond.protocols.wrappers`` to ease the creation of such route. - - `set_max_request_size(size)`: change the default limit of the request to + - ``set_max_request_size(size)``: change the default limit of the request to the size in bytes. - - `with_pool`: which takes the first parameter as database name and + - ``with_pool``: which takes the first parameter as database name and replace it by the corresponding instance of the :ref:`Pool `. - - `with_transaction([readonly])`: which starts a :class:`Transaction` using - the :ref:`Pool ` from `with_pool`. If `readonly` is not set, - the transaction will not be readonly for `POST`, `PUT`, `DELETE` and - `PATCH` methods and readonly for all others. + - ``with_transaction([readonly])``: which starts a :class:`Transaction` + using the :ref:`Pool ` from ``with_pool``. If ``readonly`` is + not set, the transaction will not be readonly for ``POST``, ``PUT``, + ``DELETE`` and ``PATCH`` methods and readonly for all others. - - `user_application(name[, json])`: which set the :attr:`Transaction.user` - from the `Authorization` header using the type `bearer` and a valid key - for the named user application. + - ``user_application(name[, json])``: which set the + :attr:`Transaction.user` from the ``Authorization`` header using the + type ``bearer`` and a valid key for the named user application. User Application Key ==================== Tryton also provides a easy way to manage access to user application using keys per named application. -A key is created with a `POST` request on the `URL` -`//user/application/` which returns the key. The request must +A key is created with a ``POST`` request on the ``URL`` +``//user/application/`` which returns the key. The request must contain as data a json object with the keys: - - `user`: the user login + - ``user``: the user login - - `application`: the name of the application + - ``application``: the name of the application After the creation, the key must be validated by the user from the preferences of a Tryton client. -A key can be deleted with a `DELETE` request on the same `URL`. The request +A key can be deleted with a ``DELETE`` request on the same ``URL``. The request must contain as data a json object with the keys: - - `user`: the user login + - ``user``: the user login - - `key`: the key to delete + - ``key``: the key to delete - - `application`: the name of the application of the key + - ``application``: the name of the application of the key diff --git a/doc/topics/views/index.rst b/doc/topics/views/index.rst index 699fd0323a..65cf247281 100644 --- a/doc/topics/views/index.rst +++ b/doc/topics/views/index.rst @@ -8,13 +8,13 @@ The views are used to display records of an :class:`ModelView ` to the user. In Tryton, :class:`ModelView ` can have several views. -An `action` opens a window and defines which view to show. +An ``action`` opens a window and defines which view to show. -The views are built from XML that is stored in the `view` directory of the +The views are built from XML that is stored in the ``view`` directory of the module or in the databases thanks to the model ir.ui.view. So generally, they are defined in xml files with this kind of xml where name is -the name of the XML file in the `view` directory: +the name of the XML file in the ``view`` directory: .. highlight:: xml @@ -295,7 +295,7 @@ image Display an image. * ``name``: the image name or the field name which contains the image name. - The image name must be the name of a record of `ir.ui.icon`. + The image name must be the name of a record of ``ir.ui.icon``. * ``yexpand``: see in common-attributes-yexpand_. @@ -352,7 +352,7 @@ Display a button. ``button(cls, records)`` - The function may return an `ir.action` id or one of those client side + The function may return an ``ir.action`` id or one of those client side action keywords: .. _topics-views-client-actions: @@ -381,8 +381,8 @@ Display a button. * ``help``: see in common-attributes-help_. * ``keyword``: specify where will the button be displayed in the client - toolbar. The valid values are the keywords starting with `form_` from - :ref:`Actions ` without the `form_` part. + toolbar. The valid values are the keywords starting with ``form_`` from + :ref:`Actions ` without the ``form_`` part. .. warning:: @@ -395,10 +395,10 @@ Display a button. link ^^^^ -Display an `ir.action.act_window` as a button with a counter or one counter per -tab. When clicked it opens the window. +Display an ``ir.action.act_window`` as a button with a counter or one counter +per tab. When clicked it opens the window. - * ``name``: The XML id of `ir.action.act_window`. + * ``name``: The XML id of ``ir.action.act_window``. * ``colspan``: see in common-attributes-colspan_. @@ -406,8 +406,8 @@ tab. When clicked it opens the window. * ``icon``: The name of the icon to display. - * ``empty``: If set to `hide` the button is not displayed if the counter is - zero. The default is ``show``. + * ``empty``: If set to ``hide`` the button is not displayed if the counter + is zero. The default is ``show``. notebook ^^^^^^^^ @@ -538,9 +538,9 @@ trytond/ir/ui/tree.rng. There is also a RNC in trytond/ir/ui/tree.rnc. Tree view is used to display records inside a list or a tree. -It is a tree if there is a `field_childs` defined and this tree will -have drag and drop activated if the `field_childs` and the `parent -field` are defined in the view. +It is a tree if there is a ``field_childs`` defined and this tree will +have drag and drop activated if the ``field_childs`` and the ``parent +field`` are defined in the view. The columns of the view are put on the screen from left to right. @@ -842,7 +842,7 @@ The RNG that describes the xml for a calendar view is stored in trytond/ir/ui/calendar.rng. There is also a RNC in trytond/ir/ui/calendar.rnc. Calendar view is use to display records as events on a calendar based on a -`dtstart` and optionally a `dtend`. +``dtstart`` and optionally a ``dtend``. XML description --------------- @@ -857,21 +857,22 @@ Each calendar view must start with this tag. * ``dtend``: The name of the field that contains the end date. * ``mode``: An optional name for the view that will be used first. - Available views are: `day`, `week` and `month`. The default value is - `month`. + Available views are: ``day``, ``week`` and ``month``. The default value + is ``month``. * ``editable``: A boolean to specify if the calendar is editable. The - default value is `True`. + default value is ``True``. * ``color``: An optional field name that contains the text color for the - event. The default value is `black`. + event. The default value is ``black``. * ``background_color``: An optional field name that contains the background - color for the event. The default value is `lightblue`. + color for the event. The default value is ``lightblue``. * ``width``: The minimum width the calendar should request, use -1 to unset. - * ``height``: The minimum height the calendar should request, use -1 to unset. + * ``height``: The minimum height the calendar should request, use -1 to + unset. field ^^^^^ diff --git a/doc/topics/wizard.rst b/doc/topics/wizard.rst index 882daa944d..45612d28f0 100644 --- a/doc/topics/wizard.rst +++ b/doc/topics/wizard.rst @@ -5,7 +5,7 @@ Wizard ====== A wizard describes a series of steps defined as :class:`trytond.wizard.State`. -The wizard stores data in `ir.session.wizard` between states. +The wizard stores data in ``ir.session.wizard`` between states. The basics: