From 4ab8d6b44eb7a30d02086fef23fe97af8f05e6f1 Mon Sep 17 00:00:00 2001 From: David Harper Date: Sun, 11 Apr 2021 21:33:54 +0100 Subject: [PATCH] Improve documentation issue9601 review296281002 --- doc/conf.py | 61 ++++++++++++++++++++++++++++++ doc/design.rst | 95 +++++++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 40 ++++++-------------- doc/reference.rst | 67 +++++++++++++++++++++++++++++++++ doc/usage.rst | 28 ++++++++++++++ setup.py | 7 +++- 6 files changed, 267 insertions(+), 31 deletions(-) create mode 100644 doc/conf.py create mode 100644 doc/design.rst create mode 100644 doc/reference.rst create mode 100644 doc/usage.rst diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000000..8513b72dd2 --- /dev/null +++ b/doc/conf.py @@ -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 --git a/doc/design.rst b/doc/design.rst new file mode 100644 index 0000000000..0b746d1c28 --- /dev/null +++ b/doc/design.rst @@ -0,0 +1,95 @@ +****** +Design +****** + +The *Company Module* introduces some new concepts, and extends other existing +concepts: + +.. _model-company.company: + +Company +======= + +The *Company* is the main concept provided by the *Company Module*. +In Tryton it is a `Party ` that represents the +company, or organisation, which the users of the system are members of. + +.. seealso:: + + Companies can be found by opening the main menu item: + + |Company --> Companies|__ + + .. |Company --> Companies| replace:: :menuselection:`Company --> Companies` + __ https://demo.tryton.org/model/company.company + +.. _model-company.employee: + +Employee +======== + +The *Employee* is another important concept introduced by the *Company Module*. +In Tryton it is a `Party ` that is employed by, or +works for, one of the `Companies ` which the users are +members of. + +Employees can be organised into a structure by setting each employee's +supervisor. + +.. seealso:: + + A list of the employees for all the companies can be found from the main + menu item: + + |Company --> Employees|__ + + .. |Company --> Employees| replace:: :menuselection:`Company --> Employees` + __ https://demo.tryton.org/model/company.employee + +.. _model-res.user: + +User +==== + +The *Company Module* extends the `User ` concept so +that each user can be associated with one or more +`Companies ` and a set of +`Employees `. +From these a user then `chooses a current company and employee +`. + +This choice directly affects what data the user has access to in Tryton, +as models will often link records to a company and restrict access based on +the user's setup. + +.. seealso:: + + The *User* concept is introduced by the + :doc:`Res Module `. + +.. _model-party.party: + +Party +===== + +The *Company Module* adds an addition report that can be used with +`Parties `. + +.. seealso:: + + The *Party* concept is introduced by the :doc:`Party Module `. + +Reports +------- + +.. _report-party.letter: + +Letter +^^^^^^ + +This report is a document that can be used as the starting point for a letter +to the selected `Party `. +The letter that is created is preformatted with information about the party, +the `User ` and the user's current +`Company `. +The only thing that then needs to be added is the main contents of the letter. diff --git a/doc/index.rst b/doc/index.rst index 06379a721e..4437c04b12 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,34 +1,16 @@ +############## Company Module ############## -The company module defines the concepts of company and employee and -extend the user model. +The *Company Module* allows the business that is using Tryton to be +represented inside Tryton. +This may be a single company or multiple companies. +It also allows recording which employees belong to which companies and +what their organisational structure is. +.. toctree:: + :maxdepth: 2 -Company -******* - -The company model extends the party model and add several fields: the -currency, the list of employees and header and footer texts for -reports. There is also a parent company field which allow to setup -companies in a tree structure. The company model represent the actual -organisation the users of Tryton are members of. - - -Employee -******** - -The employee model extend the party model with a company field. The -employee model represent the actual employees of the companies defined -in Tryton. An employee can be optionally linked to a user trough the -user form. - - -User -**** - -Are added to the user model: companies, a company and an employee field. The -company field defines the current company of the user, this current company -will influence the data this user see in Tryton: most of the records that are -linked to a company will only be available for users in this very company. The -companies define which current company a user can choose. + usage + design + reference diff --git a/doc/reference.rst b/doc/reference.rst new file mode 100644 index 0000000000..9bcf19328d --- /dev/null +++ b/doc/reference.rst @@ -0,0 +1,67 @@ +************* +API Reference +************* + +Company Multi-Values +==================== + +.. class:: trytond.modules.company.model.CompanyMultiValueMixin + + A :class:`~trytond:trytond.model.MultiValueMixin` that makes it + simpler to create :class:`~trytond:trytond.model.fields.MultiValue` fields + based on the `Company ` in the context. + It does this by including the company from the context in the pattern by + default. + +.. class:: trytond.modules.company.model.CompanyValueMixin + + A :class:`~trytond:trytond.model.ValueMixin` used to store the values + of a :class:`.CompanyMultiValueMixin`. + +Employee Fields +=============== + +.. function:: trytond.modules.company.model.employee_field(string, [states], [company]) + + A function that returns a :class:`~trytond:trytond.model.fields.Many2One` + field. + This field is intended to be used to store the + `Employee ` that performed some action on the + :class:`~trytond:trytond.model.Model` that contains the + :class:`~trytond:trytond.model.fields.Field`. + + :param string: The string that is used as the label for the field. + :param states: The states in which the field will be read-only. + :param company: The name of the field that contains the company. + :return: The employee Many2One field. + +.. decorator:: trytond.modules.company.model.set_employee(field, [company]) + + Used to decorate methods which need to record the employee that last + ran them. + The specified ``field`` is updated with the + `User's ` current + `Employee `, but only if the employee works for the + ``company``. + + :param field: The name of the field to set to the user's current employee. + :param company: + The name of the field that contains the company. + Defaults to 'company'. + +.. decorator:: trytond.modules.company.model.reset_employee(*fields) + + Used to decorate methods which indicate that the document is now in a + state where the action has not yet been performed, so the + `Employee ` should be cleared from the ``fields``. + + :param fields: + The names of the fields that should have the employee removed. + +Company Reports +=============== + +.. class:: trytond.modules.company.company.CompanyReport + + A report that places the `Company ` of the record + in the header key and adds it to the context. diff --git a/doc/usage.rst b/doc/usage.rst new file mode 100644 index 0000000000..06bcc2b690 --- /dev/null +++ b/doc/usage.rst @@ -0,0 +1,28 @@ +***** +Usage +***** + +The `Companies ` and +`Employees ` on Tryton can be found under the +[:menuselection:`Company`] main menu item. + +.. tip:: + + For employees you can use the :guilabel:`Supervised by` item in + :guilabel:`Open related records` to get a list of the employees that are + supervised by the currently selected employee. + +.. _Setting your current company and employee: + +Setting your current company and employee +========================================= + +If you want to change your current `Company ` or +`Employee `, you should do this by opening your +preferences and selecting the desired company and employee. + +.. note:: + + If you try and change your current company or employee from inside the + [:menuselection:`Administration --> Users --> Users`] menu entry then it + will only change when you next login, or update your preferences. diff --git a/setup.py b/setup.py index f7b7bb1c04..094501aa2e 100755 --- a/setup.py +++ b/setup.py @@ -10,9 +10,12 @@ from setuptools import setup, find_packages 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): @@ -79,7 +82,7 @@ setup(name=name, download_url=download_url, project_urls={ "Bug Tracker": 'https://bugs.tryton.org/', - "Documentation": 'https://docs.tryton.org/', + "Documentation": 'https://docs.tryton.org/projects/modules-company/', "Forum": 'https://www.tryton.org/forum', "Source Code": 'https://hg.tryton.org/modules/company', },