changeset 50ceafecdc9b in modules/commission:default
details:
https://hg.tryton.org/modules/commission?cmd=changeset&node=50ceafecdc9b
description:
Improve documentation
issue11764
review433551003
diffstat:
.drone.yml | 8 ++
doc/conf.py | 61 ++++++++++++++++++++++
doc/design.rst | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
doc/index.rst | 37 ++-----------
doc/usage.rst | 24 ++++++++
tryton.cfg | 1 +
6 files changed, 253 insertions(+), 31 deletions(-)
diffs (327 lines):
diff -r 56bf8305bcf2 -r 50ceafecdc9b .drone.yml
--- a/.drone.yml Sun Oct 09 18:48:58 2022 +0200
+++ b/.drone.yml Sun Oct 09 18:53:45 2022 +0200
@@ -31,6 +31,14 @@
- twine check dist/*
volumes:
- cache:/root/.cache
+ check_doc:
+ image: ${IMAGE}
+ commands:
+ - pip install sphinx
+ - python -m sphinx -T -E -W -n -b html doc _build/html
+ - python -m sphinx -T -E -W -n -b linkcheck doc _build
+ volumes:
+ - cache:/root/.cache
services:
postgresql:
diff -r 56bf8305bcf2 -r 50ceafecdc9b doc/conf.py
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/conf.py Sun Oct 09 18:53:45 2022 +0200
@@ -0,0 +1,61 @@
+# This file is part of Tryton. The COPYRIGHT file at the top level of
+# this repository contains the full copyright notices and license terms.
+
+modules_url = 'https://docs.tryton.org/projects/modules-{module}/en/{series}/'
+trytond_url = 'https://docs.tryton.org/projects/server/en/{series}/'
+
+
+def get_info():
+ import configparser
+ import os
+ import subprocess
+ import sys
+
+ module_dir = os.path.dirname(os.path.dirname(__file__))
+
+ config = configparser.ConfigParser()
+ config.read_file(open(os.path.join(module_dir, 'tryton.cfg')))
+ info = dict(config.items('tryton'))
+
+ result = subprocess.run(
+ [sys.executable, 'setup.py', '--name'],
+ stdout=subprocess.PIPE, check=True, cwd=module_dir)
+ info['name'] = result.stdout.decode('utf-8').strip()
+
+ result = subprocess.run(
+ [sys.executable, 'setup.py', '--version'],
+ stdout=subprocess.PIPE, check=True, cwd=module_dir)
+ version = result.stdout.decode('utf-8').strip()
+ if 'dev' in version:
+ info['series'] = 'latest'
+ else:
+ info['series'] = '.'.join(version.split('.', 2)[:2])
+
+ for key in {'depends', 'extras_depend'}:
+ info[key] = info.get(key, '').strip().splitlines()
+ info['modules'] = set(info['depends'] + info['extras_depend'])
+ info['modules'] -= {'ir', 'res'}
+
+ return info
+
+
+info = get_info()
+
+master_doc = 'index'
+project = info['name']
+release = version = info['series']
+default_role = 'ref'
+highlight_language = 'none'
+extensions = [
+ 'sphinx.ext.intersphinx',
+ ]
+intersphinx_mapping = {
+ 'trytond': (trytond_url.format(series=version), None),
+ }
+intersphinx_mapping.update({
+ m: (modules_url.format(
+ module=m.replace('_', '-'), series=version), None)
+ for m in info['modules']
+ })
+
+del get_info, info, modules_url, trytond_url
diff -r 56bf8305bcf2 -r 50ceafecdc9b doc/design.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design.rst Sun Oct 09 18:53:45 2022 +0200
@@ -0,0 +1,153 @@
+******
+Design
+******
+
+The *Commission Module* introduces and extends the following concepts:
+
+.. _model-commission.agent:
+
+Agent
+=====
+
+An *Agent* links a party to a `Plan <model-commission.plan>`.
+An *Agent* can be either an agent or a principal of the `Company
+<company:model-company.company>`.
+
+.. seealso::
+
+ Agents are found by opening the main menu item:
+
+ |Commission --> Agents|__
+
+ .. |Commission --> Agents| replace:: :menuselection:`Commission -->
Agents`
+ __ https://demo.tryton.org/model/commission.agent
+
+.. _model-commission.agent.selection:
+
+Agent Selection
+================
+
+The *Agent Selection* contains a sets of rules to assign automatically an
+`Agent <model-commission.agent>` to sales based on criteria.
+
+.. _model-commission.plan:
+
+Plan
+====
+
+A *Plan* defines how the `Commission <model-commission>` of an `Agent
+<model-commission.agent>` is computed using a list of formula with criteria.
+
+.. seealso::
+
+ Plans are found by opening the main menu item:
+
+ |Commission -> Configuration --> Plans|__
+
+ .. |Commission -> Configuration --> Plans| replace::
:menuselection:`Commission -> Configuration --> Plans`
+ __ https://demo.tryton.org/model/commission.plan
+
+.. _model-commission:
+
+Commission
+==========
+
+The *Commission* concept is used to register the amount that is due to an agent
+or to receive from a principal.
+
+An `Invoice <account_invoice:model-account.invoice>` can be generated using the
+*Invoice* button.
+The commissions invoiced together are grouped by `Agent
+<model-commission.agent>`.
+
+.. seealso::
+
+ Commissions are found by opening the main menu item:
+
+ |Commission --> Commissions|__
+
+ .. |Commission --> Commissions| replace:: :menuselection:`Commission -->
Commissions`
+ __ https://demo.tryton.org/model/commission
+
+Wizards
+-------
+
+.. _wizard-commission.create_invoice:
+
+Create Commission Invoice
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *Create Commission Invoice* wizard helps the user to invoice all the
+pending `Commission <model-commission>` based on search criteria like the date
+period or the `Agent <model-commission.agent>`.
+
+.. _model.commission.reporting.agent:
+
+Commission Reporting Agent
+==========================
+
+The *Commission Reporting Agent* sums the commission amounts per `Agent
+<model-commission.agent>` for the selected period from the ``Context``.
+
+.. _concept-product:
+
+Product
+=======
+
+The *Product* concept is extended to store the principals who pay a commission
+when the product is sold.
+
+.. seealso::
+
+ The `Product <product:concept-product>` concept is introduced by the
+ :doc:`Product Module <product:index>`.
+
+.. _model-party.party:
+
+Party
+=====
+
+The *Party* is extended to store its `Agent Selection
+<model-commission.agent.selection>`.
+
+.. seealso::
+
+ The `Party <party:model-party.party>` concept is introduced by the
+ :doc:`Party Module <party:index>`.
+
+.. _model-sale.sale:
+
+Sale
+====
+
+The *Sale* is extended to store an `Agent <model-commission.agent>` on the
+header and `Principal <model-commission.agent>` on the lines.
+Those values are copied to the generated `Invoice
+<account_invoice:model-account.invoice>`.
+
+When a `Product <product:concept-product>` is selected, its principal is copied
+on the line.
+When the *Sale* is quoted and if there is no *Agent* filled, one is computed
+using the `Agent Selection <model-commission.agent.selection>`.
+
+.. seealso::
+
+ The `Sale <sale:model-sale.sale>` concept is introduced by the :doc:`Sale
+ Module <sale:index>`.
+
+.. _model-account.invoice:
+
+Invoice
+========
+
+The *Invoice* concept is extended to store an `Agent <model-commission.agent>`
+on the header and `Principal <model-commission.agent>` on the lines.
+
+When the *Invoice* is posted the corresponding `Commissions <model-commission>`
+are created.
+Its due date is set later depending on the commission method.
+
+.. seealso::
+
+ The `Invoice <account_invoice:model-account.invoice>` concept is introduced
+ by the :doc:`Account Invoice Module <account_invoice:index>`.
diff -r 56bf8305bcf2 -r 50ceafecdc9b doc/index.rst
--- a/doc/index.rst Sun Oct 09 18:48:58 2022 +0200
+++ b/doc/index.rst Sun Oct 09 18:53:45 2022 +0200
@@ -1,38 +1,13 @@
+#################
Commission Module
#################
-The commission module allows to manage commission for sale's agent.
+The *Commission Module* allows you to manage commission for sale's agent.
A commission move is created when posting the invoice, following the agent's
commission plan.
-Agent
-*****
-
-An agent links a party with a commission plan and method.
-
-- The *Plan* is the commission plan.
-- The *Account* is the payable account on which the commission will be
- credited.
-- The *Commission Method* defines when the commission will be due:
- - *On Posting*: when the invoice is posted.
- - *On Payment*: when the invoice is paid.
-
-Commission Plan
-***************
+.. toctree::
+ :maxdepth: 2
-A plan contains a sets of lines that defines the formula to use to compute the
-commission amount. The line is selected by choosing the first that matches the
-criteria.
-
-- The *Commission Product* is used to debit the commission using its expense
- account.
-
-Line
-----
-
-- The *Formula* is a Python expression that will be evaluated with `amount` as
- the invoiced amount.
-
-The criteria:
-
-- *Product*.
+ usage
+ design
diff -r 56bf8305bcf2 -r 50ceafecdc9b doc/usage.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage.rst Sun Oct 09 18:53:45 2022 +0200
@@ -0,0 +1,24 @@
+*****
+Usage
+*****
+
+.. _Setting automatically the agent when selling to a customer:
+
+Setting automatically the agent when selling to a customer
+==========================================================
+
+Sometimes you want to have the same `Agent <model-commission.agent>` always set
+when selling to a specific *Customer*.
+You can define the *Agent* on the `Party <party:model-party.party>` form for
+a period (or leave the dates empty for any period).
+
+.. _Rewarding employee salesman with commission:
+
+Rewarding employee salesman with commission
+===========================================
+
+You must create an `Agent <model-commission.agent>` for each `Employee
+<company:model-company.employee>`.
+Then for each *Agent* opens the *Selections* related records and create an
+`Agent Selection <model-commission.agent.selection>` only filled with the
+corresponding *Employee*.
diff -r 56bf8305bcf2 -r 50ceafecdc9b tryton.cfg
--- a/tryton.cfg Sun Oct 09 18:48:58 2022 +0200
+++ b/tryton.cfg Sun Oct 09 18:53:45 2022 +0200
@@ -4,6 +4,7 @@
account
account_invoice
account_product
+ company
ir
party
product
