changeset b0a4025dc552 in modules/purchase:default
details: https://hg.tryton.org/modules/purchase?cmd=changeset&node=b0a4025dc552
description:
Improve documentation
issue9734
review314641002
diffstat:
doc/conf.py | 61 ++++++++++++++++
doc/design.rst | 168 ++++++++++++++++++++++++++++++++++++++++++++++
doc/index.rst | 84 +++-------------------
doc/usage/index.rst | 13 +++
doc/usage/prepurchase.rst | 56 +++++++++++++++
doc/usage/process.rst | 125 ++++++++++++++++++++++++++++++++++
doc/usage/returns.rst | 52 ++++++++++++++
setup.py | 7 +-
8 files changed, 491 insertions(+), 75 deletions(-)
diffs (618 lines):
diff -r 279bbaab28ca -r b0a4025dc552 doc/conf.py
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/conf.py Wed Mar 17 10:06:27 2021 +0000
@@ -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 279bbaab28ca -r b0a4025dc552 doc/design.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design.rst Wed Mar 17 10:06:27 2021 +0000
@@ -0,0 +1,168 @@
+******
+Design
+******
+
+The *Purchase Module* introduces some new concepts and updates existing
+concepts to make them work seamlessly with purchases.
+
+.. _model-purchase.purchase:
+
+Purchase
+========
+
+The *Purchase* is used to manage the purchasing process.
+Each purchase, at any time, can be in one of several different states.
+A purchase progresses through these states until eventually it is either done
+or gets cancelled.
+When some of these state changes happen the
+`Employee <company:model-company.employee>` that triggered the state change is
+also recorded.
+
+Details are stored about the `Company <company:model-company.company>` making
+the purchase and any other `Parties <party:model-party.party>`,
+`Contact Mechanisms <party:model-party.contact_mechanism>` and
+`Addresses <party:model-party.address>` that relate to it, such as the
+supplier, the contact at the supplier or the party that is sending the
+`Invoice <account_invoice:model-account.invoice>`.
+
+A purchase is identified by a unique number that is generated automatically
+from the configured `Sequence <trytond:model-ir.sequence>` and may also have
+other general information such as the purchase date, a description, or a
+reference provided by the supplier.
+
+Each purchase is made up from one or more lines.
+These lines can be put into a particular order if desired.
+Normally most lines on a purchase provide information about which
+`Products <product:concept-product>` or items are required.
+Informational lines can also be added for things like titles, comments or
+subtotals.
+
+The total, untaxed, and tax amounts for a purchase are derived from the
+amounts, prices and `Taxes <account:model-account.tax>` of the purchase's
+lines.
+
+A destination `Warehouse <stock:concept-stock.location.warehouse>` is required
+for purchases of physical items such as goods or assets.
+The purchase will automatically create `Stock Moves <stock:model-stock.move>`
+for these products.
+These stock moves are linked to the purchase's lines and must be
+recreated or ignored if they get cancelled.
+
+`Invoices <account_invoice:model-account.invoice>` relating to the purchase
+may be created, depending on which invoice method is selected.
+These invoices are based on the details from the purchase, and must be
+recreated or ignored if they get cancelled.
+
+.. seealso::
+
+ Purchases can be found by opening the main menu item:
+
+ |Purchase --> Purchases|__ menu item.
+
+ .. |Purchase --> Purchases| replace:: :menuselection:`Purchase -->
Purchases`
+ __ https://demo.tryton.org/model/purchase.purchase
+
+Reports
+-------
+
+.. _report-purchase.purchase:
+
+Purchase Report
+^^^^^^^^^^^^^^^
+
+The *Purchase Report* provides a purchase order that can be sent to the
+supplier when making a purchase.
+It includes all the relevant information from the selected purchases.
+
+Wizards
+-------
+
+.. _wizard-purchase.handle.shipment.exception:
+
+Handle Shipment Exception
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *Handle Shipment Exception* wizard helps the user ensure the purchase
+has the correct `Stock Moves <stock:model-stock.move>` associated with it.
+For stock moves that have been cancelled, it lets the user decide which
+should be re-created, and which should be ignored.
+
+.. _wizard-purchase.handle.invoice.exception:
+
+Handle Invoice Exception
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *Handle Invoice Exception* wizard helps the user make sure the purchase
+only has the appropriate `Invoices <account_invoice:model-account.invoice>`
+associated with it.
+If any of the purchase's invoices get cancelled this wizard provides the user
+with the option to re-create or ignore the cancelled invoice.
+
+.. _wizard-purchase.modify_header:
+
+Modify Header
+^^^^^^^^^^^^^
+
+Some fields on a draft purchase become read-only when lines are added to it.
+The *Modify Header* wizard allows the values in these fields to be safely
+updated.
+
+.. _wizard-purchase.return_purchase:
+
+Return Purchase
+^^^^^^^^^^^^^^^
+
+The *Return Purchase* wizard is used when a purchase needs to be sent back.
+It creates new draft purchases that match any selected purchases, but with
+all the quantities negated.
+
+.. _model-purchase.product_supplier:
+
+Product Supplier
+================
+
+The *Product Supplier* concept links together a
+`Product <product:concept-product>` with a `Party <party:model-party.party>`
+that acts as a supplier.
+The product can be either a `Product Template <product:model-product.template>`
+or one of its `Variants <product:model-product.product>`.
+Each `Company <company:model-company.company>` has their own list of product
+suppliers.
+
+A supplier's product name and code, and a lead time can be defined for each
+combination of products and suppliers.
+Also different purchase prices can be set for different minimum order
+quantities.
+
+.. seealso::
+
+ A list of products and their suppliers can be found by opening the main
+ menu item:
+
+ |Product --> Product Suppliers|__
+
+ .. |Product --> Product Suppliers| replace:: :menuselection:`Product -->
Product Suppliers`
+ __ https://demo.tryton.org/model/purchase.product_supplier
+
+.. _model-purchase.configuration:
+
+Configuration
+=============
+
+The *Purchase Configuration* concept is used to store the settings that affect
+the general behaviour and default values for purchase related activities.
+
+.. note::
+
+ Some of the purchase configuration options have no effect unless the
+ :doc:`Task Queue <trytond:topics/task_queue>` has been setup and some
+ workers are running.
+
+.. seealso::
+
+ Purchase configuration settings are found by opening the main menu item:
+
+ |Purchase --> Configuration --> Purchase Configuration|__
+
+ .. |Purchase --> Configuration --> Purchase Configuration| replace::
:menuselection:`Purchase --> Configuration --> Purchase Configuration`
+ __ https://demo.tryton.org/model/purchase.configuration/1
diff -r 279bbaab28ca -r b0a4025dc552 doc/index.rst
--- a/doc/index.rst Thu Mar 11 23:00:10 2021 +0100
+++ b/doc/index.rst Wed Mar 17 10:06:27 2021 +0000
@@ -1,78 +1,16 @@
+###############
Purchase Module
###############
-The purchase module defines the Purchase model.
-
-
-Purchase
-********
-
-The purchase is mainly defined by a party from which the products will
-be purchased and a list of purchase lines, each one containing a
-product and a quantity. Here is the extensive list of the fields, most
-of them are optional or completed with sensible default values:
-
-- Party: The supplier.
-- Contact: The contact who received the order.
-- Invoice Party: An optional different party that sends the invoice.
-- Invoice Address: The invoice address of the supplier.
-- Supplier Reference: Allow to keep track of the supplier reference
- for this order.
-- Description: An optional description for the order.
-- Number: The internal reference of the purchase (will be generated
- automatically on confirmation).
-- Reference: The optional external reference of the order.
-- Purchase Date: The date the purchase is made.
-- Payment Term: Define which payment term will be use for the future
- invoice.
-- Warehouse: Define the warehouse where the shipment will be made.
-- Currency: define the currency to use for this purchase. All product
- prices will be computed accordingly.
-- Purchase Lines:
+The *Purchase Module* provides everything that is required to create and
+manage purchases made by the company.
+It adds the idea of a purchase to Tryton, and allows it to be tracked as it
+moves through various states from draft to done.
+It makes it easy to create supplier shipments for the purchase, and includes
+the ability to automatically create related supplier invoices.
- - Type: The type of the line. The default value is *Line* which
- means that the current purchase line contains the fields defined
- hereunder. The other values of Type (*Comment*, *Subtotal*,
- *Title*) are used to add extra lines that will appear on the
- report, thus allowing to easily customise it.
- - Sequence: Allow to order lines. The value of this field is also
- updated with a drag and drop between the lines.
- - Product: An optional reference to the product to purchase.
- - Description: The description of the product to purchase.
- - Quantity: The quantity to purchase.
- - Unit: The unit of measure in which is expressed the quantity.
- - Unit Price: The unit price of the product expressed in the
- currency of the purchase.
- - Amount: The amount of the current line (Unit Price multiplied by
- Quantity).
- - Delivery Date: The computed date at which the product is expected to be
- delivered.
- - Taxes: The list of taxes that will be applied to the current line.
+.. toctree::
+ :maxdepth: 2
-- Invoice State: The state of the invoice related to the purchase.
-- Shipment State: The state of the shipment related to the purchase.
-- Untaxed: The untaxed amount.
-- Tax: The tax amount.
-- Total: The total amount.
-- State: The state of the purchase. May take one of the following
- values: Draft, Quotation, Confirmed, Cancelled.
-- Company: The company which issue the purchase order.
-- Invoice Method: May take one of the following values:
-
- - Base on order: The invoice is created when the purchase order is confirmed.
- - Base on shipment: The invoice is created when the shipment is
- received and will contains the shipped quantities. If there are
- several shipments for the same purchase, several invoices will be
- created.
- - Manual: Tryton doesn't create any invoice automatically.
-
-- Comments: A text fields to add custom comments.
-- Invoices: The list of related invoices.
-- Moves: The list of related stock moves.
-- Shipments: The list of related shipments.
-- Return Shipments: The list of the related shipment returns. If a Supplier
- Return location is defined on warehouse it will be used on return shipments
- as origin location. Otherwise the warehouse storage location will be used.
-
-The *Purchase* report allow to print the purchase orders or to send
-them by mail.
+ usage/index
+ design
diff -r 279bbaab28ca -r b0a4025dc552 doc/usage/index.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage/index.rst Wed Mar 17 10:06:27 2021 +0000
@@ -0,0 +1,13 @@
+*****
+Usage
+*****
+
+Settings, information and tasks relating to purchases can be found under the
+[:menuselection:`Purchase`] main menu item.
+
+.. toctree::
+ :maxdepth: 1
+
+ prepurchase
+ process
+ returns
diff -r 279bbaab28ca -r b0a4025dc552 doc/usage/prepurchase.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage/prepurchase.rst Wed Mar 17 10:06:27 2021 +0000
@@ -0,0 +1,56 @@
+.. _Listing Suppliers:
+
+Listing Suppliers
+=================
+
+In Tryton, by definition, the `Parties <party:model-party.party>` that your
+`Company <company:model-company.company>` has bought from are its suppliers.
+The *Purchase Module* lets you list these when you open the
+[:menuselection:`Party --> Parties --> Parties associated to Purchases`]
+main menu item.
+
+.. tip::
+
+ For some companies it is important to know which parties are, or may
+ eventually be, suppliers before you have bought anything from them.
+ One way of doing this is to create a ``Supplier``
+ `Category <party:model-party.category>`, and add all the appropriate
+ parties to it.
+
+.. _Making products purchasable:
+
+Making products purchasable
+===========================
+
+Before you can add a `Product <product:concept-product>` to a
+`Purchase <model-purchase.purchase>` it must be marked as purchasable.
+When you do this you will also be able to set some additional properties such
+as the `Unit of Measure <product:model-product.uom>` the product is normally
+bought in, and which suppliers are used and their details about the product.
+
+.. _Setting bulk prices:
+
+Setting bulk prices
+===================
+
+Suppliers may offer different prices depending on how much of a
+`Product <product:concept-product>` is purchased.
+In Tryton you can record these prices using the
+`Product Supplier <model-purchase.product_supplier>` concept.
+
+.. tip::
+
+ You can set these prices by opening one of the :guilabel:`Suppliers`
+ lines shown when viewing a product's details.
+
+.. note::
+
+ To ensure the correct price is chosen when entering in a
+ `Purchase <model-purchase.purchase>` you must ensure that the prices are
+ ordered correctly.
+ The lowest quantity must appear first, going up to the largest quantity
+ last.
+
+ This is because Tryton searches through the price lines in
+ :guilabel:`Sequence` order, and uses the last price it finds where the
+ ordered quantity is equal to, or more than, the price line's quantity.
diff -r 279bbaab28ca -r b0a4025dc552 doc/usage/process.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage/process.rst Wed Mar 17 10:06:27 2021 +0000
@@ -0,0 +1,125 @@
+.. _Creating a purchase order:
+
+Creating a purchase order
+=========================
+
+Creating a new purchase order is simply a matter of creating a new
+`Purchase <model-purchase.purchase>` and adding the lines that are
+required.
+Most of the fields are optional or have sensible default values.
+
+.. tip::
+
+ Product prices are automatically converted to the
+ `Currency <currency:model-currency.currency>` used on the purchase.
+ To keep the prices fixed when ordering in a foreign currency set the
+ currency and prices in the `Product's <product:concept-product>` list of
+ `Product Suppliers <model-purchase.product_supplier>`.
+
+.. tip::
+
+ The purchase's reference field is intended to be used to keep track of
+ the supplier's reference for the purchase.
+ This can be filled in at any time, even when the purchase is done.
+
+.. _Changing a purchase order:
+
+Changing a purchase order
+=========================
+
+To be able to change most of the values in the fields on a
+`Purchase <model-purchase.purchase>` the purchase must be in a draft state.
+
+There are also a few fields, such as the `Party <party:model-party.party>` and
+`Currency <currency:model-currency.currency>`, which become read-only when any
+lines are added to the order.
+To be able to change these without needing to remove the lines from the
+purchase you can use the :guilabel:`Modify Header` button to start the
+`Modify Header <wizard-purchase.modify_header>` wizard.
+
+.. _Receiving a shipment:
+
+Receiving a shipment
+====================
+
+Goods that are bought as part of a `Purchase <model-purchase.purchase>` are
+`received from the supplier <stock:Sending and receiving deliveries>` using a
+`Supplier Shipment <stock:model-stock.shipment.in>`.
+
+Suppliers sometimes send a single order on multiple different shipments, or
+group several orders together into a single shipment.
+As it is not possible to know how a supplier will ship products the
+*Purchase Module* does not automatically create any supplier shipments for you.
+
+A purchase does, however, create draft `Stock Moves <stock:model-stock.move>`
+for any goods or assets that have been purchased.
+Once you receive the information about what's been shipped you create a new
+supplier shipment and add these moves to it.
+
+If not all the stock has been sent, then new stock moves are automatically
+created for any remaining quantities when the shipment is received, or the
+purchase gets processed again.
+These can be added to later shipments, split up further, or cancelled.
+
+.. tip::
+
+ The supplier shipments that are related to the purchase can be found using
+ the purchase's :guilabel:`Shipments` link.
+
+ The :guilabel`Shipments` and stock :guilabel:`Moves` related to a purchase
+ can also be found using the items in the purchase's
+ :guilabel:`Open related records` menu.
+
+.. _Getting invoiced:
+
+Getting invoiced
+================
+
+The `Purchase's <model-purchase.purchase>` invoice method determines whether
+the purchase will automatically generate draft
+`Invoices <account_invoice:model-account.invoice>`.
+
+When you receive the invoice from the supplier you can then find the draft
+supplier invoice and check it for any discrepancies, before validating or
+posting it.
+
+.. tip::
+
+ The supplier invoices that are related to the purchase can be found using
+ the purchase's :guilabel:`Invoices` link, or the :guilabel:`Invoices`
+ item found in the sale's :guilabel:`Open related records` menu.
+
+.. _Handling shipment and invoice exceptions:
+
+Handling shipment and invoice exceptions
+========================================
+
+Sometimes you may cancel `Stock Moves <stock:model-stock.move>` or
+`Invoices <account_invoice:model-account.invoice>` that are related to a
+`Purchase <model-purchase.purchase>`.
+You may have done this because you no longer need these items, or you may
+now need to recreate them.
+As Tryton does not know if a cancelled item needs to be recreated, or not,
+it shows this as an exception in the purchase's shipment or invoice state.
+
+For purchases that have a shipment or invoice exception you can use the
+`Handle Shipment Exception <wizard-purchase.handle.shipment.exception>` or
+`Handle Invoice Exception <wizard-purchase.handle.invoice.exception>` wizards
+to recreate the items that need recreating, and ignore the rest.
+
+.. tip::
+
+ When using the wizard the moves and invoices to recreate will, by default,
+ already be selected.
+ This means you will need to deselect any that you do not want to recreate.
+
+.. _Finishing a purchase:
+
+Finishing a purchase
+====================
+
+In Tryton once a `Purchase <model-purchase.purchase>` is being processed there
+is no button that moves the purchase into a done state.
+This will happen automatically once the purchase's
+`Shipments <stock:model-stock.shipment.in>` and
+`Invoices <account_invoice:model-account.invoice>` are completed.
diff -r 279bbaab28ca -r b0a4025dc552 doc/usage/returns.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage/returns.rst Wed Mar 17 10:06:27 2021 +0000
@@ -0,0 +1,52 @@
+.. _Cancelling purchases:
+
+Cancelling purchases
+====================
+
+You can easily cancel `Purchases <model-purchase.purchase>` that are not yet
+confirmed using the :guilabel:`Cancel` button.
+
+Confirmed purchases cannot be cancelled, but you can put them back to a state
+where they can be cancelled.
+However, as soon as a confirmed purchase starts to be processed it can no
+longer be cancelled.
+This may happen immediately when it is confirmed, or after a delay if one has
+been correctly `Configured <model-purchase.configuration>`.
+
+Once a purchase has started to be processed, to effectively cancel the
+purchase, you must cancel its `Stock Moves <stock:model-stock.move>` and
+`Invoices <account_invoice:model-account.invoice>`.
+Once you have done this you must
+`handle the exceptions <Handling shipment and invoice exceptions>`,
+ensuring that none of the moves or invoices are selected for
+recreation.
+
+.. _Returning purchases:
+
+Returning purchases
+===================
+
+There may be times when you need to send a
+`Purchase <model-purchase.purchase>`, or part of a purchase, back to the
+supplier.
+In Tryton this is represented by a purchase that has negative quantities.
+
+One way of creating a supplier return is to select the purchases that you want
+to return and then use the `Return Purchase <wizard-purchase.return_purchase>`
+wizard.
+This creates a draft return purchase for the whole of the selected purchase.
+
+If only part of the purchase is being returned, then the return purchase can
+be altered as required.
+When it gets processed it will automatically create
+`Credit Notes <account_invoice:model-account.invoice>` and
+`Supplier Return Shipments <stock:model-stock.shipment.in.return>` where
+required.
+
+.. note::
+
+ When processing the return shipment, if the
+ `Warehouse <stock:concept-stock.location.warehouse>` has a supplier return
+ `Location <stock:model-stock.location>` the returned stock will be taken
+ from that location.
+ Otherwise the stock will be picked from the warehouse's storage location.
diff -r 279bbaab28ca -r b0a4025dc552 setup.py
--- a/setup.py Thu Mar 11 23:00:10 2021 +0100
+++ b/setup.py Wed Mar 17 10:06:27 2021 +0000
@@ -10,9 +10,12 @@
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):
@@ -80,7 +83,7 @@
download_url=download_url,
project_urls={
"Bug Tracker": 'https://bugs.tryton.org/',
- "Documentation": 'https://docs.tryton.org/',
+ "Documentation": 'https://docs.tryton.org/projects/modules-purchase/',
"Forum": 'https://www.tryton.org/forum',
"Source Code": 'https://hg.tryton.org/modules/purchase',
},
