changeset f1ad83824aa6 in modules/product:default
details: https://hg.tryton.org/modules/product?cmd=changeset;node=f1ad83824aa6
description:
Add improved documentation files
issue9635
review308231002
diffstat:
doc/conf.py | 61 ++++++++++++++++++
doc/configuration.rst | 41 ++++++++++++
doc/design.rst | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++
doc/usage.rst | 74 ++++++++++++++++++++++
4 files changed, 344 insertions(+), 0 deletions(-)
diffs (360 lines):
diff -r 4fdb6a6de540 -r f1ad83824aa6 doc/conf.py
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/conf.py Tue Jan 05 16:40:35 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 4fdb6a6de540 -r f1ad83824aa6 doc/configuration.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/configuration.rst Tue Jan 05 16:40:35 2021 +0000
@@ -0,0 +1,41 @@
+*************
+Configuration
+*************
+
+The *Product Module* uses some settings from the ``[product]`` section of the
+:doc:`configuration file <trytond:topics/configuration>`.
+
+.. _config-product.price_decimal:
+
+``price_decimal``
+=================
+
+The ``price_decimal`` setting defines how many decimal places are used when
+storing `Products' <concept-product>` unit prices.
+
+.. warning::
+
+ Once the database has been created you cannot reduce this value, doing so
+ will break your system's data integrity.
+ Also if you want to increase this value you must also manually change it in
+ the database `IR Configuration <trytond:model-ir.configuration>`.
+
+The default value is: ``4``
+
+.. _config-product.uom_conversion_decimal:
+
+``uom_conversion_decimal``
+==========================
+
+The value from the ``uom_conversion_decimal`` setting defines the number of
+decimal places used when storing the conversion rates and factors between
+`Units of Measure <model-product.uom>`.
+
+.. warning::
+
+ Once the database has been created you cannot reduce this value, doing so
+ will break your system's data integrity.
+ Also if you want to increase this value you must also manually change it in
+ the database `IR Configuration <trytond:model-ir.configuration>`.
+
+The default value is: ``12``
diff -r 4fdb6a6de540 -r f1ad83824aa6 doc/design.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design.rst Tue Jan 05 16:40:35 2021 +0000
@@ -0,0 +1,168 @@
+******
+Design
+******
+
+The *Product Module* introduces the following concepts:
+
+.. _concept-product:
+
+Product
+=======
+
+The *Product* is the main concept introduced by the *Product Module*.
+It represents an item or service that Tryton stores information about, and is
+often something that gets bought, sold, or produced.
+
+In Tryton product definitions are made up from two parts, the
+`Product Template <model-product.template>` and the
+`Product Variant <model-product.product>`.
+Both of these are sometimes referred to as the *Product*, depending on the
+context.
+
+Each product template can have many different product variants, but each
+product variant is based exclusively on one product template.
+
+A product's full code is made up from a prefix code which is defined on the
+product template and a suffix code which is specified on the product variant.
+The full product code can then be used as the product's |SKU|_.
+
+.. |SKU| replace:: :abbr:`SKU (Stock Keeping Unit)`
+.. _SKU: https://en.wikipedia.org/wiki/Stock_keeping_unit
+
+.. _model-product.template:
+
+Product Template
+----------------
+
+The *Product Template* defines the set of properties common to a group of
+`Product Variants <model-product.product>`.
+These properties include things like its list price, its type, its code, what
+`Categories <model-product.category>` it is in, and what
+`Units of Measure <model-product.uom>` are used by default for quantities of
+the product.
+
+.. seealso::
+
+ A list of product templates can be found by opening the main menu item:
+
+ |Product --> Products|__
+
+ .. |Product --> Products| replace:: :menuselection:`Product --> Products`
+ __ https://demo.tryton.org/model/product.template
+
+.. _model-product.product:
+
+Product Variant
+---------------
+
+Each *Product Variant* inherits many of its properties from its
+`Product Template <model-product.template>`.
+It does, however, have some properties that are specific to each variant
+such as the description, cost price, and suffix code which is important to
+distinguish between different variants.
+
+The identifiers that are used to refer to a product are also specific to a
+product variant.
+A product identifier is made up from a type and a code.
+
+Some of the supported types of identifier include:
+
+* International Article Number (EAN)
+* International Standard Audiovisual Number (ISAN)
+* International Standard Book Number (ISBN)
+* International Standard Identifier for Libraries (ISIL)
+* International Securities Identification Number (ISIN)
+* International Standard Music Number (ISMN)
+
+.. seealso::
+
+ A list of all the product variants is available from the main menu item:
+
+ |Product --> Products --> Variants|__
+
+ .. |Product --> Products --> Variants| replace:: :menuselection:`Product
--> Products --> Variants`
+ __ https://demo.tryton.org/model/product.product
+
+.. _model-product.category:
+
+Category
+========
+
+The product *Category* concept provides a flexible way of grouping
+`Product Templates <model-product.template>` together.
+The categories can be structured by giving them a parent category and some
+sub-categories.
+
+.. seealso::
+
+ A list of product categories can be found by opening the main menu item:
+
+ |Product --> Categories|__
+
+ .. |Product --> Categories| replace:: :menuselection:`Product -->
Categories`
+ __ https://demo.tryton.org/model/product.category
+
+.. _model-product.uom:
+
+Unit of Measure
+===============
+
+The *Unit of Measure* concept provides the units by which the quantity of a
+`Product <concept-product>` is measured.
+These are things like, meter, mile, kilogram, hour, gallon, and so on.
+
+Each unit of measure belongs to a
+`Unit of Measure Category <model-product.uom.category>`.
+
+Quantities can be converted to a different unit of measure from the same
+category using the unit of measures' rates or factors.
+It is also possible to specify the rounding precision and number of decimal
+digits used when rounding or displaying values from the unit of measure.
+
+.. seealso::
+
+ The units of measure can be found using the main menu item:
+
+ |Product --> Units of Measure|__
+
+ .. |Product --> Units of Measure| replace:: :menuselection:`Product -->
Units of Measure`
+ __ https://demo.tryton.org/model/product.uom
+
+.. _model-product.uom.category:
+
+Unit of Measure Category
+========================
+
+A *Unit of Measure Category* is used to group together
+`Units of Measure <model-product.uom>` that are used to measure the same type
+of property.
+These are things like length, weight, time or volume.
+
+.. seealso::
+
+ The units of measure can be found using the main menu item:
+
+ |Product --> Units of Measure --> Categories|__
+
+ .. |Product --> Units of Measure --> Categories| replace::
:menuselection:`Product --> Units of Measure --> Categories`
+ __ https://demo.tryton.org/model/product.uom.category
+
+.. _model-product.configuration:
+
+Configuration
+=============
+
+The product *Configuration* contains the settings which are used to configure
+the behaviour and default values for things associated with products.
+
+There are configuration options for the sequences to use to automatically
+generate codes for `Products <concept-product>`.
+
+.. seealso::
+
+ The product configuration can be found using the main menu item:
+
+ |Product --> Configuration --> Product Configuration|__
+
+ .. |Product --> Configuration --> Product Configuration| replace::
:menuselection:`Product --> Configuration --> Product Configuration`
+ __ https://demo.tryton.org/model/product.configuration/1
diff -r 4fdb6a6de540 -r f1ad83824aa6 doc/usage.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage.rst Tue Jan 05 16:40:35 2021 +0000
@@ -0,0 +1,74 @@
+*****
+Usage
+*****
+
+The items found under the [:menuselection:`Product`] main menu item allow you
+to view and manage the products on your system.
+
+.. _Using product templates and variants:
+
+Using product templates and variants
+====================================
+
+Tryton makes it easy to create `Products <model-product.template>` which have
+one or more slightly different `Variants <model-product.product>`.
+
+A simple example of where you could use this is in a company that supplies
+clothes.
+Each type of shirt may come in a range of different sizes, but most of the
+properties of the shirt, such as the name, unit of measurement, categories,
+and so on, would be the same.
+So in this case you would create a single *Product* to represent the shirt,
+and a *Variant* for each of the different sizes.
+Structuring your products like this can help you manage and update them.
+
+.. tip::
+
+ You may find that your products are not suited to being structured in this
+ way.
+ If so, don't worry, when you create a new *Product* from the
+ [:menuselection:`Product --> Products`] menu item a single variant is
+ automatically created for you and displayed as part of the product.
+
+.. _Categorising products:
+
+Categorising products
+=====================
+
+It can be a good idea to organise your `Products <concept-product>` into
+groups.
+This makes it much easier to find and manage them effectively, especially if
+you have a lot of products on your system.
+
+The product `Categories <model-product.category>` are designed for this
+purpose.
+You can create categories with any name you want, and then add the appropriate
+categories to each product.
+Each product can belong to as many, or as few, categories as required.
+The categories can also be organised into a
+structure, with each category having a parent category and some subcategories.
+This can help you classify your products more finely.
+
+For example, a clothes supplier may use these categories::
+
+ Accessories
+ Clothes
+ Shirts
+ Short sleeves
+ Long sleeves
+ Jumpers
+ Range
+ Spring Summer
+ Autumn Winter
+ Christmas
+
+Based on these categories, you may decide that a particular lightweight shirt
+belongs in the ``Clothes / Shirts / Short sleeves`` and
+``Range / Spring Summer`` categories.
+
+.. tip::
+
+ To get a list of all the products in a category first open the
+ [:menuselection:`Product --> Categories`] menu item.
+ Then when you open one of the categories listed here you will get a list
+ of all the products in that category.
