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.