From 14ad0b83f83ab12370fc43b6aef8aa73f2dff836 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Krier?= Date: Sun, 9 Oct 2022 18:53:45 +0200 Subject: [PATCH] Improve documentation issue11764 review433551003 --- .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(-) create mode 100644 doc/conf.py create mode 100644 doc/design.rst create mode 100644 doc/usage.rst diff --git a/.drone.yml b/.drone.yml index cb4fbecb4d..b45ef267ef 100644 --- a/.drone.yml +++ b/.drone.yml @@ -31,6 +31,14 @@ pipeline: - 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 --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000000..8513b72dd2 --- /dev/null +++ b/doc/conf.py @@ -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 --git a/doc/design.rst b/doc/design.rst new file mode 100644 index 0000000000..708b0c1ff2 --- /dev/null +++ b/doc/design.rst @@ -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 `. +An *Agent* can be either an agent or a principal of the `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 ` to sales based on criteria. + +.. _model-commission.plan: + +Plan +==== + +A *Plan* defines how the `Commission ` of an `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 ` can be generated using the +*Invoice* button. +The commissions invoiced together are grouped by `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 ` based on search criteria like the date +period or the `Agent `. + +.. _model.commission.reporting.agent: + +Commission Reporting Agent +========================== + +The *Commission Reporting Agent* sums the commission amounts per `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 ` concept is introduced by the + :doc:`Product Module `. + +.. _model-party.party: + +Party +===== + +The *Party* is extended to store its `Agent Selection +`. + +.. seealso:: + + The `Party ` concept is introduced by the + :doc:`Party Module `. + +.. _model-sale.sale: + +Sale +==== + +The *Sale* is extended to store an `Agent ` on the +header and `Principal ` on the lines. +Those values are copied to the generated `Invoice +`. + +When a `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 `. + +.. seealso:: + + The `Sale ` concept is introduced by the :doc:`Sale + Module `. + +.. _model-account.invoice: + +Invoice +======== + +The *Invoice* concept is extended to store an `Agent ` +on the header and `Principal ` on the lines. + +When the *Invoice* is posted the corresponding `Commissions ` +are created. +Its due date is set later depending on the commission method. + +.. seealso:: + + The `Invoice ` concept is introduced + by the :doc:`Account Invoice Module `. diff --git a/doc/index.rst b/doc/index.rst index 347520e6d0..051d74186c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -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 -***** +.. toctree:: + :maxdepth: 2 -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 -*************** - -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 --git a/doc/usage.rst b/doc/usage.rst new file mode 100644 index 0000000000..35de4b09fb --- /dev/null +++ b/doc/usage.rst @@ -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 ` always set +when selling to a specific *Customer*. +You can define the *Agent* on the `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 ` for each `Employee +`. +Then for each *Agent* opens the *Selections* related records and create an +`Agent Selection ` only filled with the +corresponding *Employee*. diff --git a/tryton.cfg b/tryton.cfg index ff40f742b5..03427b8e01 100644 --- a/tryton.cfg +++ b/tryton.cfg @@ -4,6 +4,7 @@ depends: account account_invoice account_product + company ir party product