From 356123b7ca9055658bf49258cc8d8fd74367d061 Mon Sep 17 00:00:00 2001 From: David Harper Date: Tue, 15 Dec 2020 12:40:23 +0000 Subject: [PATCH] Add documentation files issue9139 review297241003 --- doc/conf.py | 60 ++++++++++++++ doc/design.rst | 217 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/usage.rst | 120 +++++++++++++++++++++++++++ 3 files changed, 397 insertions(+) create mode 100644 doc/conf.py create mode 100644 doc/design.rst create mode 100644 doc/usage.rst diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000000..a772bdd7c9 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,60 @@ +# 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() + +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 --git a/doc/design.rst b/doc/design.rst new file mode 100644 index 0000000000..436750945b --- /dev/null +++ b/doc/design.rst @@ -0,0 +1,217 @@ +****** +Design +****** + +The *Party Module* introduces the following concepts: + +.. _model-party.party: + +Party +===== + +*Parties* are the primary concept provided by the *Party Module*. +Each party represents a person, business, organisation, association or other +group that can be treated as a single entity. + +There are often a lot of properties associated with a party, including things +like `Addresses `, +`Contact Mechanisms `, and sometimes one or more +`Identifiers ` and `Categories `. + +.. seealso:: + + Parties can be found by opening the main menu item: + + |Party --> Parties|__ + + .. |Party --> Parties| replace:: :menuselection:`Party --> Parties` + __ https://demo.tryton.org/model/party.party + +Reports +------- + +.. _report-party.label: + +Labels +^^^^^^ + +The *Labels* report creates a document containing the names and postal +addresses of the selected parties. +It is preformatted so it is ready to be printed onto labels which can then be +stuck onto envelopes. + +Wizards +------- + +.. _wizard-party.check_vies: + +Check VIES +^^^^^^^^^^ + +The *Check* :abbr:`VIES (VAT Information Exchange System)` wizard uses the +European Commission's `VIES web service`_ to verify that a party's +VAT-identification number is valid. + +.. _VIES web service: https://ec.europa.eu/taxation_customs/vies/ + +.. _wizard-party.replace: + +Replace +^^^^^^^ + +This wizard is used to replace selected duplicate parties with the party that +should be used instead. +It updates all the documents that the duplicate party appears on so they point +to the party that is replacing it. +The duplicate party is then deactivated and linked to the party that replaces +it. + +.. _wizard-party.erase: + +Erase +^^^^^ + +This wizard clears out all of a party's personal data from the system +including any historized data and any resources such as attachments or notes. + +.. note:: + + If the party `Replaced ` some other parties, then the + personal data for those other parties is also erased. + +.. _model-party.identifier: + +Identifier +========== + +A party identifier is a code that is used to identify a +`Party `. +They include things like company, personal identification, social security, +tax and vat registration numbers. +Most types of identifiers are checked by Tryton before they get saved to +ensure that they are valid. + +.. _model-party.address: + +Address +======= + +Tryton provides the party *Address* concept which is used to store a +`Party's ` postal addresses. +It has fields available for each different component of an address. +Each party can have more than one address, and the preferred order of the +addresses can also be defined. + +.. seealso:: + + Party addresses can be found by opening the main menu item: + + |Party --> Addresses|__ + + .. |Party --> Addresses| replace:: :menuselection:`Party --> Addresses` + __ https://demo.tryton.org/model/party.address + +.. _model-party.address.format: + +Address Format +============== + +The *Address Formats* allow different address formats to be specified based on +`Country ` and language. +These formats are then used when postal addresses need generating. + +.. seealso:: + + You can find address formats by opening the main menu item: + + |Party --> Configuration --> Address Formats|__ + + .. |Party --> Configuration --> Address Formats| replace:: :menuselection:`Party --> Configuration --> Address Formats` + __ https://demo.tryton.org/model/party.address.format + +.. _model-party.address.subdivision_type: + +Address Subdivision Type +======================== + +*Address Subdivision Types* allow you to define, for each +`Country `, which types of +`Subdivision ` are used in their postal +addresses. + +.. seealso:: + + The address subdivision types can be accessed from the main menu item: + + |Party --> Configuration --> Address Subdivision Types|__ + + .. |Party --> Configuration --> Address Subdivision Types| replace:: :menuselection:`Party --> Configuration --> Address Subdivision Types` + __ https://demo.tryton.org/model/party.address.subdivision_type + +.. _model-party.contact_mechanism: + +Contact Mechanism +================= + +Each of the *Contact Mechanisms* represent a way in which a +`Party ` can be contacted. +These are things such as email addresses, phone numbers, websites, and so on. +In Tryton there is no limit to the number and type of contact mechanisms that +can be associated with a party. + +.. note:: + + If the Python phonenumbers_ library is installed, then any phone and + fax numbers that get entered are validated and formatted before they are + saved. + + .. _phonenumbers: https://pypi.org/project/phonenumbers/ + +.. seealso:: + + A list of contact mechanisms can be found by opening the main menu item: + + |Party --> Contact Mechanisms|__ + + .. |Party --> Contact Mechanisms| replace:: :menuselection:`Party --> Contact Mechanisms` + __ https://demo.tryton.org/model/party.contact_mechanism + +.. _model-party.category: + +Category +======== + +Party *Categories* are a flexible way of grouping `Parties ` +together. +The categories can be structured by giving them a parent category and some +sub-categories. + +.. seealso:: + + The party categories can be found by opening the main menu item: + + |Party --> Categories|__ + + .. |Party --> Categories| replace:: :menuselection:`Party --> Categories` + __ https://demo.tryton.org/model/party.category + +.. _model-party.configuration: + +Configuration +============= + +The party *Configuration* contains the settings which are used to configure the +behaviour and default values for things to do with parties. + +The default configuration will automatically generate a code for a new +`Party `. +This setting can be changed if you are `Manually assigning party codes`. + +.. seealso:: + + Configuration settings are found by opening the main menu item: + + |Party --> Configuration --> Party Configuration|__ + + .. |Party --> Configuration --> Party Configuration| replace:: :menuselection:`Party --> Configuration --> Party Configuration` + __ https://demo.tryton.org/model/party.configuration/1 diff --git a/doc/usage.rst b/doc/usage.rst new file mode 100644 index 0000000000..93261ed75b --- /dev/null +++ b/doc/usage.rst @@ -0,0 +1,120 @@ +***** +Usage +***** + +The items found under the [:menuselection:`Party`] main menu item allow you to +see and manage the parties on your system in a variety of different ways. + +.. tip:: + + A `Party ` is often referred to from documents generated + in other parts of your Tryton system, from a party you can + :guilabel:`Open related records` to quickly find documents related to that + party. + +.. _Categorising parties: + +Categorising parties +==================== + +It can be a good idea to organise the `Parties ` on Tryton +into groups. +This is especially important if you have a lot of parties on your system, +as it helps you find and manage them effectively. + +To do this you use party `Categories `. +You can create categories with any name you like, and then add the appropriate +categories to each party. +These categories can also be organised into a structure, with each category +containing one or more subcategories. +This can help you classify the parties more finely. + +For example:: + + Haulier + Local + National + International + +In this example hauliers that only deliver goods locally are added to the +``Haulier / Local`` category. +A haulier that delivers to anywhere in the country is added to both the +``Haulier / Local`` and ``Haulier / National`` categories. + +.. tip:: + + Opening a category from the tree view will show a list of the parties + that are a member of that category, or any of its subcategories. + +.. _Manually assigning party codes: + +Manually assigning party codes +============================== + +Each `Party ` that gets entered onto the system needs a +unique code. +By default Tryton will automatically generate a code for each new party using +the `Sequence ` defined in the party +`Configuration `. + +There are times when you want to manually allocate codes to parties. +Perhaps you have a policy of coding parties based on part of their name, or +maybe you have some other reason for needing to give each party a specific +code. +In these cases you need to clear out the :guilabel:`Party Sequence` defined in +the party *Configuration*. +Once you have done this, as you create the parties, you must fill in the party +code manually. + +.. _Setting a default party language: + +Setting a default party language +================================ + +When a new `Party ` is created the default language for the +party is taken from the party `Configuration `. +Providing a default language for parties can help reduce data entry, and ensure +that new parties are given a language. +This, in turn, can be important as Tryton will automatically generate reports, +such as invoices and delivery notes, in the correct language for each party. + +.. _Checking VAT numbers are valid: + +Checking VAT numbers are valid +============================== + +If the `Party ` is in the European Union you can use the +`Check VIES ` on it to check whether its VAT number +is valid or not. + +.. _Merging duplicate parties together: + +Merging duplicate parties together +================================== + +Even when you have checks in place to try and avoid creating duplicate +`Parties ` it is quite common to find this has accidentally +happened. + +If you do find some duplicates you will first need to decide which of them +you want to use from now on. + +Then, with the list of parties open, you should select all of the duplicates, +apart from the one you want to keep, and then run the +`Replace ` party wizard. +Here, you will be able to enter which party you want to keep and get Tryton to +replace the duplicates with it. + +.. _Erasing a party's personal data: + +Erasing a party's personal data +=============================== + +In order to help you comply with privacy legislation, personal data about a +person or business can be erased from the system by using the +`Erase ` party wizard. + +.. tip:: + + Tryton will stop you from accidental erasing a party that has pending + operations.