changeset 0032a1985534 in modules/stock:default
details: https://hg.tryton.org/modules/stock?cmd=changeset;node=0032a1985534
description:
Improve documentation
issue9681
review302311002
diffstat:
doc/conf.py | 61 ++++++++
doc/design/configuration.rst | 17 ++
doc/design/index.rst | 16 ++
doc/design/inventory.rst | 48 ++++++
doc/design/location.rst | 59 +++++++
doc/design/move.rst | 58 +++++++
doc/design/period.rst | 32 ++++
doc/design/product.rst | 97 +++++++++++++
doc/design/shipment.rst | 231 +++++++++++++++++++++++++++++++
doc/index.rst | 319 +-----------------------------------------
doc/reference.rst | 13 +
doc/setup.rst | 69 +++++++++
doc/usage/index.rst | 14 +
doc/usage/period.rst | 16 ++
doc/usage/quantity.rst | 98 +++++++++++++
doc/usage/shipment.rst | 125 ++++++++++++++++
doc/usage/value.rst | 66 ++++++++
setup.py | 7 +-
18 files changed, 1038 insertions(+), 308 deletions(-)
diffs (1438 lines):
diff -r 86bbfaea7a8c -r 0032a1985534 doc/conf.py
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/conf.py Sat Feb 06 10:51:53 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 86bbfaea7a8c -r 0032a1985534 doc/design/configuration.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design/configuration.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,17 @@
+.. _model-stock.configuration:
+
+Configuration
+=============
+
+The *Stock Configuration* contains settings that are used to configure the
+behaviour and default values for stock related activities, including the
+sequences used to generate `Shipment <concept-stock.shipment>` numbers.
+
+.. seealso::
+
+ The stock configuration can be found using the main menu item:
+
+ |Inventory & Stock --> Configuration --> Stock Configuration|__
+
+ .. |Inventory & Stock --> Configuration --> Stock Configuration|
replace:: :menuselection:`Inventory & Stock --> Configuration --> Stock
Configuration`
+ __ https://demo.tryton.org/model/stock.configuration/1
diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/index.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design/index.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,16 @@
+******
+Design
+******
+
+The stock module introduces or extends the following concepts.
+
+.. toctree::
+ :maxdepth: 1
+
+ location
+ move
+ shipment
+ inventory
+ period
+ configuration
+ product
diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/inventory.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design/inventory.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,48 @@
+.. _model-stock.inventory:
+
+Inventory
+=========
+
+The *Inventory* concept is used to help check and correct the amount of
+stock stored in a `Location <model-stock.location>`.
+
+Each inventory has a set of lines, one for each `Product <concept-product>`
+that is in, or is should be in, the location.
+Each line has an expected quantity and an actual quantity.
+The former is used to show how much stock is expected to be in the location
+and the latter is used to record how much stock was actually found there.
+
+A option on the inventory specifies what to do with lines whose actual
+quantity is left empty.
+
+When the *Inventory* is confirmed the stock in the location is updated by
+creating a set of `Stock Moves <model-stock.move>`.
+These moves correct the stock in the location.
+They do this by transferring stock to and from the lost and found location
+associated with location being checked.
+
+.. warning::
+
+ Do not use inventories when `Setting initial stock levels`.
+
+.. seealso::
+
+ The inventory checks can be found using the main menu item:
+
+ |Inventory & Stock --> Inventories|__
+
+ .. |Inventory & Stock --> Inventories| replace::
:menuselection:`Inventory & Stock --> Inventories`
+ __ https://demo.tryton.org/model/stock.inventory
+
+Wizards
+-------
+
+.. _wizard-stock.inventory.count:
+
+Inventory Count
+^^^^^^^^^^^^^^^
+
+The *Inventory Count* wizard helps users fill in inventories on a
+`Product <concept-product>` by product basis.
+It takes a product and a quantity and adds this to the appropriate inventory
+line.
diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/location.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design/location.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,59 @@
+.. _model-stock.location:
+
+Location
+========
+
+A location represents the place where stock is stored.
+This may be a physical location, such as a shelf, or a virtual location such
+as the location used for products that have gone missing.
+
+Locations are organised in to a structure with each location having a parent
+location and zero or more sub-locations.
+It is possible to restrict a location to only one level of children.
+This enables the use of an optimisation that improves the performance of the
+the stock quantity calculation.
+
+A location also has a set of properties that allow the :ref:`current and
+forecasted amounts of stock <concept-product.quantity>` in the location to be
+obtained along with the stock's value.
+
+.. _concept-stock.location.warehouse:
+
+Warehouse
+---------
+
+Warehouses are special locations that represent a physical warehouse and as
+such can have an `Address <party:model-party.address>`.
+They are also normally split up into a set of locations each with a particular
+purpose, such as for the input, output or storage of stock.
+
+.. seealso::
+
+ Stock locations can be added, removed and changed from the main menu item:
+
+ |Inventory & Stock --> Configuration --> Locations|__
+
+ .. |Inventory & Stock --> Configuration --> Locations| replace::
:menuselection:`Inventory & Stock --> Configuration --> Locations`
+ __ https://demo.tryton.org/model/stock.location
+
+ The stock locations structure, and access to the stock levels in
+ a location can be found from the main menu item:
+
+ :menuselection:`Inventory & Stock --> Locations`
+
+.. _model-stock.location.lead_time:
+
+Location Lead Time
+==================
+
+A *Location Lead Time* is the amount of time that it normally takes to
+transfer stock between two `Warehouses <concept-stock.location.warehouse>`.
+
+.. seealso::
+
+ Location lead times can be updated from the main menu item:
+
+ |Inventory & Stock --> Configuration --> Locations --> Location Lead
Times|__
+
+ .. |Inventory & Stock --> Configuration --> Locations --> Location Lead
Times| replace:: :menuselection:`Inventory & Stock --> Configuration -->
Locations --> Location Lead Times`
+ __ https://demo.tryton.org/model/stock.location.lead_time
diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/move.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design/move.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,58 @@
+.. _model-stock.move:
+
+Move
+====
+
+In Tryton a stock *Move* represents the transfer of a given amount of a
+`Product <concept-product>` between two different
+`Stock Locations <model-stock.location>`.
+Often stock moves will be grouped together into a
+`Shipment <concept-stock.shipment>`.
+
+.. note::
+
+ Service products have no physical presence, so are not available for
+ use in stock moves.
+
+A stock move has some properties that record the planned date for the stock
+move and also its effective date, which is when the move actually happened.
+
+Some stock moves are also associated with unit and cost prices.
+These allow the value of stock to be calculated at any time, and for products'
+cost prices to be updated based on the stock moves.
+
+Each `Company <company:model-company.company>` has its own stock moves which
+are kept separate from other company's stock moves.
+
+.. seealso::
+
+ The stock moves can be listed by opening the main menu item:
+
+ |Inventory & Stock --> Moves|__
+
+ .. |Inventory & Stock --> Moves| replace:: :menuselection:`Inventory &
Stock --> Moves`
+ __ https://demo.tryton.org/model/stock.move
+
+.. _concept-stock.move.assign:
+
+Assign Concept
+--------------
+
+A stock move is assigned when the stock for the stock move has been found
+and reserved and cannot be assigned by any other stock move.
+
+When attempting to assign a stock move Tryton looks at the stock move's source
+locations and their sub-locations, and searches for the stock that is needed
+to complete the stock moves.
+If stock is found then the source location of the stock move is changed,
+or the stock move is split up into several stock moves, each of which may
+take stock from a different sub-location.
+
+If there is not enough stock available to fully assign the stock move then the
+remainder is left in a stock move that is not assigned.
+
+.. note::
+
+ Consumable products always get assigned even when there is not enough
+ stock available for the stock move.
+ This is the key difference between goods and consumable products.
diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/period.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design/period.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,32 @@
+.. _model-stock.period:
+
+Period
+======
+
+In Tryton a stock *Period* is used to group together the all stock moves that
+happened up to a specific date and that were also done after the date of any
+previous stock *Period*.
+
+This allows the stock levels for the `Products <concept-product>` in all stock
+`Locations <model-stock.location>` to be calculated for the date of the period,
+and stored in the `Stock Period Cache <model-stock.period.cache>`.
+
+These cached values can then be used, where applicable, instead of having to
+recalculate them each time they are needed.
+
+.. seealso::
+
+ The periods can be viewed and managed from the main menu item:
+
+ |Inventory & Stock --> Configuration --> Periods|__
+
+ .. |Inventory & Stock --> Configuration --> Periods| replace::
:menuselection:`Inventory & Stock --> Configuration --> Periods`
+ __ https://demo.tryton.org/model/stock.period
+
+.. _model-stock.period.cache:
+
+Period Cache
+============
+
+The *Period Cache* is used to store the quantities of a product in a
+particular location on the date defined by its `Period <model-stock.period>`.
diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/product.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design/product.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,97 @@
+.. _concept-product:
+
+Product
+=======
+
+When the *Stock Module* is activated, products gain some extra properties.
+These include a product's stock and forecast quantities, which show its
+current and predicted future stock situation, and the cost value of its
+stock.
+
+.. seealso::
+
+ The `Product <product:concept-product>` concept is introduced by the
+ :doc:`Product Module <product:index>`.
+
+.. _concept-product.quantity:
+
+Product Quantity
+----------------
+
+The amount, and the value, of a product in a
+`Stock Location <model-stock.location>` is calculated by adding up all the
+`Stock Moves <model-stock.move>` in to that location and subtracting those
+out of the same location.
+
+Some values from the
+:attr:`Transaction context <trytond:trytond.transaction.Transaction.context>`
+are used to help determine which stock moves get included in this calculation
+and which get left out.
+These values include things like which locations to include in the
+calculation, and what dates should be included.
+
+Normally, when calculating stock quantities for a date in the past, only moves
+that are done are included in the calculation, and only if their effective
+date is early enough.
+This reflects the real situation based on completed stock moves.
+For dates in the future, draft and `Assigned <concept-stock.move.assign>`
+moves are also included, but only if their planned date is between today's
+date and the future date, inclusive.
+
+.. note::
+
+ The stock quantity of consumable products is calculated in exactly
+ the same way as any other product, even though consumable products
+ can always be assigned regardless of how much stock there is.
+
+Wizards
+-------
+
+.. _wizard-product.recompute_cost_price:
+
+Recompute Cost Price
+^^^^^^^^^^^^^^^^^^^^
+
+The *Recompute Cost Price* wizard updates products' cost prices using their
+cost price method.
+
+.. _wizard-product.modify_cost_price:
+
+Modify Cost Price
+^^^^^^^^^^^^^^^^^
+
+The *Modify Cost Price* wizard is only way in which a product's cost price
+can be changed once it has stock moves.
+The wizard takes a date and a fixed price or formula for the new cost price.
+These changes are stored in the
+`Cost Price Revision <model-product.cost_price.revision>` concept and are
+applied at the beginning of the date that was selected when the cost price
+of the product gets re-calculated.
+
+.. _model-stock.product_quantities_warehouse:
+
+Product Quantities by Warehouse
+===============================
+
+The idea of the *Product Quantities by Warehouse* concept is to provide
+information about how the stock levels of one or more products have varied
+over time in a particular `Warehouse <concept-stock.location.warehouse>`.
+
+.. _model-stock.product_quantities_warehouse.move:
+
+Product Quantities by Warehouse Move
+====================================
+
+The *Product Quantities by Warehouse Move* concept provides information about
+how `Stock Moves <model-stock.move>` have affected the stock levels in a
+`Warehouse <concept-stock.location.warehouse>` over time.
+
+.. _model-product.cost_price.revision:
+
+Cost Price Revision
+===================
+
+The *Cost Price Revision* records changes to a product's cost price.
+These revisions are automatically created when the product's cost price is
+changed using the `Modify Cost Price <wizard-product.modify_cost_price>`
+wizard.
diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/shipment.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design/shipment.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,231 @@
+.. _concept-stock.shipment:
+
+Shipment
+========
+
+In Tryton the concept of a *Shipment* is used to help organise and manage
+groups of related `Stock Moves <model-stock.move>`.
+There are different types of shipment which are used for different purposes.
+Some of these types of shipment may also be split up into stages.
+In each stage stock is moved to or from an intermediate
+`Location <model-stock.location>`.
+Each stage's moves form a subset of the shipment's total moves.
+
+.. _model-stock.shipment.in:
+
+Supplier Shipment
+-----------------
+
+A *Supplier Shipment* has a set of properties that hold details about the
+shipment such as who the supplier is, what
+`Warehouse <concept-stock.location.warehouse>` it is going to and the date
+when the shipment is expected to be delivered.
+
+It is made up from two sets of `Stock Moves <model-stock.move>`:
+
+* Incoming moves, these are used to move stock between a supplier
+ `Location <model-stock.location>` and the warehouse's input location, and
+* Inventory moves, these then put the stock away in the warehouse's storage
+ location, or one of its child locations.
+
+.. note::
+
+ If the warehouse's input location and storage location are the same then
+ the inventory moves are not created.
+
+.. seealso::
+
+ The supplier shipments can be found by opening the main menu item:
+
+ |Inventory & Stock --> Supplier Shipments|__
+
+ .. |Inventory & Stock --> Supplier Shipments| replace::
:menuselection:`Inventory & Stock --> Supplier Shipments`
+ __ https://demo.tryton.org/model/stock.shipment.in
+
+Reports
+^^^^^^^
+
+.. _report-stock.shipment.in.restocking_list:
+
+Restocking List
+"""""""""""""""
+
+The *Restocking List* report lists the items on an incoming shipment and the
+destination locations for the stock based on the inventory moves.
+
+.. _model-stock.shipment.in.return:
+
+Supplier Return Shipment
+------------------------
+
+A *Supplier Return Shipment* has a set of properties that contain information
+about the shipment such as who the supplier was, what
+`Address <party:model-party.address>` the shipment is going to, and the date
+the shipment is sent.
+
+It is made up from a single set of `Stock Moves <model-stock.move>` that return
+the stock directly back to a supplier `Location <model-stock.location>`.
+
+.. seealso::
+
+ The supplier shipments can be found by opening the main menu item:
+
+ |Inventory & Stock --> Supplier Shipments --> Supplier Return
Shipments|__
+
+ .. |Inventory & Stock --> Supplier Shipments --> Supplier Return
Shipments| replace:: :menuselection:`Inventory & Stock --> Supplier Shipments
--> Supplier Return Shipments`
+ __ https://demo.tryton.org/model/stock.shipment.in.return
+
+.. _model-stock.shipment.out:
+
+Customer Shipment
+-----------------
+
+A *Customer Shipment* has a set of properties that contain information about
+the shipment such as which `Warehouse <concept-stock.location.warehouse>` it
+is being sent from, what `Address <party:model-party.address>` it is being
+delivered to, and the date it is being sent.
+
+A customer shipment is made up from two sets of
+`Stock Moves <model-stock.move>`:
+
+* Inventory moves, these moves are used to pick the stock from the warehouse's
+ storage `Location <model-stock.location>` and put it in the output location,
+ and
+* Outgoing moves, these then take the picked stock and send it to a
+ customer location.
+ The outgoing moves are created first and define what stock needs to be sent
+ to the customer.
+
+.. note::
+
+ If the warehouse's picking location (or storage location if no picking
+ location is defined) is the same as its output location then only
+ outgoing moves are created and these moves do not get
+ `Assigned <concept-stock.move.assign>`.
+
+.. seealso::
+
+ The customer shipments can be found by opening the main menu item:
+
+ |Inventory & Stock --> Customer Shipments|__
+
+ .. |Inventory & Stock --> Customer Shipments| replace::
:menuselection:`Inventory & Stock --> Customer Shipments`
+ __ https://demo.tryton.org/model/stock.shipment.out
+
+Reports
+^^^^^^^
+
+.. _report-stock.shipment.out.picking_list:
+
+Picking List
+""""""""""""
+
+The *Picking List* report lists the stock that is needed for a shipment.
+For each item on the shipment it details the location the stock should be
+taken from, and how much should be taken.
+
+.. _report-stock.shipment.out.delivery_note:
+
+Delivery Note
+"""""""""""""
+
+The *Delivery Note* report contains information about where the shipment is
+being sent, and when the delivery is happening.
+It also lists all the items on the shipment.
+
+.. _model-stock.shipment.out.return:
+
+Customer Return Shipment
+------------------------
+
+A *Customer Return Shipment* has properties that contain information about
+which customer the stock is being returned from, which
+`Warehouse <concept-stock.location.warehouse>` it is sent to and the date the
+return is happening.
+
+It is made up from two sets of `Stock Moves <model-stock.move>`:
+
+* Incoming moves, these are used to move stock between a customer
+ `Location <model-stock.location>` and the warehouse's input location, and
+* Inventory moves, these then put the stock away in the warehouse's storage
+ location, or one of its child locations.
+
+.. note::
+
+ If the warehouse's input location and storage location are the same then
+ the inventory moves are not created.
+
+.. seealso::
+
+ The customer shipments can be found by opening the main menu item:
+
+ |Inventory & Stock --> Customer Shipments --> Customer Return
Shipments|__
+
+ .. |Inventory & Stock --> Customer Shipments --> Customer Return
Shipments| replace:: :menuselection:`Inventory & Stock --> Customer Shipments
--> Customer Return Shipments`
+ __ https://demo.tryton.org/model/stock.shipment.out.return
+
+Reports
+^^^^^^^
+
+.. _report-stock.shipment.out.return.restocking_list:
+
+Customer Return Restocking List
+"""""""""""""""""""""""""""""""
+
+The *Customer Return Restocking List* report lists the items that were
+returned by a customer.
+For each item a destination location for the stock is also included based on
+the inventory moves.
+
+.. _model-stock.shipment.internal:
+
+Internal Shipment
+-----------------
+
+An internal shipment allows a group of `Stock Moves <model-stock.move>`,
+between locations within the same `Company <company:model-company.company>`,
+to be managed as a single entity.
+
+For internal shipments that are planned to start and end on different dates it
+is made up from two sets of moves.
+The first set are outgoing moves that put the stock in a transit
+`Location <model-stock.location>` and the second set are incoming moves that
+take the stock from the transit location and place it in the destination
+location.
+
+.. seealso::
+
+ Internal shipments are available from the main menu item:
+
+ |Inventory & Stock --> Internal Shipments|__
+
+ .. |Inventory & Stock --> Internal Shipments| replace::
:menuselection:`Inventory & Stock --> Internal Shipments`
+ __ https://demo.tryton.org/model/stock.shipment.internal
+
+Reports
+^^^^^^^
+
+.. _report-stock.shipment.internal.report:
+
+Internal Shipment Report
+""""""""""""""""""""""""
+
+The *Internal Shipment Report* provides a list of the items on the internal
+shipment along with their quantities.
+For shipments between `Warehouses <concept-stock.location.warehouse>` it also
+contains the `Address <party:model-party.address>` of the warehouse the stock
+is being sent to.
+
+Wizards
+-------
+
+.. _wizard-stock.shipment.assign:
+
+Assign Shipment
+^^^^^^^^^^^^^^^
+
+The *Assign Shipment* wizard is used to assign a shipment.
+Assigning a shipment tries to `Assign <concept-stock.move.assign>` the
+`Stock Moves <model-stock.move>` that take the stock for the shipment.
+If not all the stock moves can be assigned then it provides the user with a
+set of options of what to do next.
diff -r 86bbfaea7a8c -r 0032a1985534 doc/index.rst
--- a/doc/index.rst Wed Feb 03 21:21:03 2021 +0100
+++ b/doc/index.rst Sat Feb 06 10:51:53 2021 +0000
@@ -1,311 +1,18 @@
+############
Stock Module
############
-The stock module defines fundamentals for all stock management
-situations: Locations where products are stored, moves between these
-locations, shipments for product arrivals and departures and inventory
-to control and update stock levels.
-
-Location
-********
-
-Locations are generic places where products are physically or
-virtually stored. The following location types are defined:
-
-* Storage
-
- Storage locations define real places where products are stored.
-
-* Warehouse
-
- Warehouses are meta-locations which define input, storage, picking, output
- ,lost and found and waste locations. These locations are all of type
- Storage. Input and Output are locations where incoming an outgoing product
- are temporally stored awaiting transportation. The storage location is often
- the biggest location where products are stored for middle or long periods of
- time. The picking location is optionally where the products are picked by
- the customer shipment otherwise the storage location is used. The lost and
- found location is the location used by inventories when correcting stock
- levels. Waste locations are used to throw away wrong products entering the
- warehouse.
-
-* Customer
-
- Customer locations are virtual locations accumulating products that
- have been sent to customers.
-
-* Supplier
-
- Supplier locations are virtual locations accumulating products that have
- been received from suppliers.
-
-* Lost And Found
-
- Lost And Found locations collects inventory gaps. See
- :ref:inventory for details.
-
-* Drop
-
- Drop locations are virtual locations used as intermediary locations in the
- process of drop shipping.
-
-* Production
-
- Production locations are used during the production of products.
-
-* View
-
- View locations are virtual locations that can be used to logically group
- other location types.
-
-Locations are organised in tree structures, allowing to define
-fine grained structures.
-It is possible to restrict a location to have only one level of children, this
-allows to improve the performance of the stock quantity computation.
-
-Location Lead Time
-------------------
-
-It allows to define the time needed for an *Internal Shipment* between two
-warehouses.
-
-
-Move
-****
-
-A move is a movement of a product in a given quantity between two
-locations. It may eventually defines a unit price and a currency for
-the products that are moved from or to another company, allowing to
-compute stock value at any time (and to update the cost prices if the
-chosen cost price method is *Average*). A move also defines a planned
-date (when one plan to do the move) and an effective date (when the
-move is actually made). Products that are used in stock move must of
-of type *Goods* or *Assets*. Stock levels are ignored for
-consumable, this means that they can be always assigned. *Service*
-products are ignored by the stock module.
-
-A move can be in one of this states:
-
-* Draft
-
- The initial state, used when the move is created and to define
- future stock movement that are planned, but still subject to
- modifications.
-
-* Assigned
-
- An assigned move allow to reserve some products. Thus preventing
- other user to assign them.
-
-* Done
-
- The move is in state Done when the real movement is made.
-
-* Cancelled
-
- A cancelled move will be ignored by the system. Only Draft or
- Assigned move can be cancelled. To revert a move in state Done, an
- opposite move must be created.
-
-* Staging
-
- A phantom state used to create in advance move that should not be taken for
- stock computation.
-
-A cron task runs every day and recomputes the cost price of moves if a past
-unit price has changed.
-
-Product Quantities
-------------------
-
-Product quantities on each location are the sum of all moves coming
-from or going to this location. For quantities that are computed for
-a date in the past, only confirmed moves (i.e. in state Done) with an
-effective date inferior to the considered date are taken into account,
-reflecting the real situation. For future quantities, Draft and
-Assigned move with a planned date greater than today and smaller than
-the given date are also summed.
-
-
-Shipment
-********
-
-A Shipment define a group of moves happening at the same date and
-around the same location.
-
-
-Supplier Shipment
------------------
-
-A supplier shipment is used when products are received from a
-supplier. It is mainly composed of a party (the supplier), a location
-(the warehouse in which the products are coming) and two list of moves:
-
-* Incoming moves
-
- The moves between the supplier location and the input location
- (as defined on the warehouse).
-
-* Inventory moves
-
- The inventory moves are between the input location and the storage
- location (or one of his child locations).
-
-If the storage location is configured as the same as the input location only
-incoming moves are created.
-
+The *Stock Module* provides the fundamental concepts required for managing
+stock.
+This includes keeping track of where the stock is, how much is available,
+and checking and correcting stock levels.
+It also allows stock to be moved from one place to another, and delivered to
+and from customers and suppliers.
-The supplier shipment can be in one of this states:
-
-* Draft
-
- Incoming moves and inventory moves (if they exist) are in draft.
-
-* Received
-
- Incoming move are set in state Done, inventory moves are created if
- necessary.
-
-* Done
-
- Inventory and incoming moves are in state Done.
-
-* Cancelled
-
- All moves are cancelled.
-
-
-Customer Shipment
------------------
-
-A customer shipment is used for sending products to customer. It is
-mainly composed of a party (the customer), a location (the warehouse
-out of which the product are going) and two list of moves:
-
-* Inventory moves
-
- The moves between the picking or storage location and the output location of
- the warehouse
-
-* Outgoing moves
-
- The moves between the output location of the warehouse and a
- customer location.
-
-If the picking or storage location is configured as the same as the output
-location, then only outgoing moves are created and no assignation is done.
-
-
-The customer shipment can be in one of this states:
-
-* Draft
-
- Outgoing moves and inventory moves (if they exist) are in draft.
-
-* Waiting
-
- When a customer shipment is set to waiting, the inventory moves are
- created (or completed) to balance the outgoing moves. The waiting
- state also means that the shipment should be processed.
-
-* Assigned
-
- The assigned state is when products have been assigned (or reserved)
- from the storage locations.
-
-* Packed
-
- The packed state is when the inventory moves have been made, i.e
- when the products have been physically moved to the outgoing
- locations.
-
-* Done
-
- The shipment is Done when the outgoing moves have been made,
- e.g. when a truck left the warehouse.
-
-* Cancelled
-
- A shipment which is not yet completed (not in state Done) can be
- cancelled at any time. This also cancels all the moves.
-
+.. toctree::
+ :maxdepth: 2
-Rescheduling Customer Shipments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-It is possible to setup a cron task to reschedule customer shipments that are
-planned for the past. By default they are rescheduled to today.
-
-
-Internal Shipment
------------------
-
-An internal shipment is used for sending products across locations
-inside the company. It is mainly composed of two locations and a list
-of moves. It can be in one of these states:
-
-
-* Draft
-
- The moves (if they exist) are in draft.
-
-* Waiting
-
- The waiting state means that the shipment should be processed.
-
-* Assigned
-
- The assigned state is when products have been assigned.
-
-* Done
-
- The shipment is Done when the moves have been made.
-
-* Cancelled
-
- A shipment which is not yet completed (not in state Done) can be
- cancelled at any time. This also cancels all the moves.
-
-
-Rescheduling Internal Shipments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-It is possible to setup a cron task to reschedule internal shipments that are
-planned for the past. By default they are rescheduled to today.
-
-
-Inventory
-*********
-
-Inventories allow to control and update stock levels. They are mainly composed
-of the inventoried storage location and a list of inventory lines.
-Inventory lines consist of a product and it's default unit of measure, an
-expected quantity and the real quantity (the real products on the shelves).
-
-A button allows to auto-complete inventory lines with respect to the expected
-quantities for each product in the location.
-Another button allows to launch a wizard to count products by adding the
-quantity to the existing matching line.
-
-When the inventory is confirmed, moves are created to balance expected
-quantities and real ones.
-
-.. warning::
- Inventories must not be used to import initial stock levels.
- Individual moves from supplier to each locations must be used with the cost
- price as unit price.
-
-Product
-*******
-
-The cost price of a product can only be modified using the "Modify Cost Price"
-wizard once it is associated with stock moves. The wizard stores, for each
-template or product the cost price revision. This revision contains a formula
-that compute the new cost price based on the current one. E.g. `cost_price *
-0.9` to reduce the cost price by 10%.
-The cost price revisions are applied at the beginning of the stored date when
-the cost price of a product is re-computed.
-
-.. warning::
- If the user modifies a revision manually, they must also run the "Recompute
- Cost Price" wizard.
+ setup
+ usage/index
+ design/index
+ reference
diff -r 86bbfaea7a8c -r 0032a1985534 doc/reference.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/reference.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,13 @@
+*************
+API Reference
+*************
+
+Stock Quantities
+================
+
+.. class:: trytond.modules.stock.StockMixin
+
+ This mixin_ provides some common methods that are useful when creating
+ classes that provide quantity fields.
+
+ .. _mixin: http://en.wikipedia.org/wiki/Mixin
diff -r 86bbfaea7a8c -r 0032a1985534 doc/setup.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/setup.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,69 @@
+*****
+Setup
+*****
+
+.. _Setting up stock locations:
+
+Setting up stock locations
+==========================
+
+The *Stock Module* provides a set of default
+`Stock Locations <model-stock.location>`, however it is likely that you will
+want to customise them to suit your company.
+
+.. tip::
+
+ If you only have a small `Warehouse <concept-stock.location.warehouse>`
+ you can use the same location for its storage, input and output locations.
+ This reduces the stock moves required to send and receive shipments.
+
+.. tip::
+
+ If you have a large number of locations in your warehouse you can
+ use the option to limit locations to only a single level of children.
+ This will improve the performance of Tryton when it is calculating
+ stock quantities.
+
+.. tip::
+
+ If you are altering your stock locations, and you have already used a
+ stock location then it cannot be deleted.
+ However, you can deactivate it which will hide it during normal use.
+
+.. _Setting initial stock levels:
+
+Setting initial stock levels
+============================
+
+When you start using Tryton you may already have some stock that you want to
+bring into the system.
+
+In order to ensure the value of your stock is correctly calculated, and to
+show that this stock has (at some point in the past) come from a supplier,
+you must enter this initial stock in the correct way.
+
+The right way of doing this is to create a set of individual
+`Stock Moves <model-stock.move>`.
+These moves can be created in the view that is opened from the
+|Inventory & Stock --> Moves|__ main menu item.
+Each of the stock moves should move some stock of a `Product <concept-product>`
+from a supplier `Location <model-stock.location>` to the appropriate storage
+location.
+These stock moves must have their unit prices set to their product's cost
+price.
+
+.. |Inventory & Stock --> Moves| replace:: :menuselection:`Inventory & Stock
--> Moves`
+__ https://demo.tryton.org/model/stock.move
+
+.. note::
+
+ As these moves are for your initial stock they have no origin, and
+ when you try and do these moves Tryton will warn you about this.
+ Because this is for your initial stock this is not a problem, and you
+ can safely go ahead and finish doing the moves.
+
+.. tip::
+
+ If you create all the stock moves to start with, you can then select them
+ all in the list view, and use the :guilabel:`Do` item from the
+ :guilabel:`Launch Action` menu to do them all in one go.
diff -r 86bbfaea7a8c -r 0032a1985534 doc/usage/index.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage/index.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,14 @@
+*****
+Usage
+*****
+
+The [:menuselection:`Inventory & Stock`] main menu item allows access to the
+items that allow you to view, manage and change things related to stock.
+
+.. toctree::
+ :maxdepth: 1
+
+ shipment
+ quantity
+ value
+ period
diff -r 86bbfaea7a8c -r 0032a1985534 doc/usage/period.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage/period.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,16 @@
+.. _Using stock periods:
+
+Using stock periods
+===================
+
+You can use `Stock Periods <model-stock.period>` to stop
+`Stock Moves <model-stock.move>` being created or updated before a specific
+date, and to improve the performance of Tryton when looking at and using
+`Product Quantities <concept-product.quantity>`.
+
+.. tip::
+
+ Depending on the number of stock moves that your
+ `Company <company:model-company.company>` generates you may find it useful
+ to create new stock periods as part of your accounting period end, or
+ fiscal year end, processes.
diff -r 86bbfaea7a8c -r 0032a1985534 doc/usage/quantity.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage/quantity.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,98 @@
+.. _Viewing stock levels:
+
+Viewing stock levels
+====================
+
+In Tryton there are a few different ways of seeing
+`Product Stock Quantities <concept-product.quantity>`.
+You can also easily see what the stock situation was at any time in the past,
+and get an idea of what the stock situation will be after any
+`Stock Moves <model-stock.move>` that are still being processed have been
+completed.
+
+.. note::
+
+ Tryton is designed to allow you to create stock moves even if they
+ create negative stock.
+ For normal storage locations negative stock levels indicate that more
+ stock has been used than was available.
+ This suggests that there may be incoming moves to the location that
+ have not yet been done, or a mistake has been made that can be resolved
+ by `Checking and correcting stock levels`.
+
+ However, although it is possible to create negative stock, you will
+ normally use `Shipments <concept-stock.shipment>` to help manage stock
+ moves, and a process to `assign them <Assigning shipments>`.
+ These respect stock availability and wont allow you to create negative
+ stock unless you force them to.
+
+Depending on what you are trying to find out you can get information about
+stock levels for either `Products <concept-product>` or
+`Locations <model-stock.location>`.
+
+If you are interested in finding out where some particular products are
+stored, then once you have selected the products you are interested in, you
+can use the menu items in the product's :guilabel:`Open related records` menu.
+
+To view how much stock is in one or more stock locations you first need to
+select the locations you are interested in.
+Once you have done this you can use the :guilabel:`Products` item from the
+:guilabel:`Open related records` menu.
+This then shows the total stock that is in all the selected locations.
+
+.. tip::
+
+ From the [:menuselection:`Inventory & Stock --> Locations`] main menu item
+ you can quickly get a list of stock in a single location by opening the
+ location you are interested in.
+
+.. tip::
+
+ If you have only selected a single location then the stock levels will
+ include all the stock in the location's children as well.
+ However, if you selected multiple locations then only the stock in the
+ selected locations is included, any stock in their child locations is
+ *not* included.
+
+.. _Checking and correcting stock levels:
+
+Checking and correcting stock levels
+====================================
+
+There are a range of things, such as mispicks, damages and theft, that can
+cause the stock levels on Tryton to not match the actual amount of stock
+available.
+
+Tryton allows you to check for and correct these discrepancies by performing
+an `Inventory <model-stock.inventory>` of a
+`Stock Location <model-stock.location>`.
+This process is sometimes also called a stocktake, stock count or inventory
+check.
+How often you need to do this, and to what extent, is very dependent on your
+business.
+You may do this once a year at the end of your fiscal year, or continuously
+by means of a `cycle count`_.
+
+When you create a new inventory you can use the :guilabel:`Complete` button to
+complete the creation of the inventory.
+This adds a line to the inventory for each product that is expected to be in
+the location.
+
+How you go about actually counting the stock will depend on how your stock
+location is organised.
+If each `Product <concept-product>` is all together and is easy to count,
+then you can enter the totals directly into the :guilabel:`Quantity` column.
+If there are many different lines in the location, or not all of each product
+is together, then you can start the `Count <wizard-stock.inventory.count>`
+wizard using the :guilabel:`Count` button to enter the quantities as you go.
+In this case, multiple quantities for the same product will be automatically
+added together.
+
+For each inventory you can choose how to deal with any lines where the quantity
+has been left empty.
+You can either keep the stock in the location, or empty it out.
+
+Once the inventory has been finished you use the :guilabel:`Confirm` button
+to correct the stock levels on Tryton.
+
+.. _`cycle count`: https://en.wikipedia.org/wiki/Cycle_count
diff -r 86bbfaea7a8c -r 0032a1985534 doc/usage/shipment.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage/shipment.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,125 @@
+.. _Sending and receiving deliveries:
+
+Sending and receiving deliveries
+================================
+
+In Tryton you use `Shipments <concept-stock.shipment>` to send stock to your
+customers and receive stock from your suppliers.
+There are different kinds of shipments available depending on whether you're
+dealing with customers or suppliers and whether you are sending or receiving
+stock.
+
+Although each type of shipment helps you manage the delivery of some stock,
+and encompasses the same set of ideas, each is tailored for a particular
+type of delivery.
+
+From Suppliers
+--------------
+
+You use a `Supplier Shipment <model-stock.shipment.in>` when receiving stock
+from a supplier.
+
+* The supplier shipment is first received in to the
+ `Warehouse's <concept-stock.location.warehouse>`
+ input `Location <model-stock.location>`.
+* You can then use the
+ `Restocking List <report-stock.shipment.in.restocking_list>`
+ to help you put the stock away in the right locations in the warehouse.
+
+To Suppliers
+------------
+
+If you need to send stock back to a supplier you use a
+`Supplier Return Shipment <model-stock.shipment.in.return>`.
+
+To Customers
+------------
+
+You use a `Customer Shipment <model-stock.shipment.out>` when sending stock
+out to a customer.
+
+* When the customer shipment is waiting to be worked on, normally the first
+ thing you need to do is `Assign it <Assigning shipments>`.
+* You then pick the stock from the
+ `Warehouse <concept-stock.location.warehouse>`.
+ A `Picking List <report-stock.shipment.out.picking_list>` helps with this as
+ it details how much stock you need, and where it can be found.
+* Once you've picked and packed the delivery you can dispatch it to the
+ customer from the warehouse's output `Location <model-stock.location>`.
+ It is common practice to send a
+ `Delivery Note <report-stock.shipment.out.delivery_note>` along with your
+ customer's shipment.
+
+From Customers
+--------------
+
+Stock that is returned by customers is handled by using a
+`Customer Return Shipment <model-stock.shipment.out.return>`.
+It works in a similar way to supplier shipments.
+
+* You receive the stock in the warehouse's input location.
+* Then you use the `Customer Return Restocking List
+ <report-stock.shipment.out.return.restocking_list>` to help you put it away
+ in the warehouse.
+
+.. _Moving stock within your company:
+
+Moving stock within your company
+================================
+
+If you want to move stock between `Locations <model-stock.location>` within a
+`Warehouse <concept-stock.location.warehouse>`, or between warehouses that
+belong to the same `Company <company:model-company.company>` you use an
+`Internal Shipment <model-stock.shipment.internal>`.
+
+The internal shipment helps you manage the processes of moving stock from one
+place to another.
+
+* Once the internal shipment is waiting to be worked on, you need to go ahead
+ and `Assign it <Assigning shipments>`.
+* You can use the
+ `Internal Shipment Report <report-stock.shipment.internal.report>`
+ to help you find and pick, or move, the stock.
+* If the stock is intended for another warehouse you then send the shipment
+ to it.
+* Finally once you've put the stock away in the correct locations the internal
+ shipment is done.
+
+.. tip::
+
+ You can use the `Stock Location Lead Time <model-stock.location.lead_time>`
+ to setup how long it normally takes for shipments between two warehouses.
+
+.. note::
+
+ If an internal shipment is expected to take more than one day to complete
+ then when the stock is sent it gets put in a transit location until the
+ shipment is done.
+
+.. _Assigning shipments:
+
+Assigning shipments
+===================
+
+Any `Shipments <concept-stock.shipment>` types that normally take stock from
+either a storage or view `Location <model-stock.location>` must be assigned
+before they can be done.
+The aim of this process is to find and reserve the stock specifically for the
+shipment.
+
+The `Assign Shipment <wizard-stock.shipment.assign>` wizard is used when
+assigning shipments.
+It tries to `Assign <concept-stock.move.assign>` each of the shipment's
+incoming `Stock Moves <model-stock.move>`.
+In doing so it updates the stock moves based on what stock it managed to find.
+
+If there is not enough stock available to fully assign the shipment you can
+force the remainder to be assigned, although this will result in some stock
+locations having negative stock.
+
+.. note::
+
+ When stock moves from a view location are assigned the stock must always be
+ taken from one of its sub-locations, as view locations cannot be the
+ source or destination of a done move.
+ This also means moves from a view location cannot be forced.
diff -r 86bbfaea7a8c -r 0032a1985534 doc/usage/value.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage/value.rst Sat Feb 06 10:51:53 2021 +0000
@@ -0,0 +1,66 @@
+.. _Finding the value of your stock:
+
+Finding the value of your stock
+===============================
+
+In Tryton you can easily find the value of stock that's in one, or more,
+`Locations <model-stock.location>` as the stock's cost value is included when
+`Viewing stock levels` for the locations you are interested in.
+
+.. _Updating the value of your stock:
+
+Updating the value of your stock
+================================
+
+The value of the stock that your `Company <company:model-company.company>`
+owns is based on the `Quantity <concept-product.quantity>` of stock and its
+cost price.
+
+You can correct the quantity of stock by
+`Checking and correcting stock levels`.
+
+You can also change how much the stock is worth by
+`Updating a product's cost price`.
+
+.. _Updating a product's cost price:
+
+Updating a product's cost price
+===============================
+
+A `Product's <concept-product>` cost price is affected by various factors
+including its cost price method and in some cases the value of stock received
+or dispatched.
+
+The `Recompute Cost Price <wizard-product.recompute_cost_price>` wizard is
+used to update a product's cost price using the product's cost price method.
+
+.. tip::
+
+ Most of the time you will not need to run the wizard that recalculates your
+ products' cost prices, because, by default, there is a scheduled task that
+ runs once a day and does this for you.
+
+ You can, however, also run the wizard at any time to ensure you are seeing
+ the most up to date information.
+
+Once there are some `Stock Moves <model-stock.move>` for a
+`Product <concept-product>` you can make a manual adjustment to a product's
+cost price using the `Modify Cost Price <wizard-product.modify_cost_price>`
+wizard.
+This allows you to do things like reduce the cost price, and consequently
+stock value, of a product by ``10%`` from a certain date by using
+``cost_price * 0.9``.
+
+.. note::
+
+ If you modify a cost price you may also need to run the *Recompute Cost
+ Price* wizard to see the changes reflected in the product's cost price.
+
+.. _Viewing cost price changes:
+
+Viewing cost price changes
+==========================
+
+You can get a list of any manual cost price changes that have been applied
+to a product by using the :guilabel:`Cost Price Revision` relate action from
+the product's :guilabel:`Open Related Records` menu.
diff -r 86bbfaea7a8c -r 0032a1985534 setup.py
--- a/setup.py Wed Feb 03 21:21:03 2021 +0100
+++ b/setup.py Sat Feb 06 10:51:53 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-stock/',
"Forum": 'https://www.tryton.org/forum',
"Source Code": 'https://hg.tryton.org/modules/stock',
},
