Update documentation of sale_advance_payment

2025-11-22 18:10:08 +01:00
parent 9c783419cf
commit dcb06d6f7d
5 changed files with 81 additions and 44 deletions
@@ -32,6 +32,7 @@ Version 6.6.0 - 2022-10-31
 * Bug fixes (see mercurial logs for details)

 Version 6.4.0 - 2022-05-02
+--------------------------
 * Bug fixes (see mercurial logs for details)
 * Fill origin name of invoice line from condition
 * Add support for Python 3.10
@@ -39,34 +40,44 @@ Version 6.4.0 - 2022-05-02
 * Recall advance payment with negative quantity

 Version 6.2.0 - 2021-11-01
+--------------------------
 * Bug fixes (see mercurial logs for details)

 Version 6.0.0 - 2021-05-03
+--------------------------
 * Bug fixes (see mercurial logs for details)

 Version 5.8.0 - 2020-11-02
+--------------------------
 * Bug fixes (see mercurial logs for details)
 * Remove support for Python 3.5

 Version 5.6.0 - 2020-05-04
+--------------------------
 * Bug fixes (see mercurial logs for details)

 Version 5.4.0 - 2019-11-04
+--------------------------
 * Bug fixes (see mercurial logs for details)

 Version 5.2.0 - 2019-05-06
+--------------------------
 * Bug fixes (see mercurial logs for details)
 * Add unearned revenue on account type

 Version 5.0.0 - 2018-10-01
+--------------------------
 * Bug fixes (see mercurial logs for details)
 * Remove support for Python 2.7

 Version 4.8.0 - 2018-04-23
+--------------------------
 * Bug fixes (see mercurial logs for details)

 Version 4.6.0 - 2017-10-30
+--------------------------
 * Bug fixes (see mercurial logs for details)

 Version 4.4.0 - 2017-05-01
+--------------------------
 * Initial release
@@ -0,0 +1,51 @@
+******
+Design
+******
+
+The *Sale Advance Payment Module* introduces and extends the following
+concepts.
+
+.. _model-sale.advance_payment_term:
+
+Sale Advance Payment Term
+=========================
+
+The *Sale Advance Payment Term* specifies how the advance payment amount is
+calculated for a `Sale <model-sale.sale>`.
+This payment allows for the supply and shipping of the sale.
+
+.. seealso::
+
+   Sale advance payment terms are created and managed from the main menu item:
+
+      |Sales --> Configuration --> Advance Payment Terms|__
+
+      .. |Sales --> Configuration --> Advance Payment Terms| replace:: :menuselection:`Sales --> Configuration --> Advance Payment Terms`
+      __ https://demo.tryton.org/model/sale.advance_payment_term
+
+.. _model-sale.sale:
+
+Sale
+====
+
+When the *Sale Advance Payment Module* is activated, the `Sale
+<sale:model-sale.sale>` is extended to allow defining an `Advance Payment Term
+<model-sale.advance_payment_term>`.
+
+When the sale is quoted, the advance payment lines are calculated using this
+term.
+
+When the sale is processed an `Invoice <account_invoice:model-account.invoice>`
+is created for each advance payment line.
+The final invoice is generated when these advance payment invoices are paid.
+Previously paid amounts are deducted from the final invoice.
+
+.. warning::
+   If an advance payment invoice is cancelled and not recreated when processing
+   the exception.
+   The condition of the cancelled invoice will be concidered as met.
+
+.. seealso::
+
+   The `Sale <sale:model-sale.sale>` concept is introduced by the :doc:`Sale
+   Module <sale:index>`.
@@ -1,47 +1,11 @@
+###########################
 Sale Advance Payment Module
 ###########################

-The sale_advance_payment module adds support for advance payment management on
-the sale.
+The *Sale Advance Payment Module* manages advance payments for sales.

-The module adds a new document: the Advance Payment Term that defines how the
-shipment or the supply processes should be managed. Either process can be
-completely delayed until the advance payments are paid.
+.. toctree::
+   :maxdepth: 2

-Two new fields are added to *Sale*:
-
- *Advance Payment Term*
- *Advance Payment Conditions*
-
-The conditions are computed at the quotation of the sale if a payment term is
-set.
-
-When the sale is processed the advance payment invoices are created, final
-invoices will be generated when this advance payment invoices are paid. Those
-invoices will take into the account the amount previously paid by the customer.
-
-.. warning::
-    If an advance payment invoice is cancelled and not recreated when
-    processing the exception. The condition of the cancelled invoice will be
-    concidered as met.
-..
-
-Advance Payment Term
-********************
-
-It defines how advance payment invoices should be created and what they block
-until they are paid.
-
- Name: The name of the term.
- Lines:
-
-  - Description: The description used for the invoice line.
-  - Account: The account used for the invoice line. If it has default taxes,
-    the taxes will be applied.
-  - Block Supply: If checked, it prevents the creation of any supply request
-    before the payment of the advance payment invoice.
-  - Block Shipping: If checked, the shipments can not be packed before the
-    payment of the advance payment invoice.
-  - Invoice Delay: The delay to apply on the sale date for the date of the
-    advance payment invoice.
-  - Formula: It computes the amount of the invoice line.
+   design
+   releases
@@ -0,0 +1,7 @@
+.. _releases-index:
+
+=============
+Release notes
+=============
+
+.. include:: ../CHANGELOG
@@ -11,9 +11,12 @@ from setuptools import find_packages, setup


 def read(fname):
-    return io.open(
+    content = io.open(
        os.path.join(os.path.dirname(__file__), fname),
        'r', encoding='utf-8').read()
+    content = re.sub(
+        r'(?m)^\.\. toctree::\r?\n((^$|^\s.*$)\r?\n)*', '', content)
+    return content


 def get_require_version(name):
@@ -61,7 +64,8 @@ setup(name=name,
    download_url=download_url,
    project_urls={
        "Bug Tracker": 'https://bugs.tryton.org/',
-        "Documentation": 'https://docs.tryton.org/',
+        "Documentation": (
+            'https://docs.tryton.org/modules-sale-advance-payment/'),
        "Forum": 'https://www.tryton.org/forum',
        "Source Code": 'https://code.tryton.org/tryton',
        },