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