Improve documentation

issue11764
review433551003

.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:

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

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 <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>`.

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

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 <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*.

tryton.cfg

@@ -4,6 +4,7 @@ depends:
     account
     account_invoice
     account_product
+    company
     ir
     party
     product