changeset 4e7e648ccf7a in modules/company:default
details: https://hg.tryton.org/modules/company?cmd=changeset&node=4e7e648ccf7a
description:
Improve documentation
issue9601
review296281002
diffstat:
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(-)
diffs (342 lines):
diff -r 19959855edb6 -r 4e7e648ccf7a doc/conf.py
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/conf.py Sun Apr 11 21:33:54 2021 +0100
@@ -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 19959855edb6 -r 4e7e648ccf7a doc/design.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design.rst Sun Apr 11 21:33:54 2021 +0100
@@ -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 <party:model-party.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 <party:model-party.party>` that is employed by, or
+works for, one of the `Companies <model-company.company>` 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 <trytond:model-res.user>` concept so
+that each user can be associated with one or more
+`Companies <model-company.company>` and a set of
+`Employees <model-company.employee>`.
+From these a user then `chooses a current company and employee
+<Setting your 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 <trytond:modules/res/index>`.
+
+.. _model-party.party:
+
+Party
+=====
+
+The *Company Module* adds an addition report that can be used with
+`Parties <party:model-party.party>`.
+
+.. seealso::
+
+ The *Party* concept is introduced by the :doc:`Party Module <party:index>`.
+
+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 <party:model-party.party>`.
+The letter that is created is preformatted with information about the party,
+the `User <trytond:model-res.user>` and the user's current
+`Company <model-company.company>`.
+The only thing that then needs to be added is the main contents of the letter.
diff -r 19959855edb6 -r 4e7e648ccf7a doc/index.rst
--- a/doc/index.rst Sun Apr 11 18:37:41 2021 +0200
+++ b/doc/index.rst Sun Apr 11 21:33:54 2021 +0100
@@ -1,34 +1,16 @@
+##############
Company Module
##############
-The company module defines the concepts of company and employee and
-extend the user model.
-
-
-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.
-
+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.
-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.
-
+.. toctree::
+ :maxdepth: 2
-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 -r 19959855edb6 -r 4e7e648ccf7a doc/reference.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/reference.rst Sun Apr 11 21:33:54 2021 +0100
@@ -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 <model-company.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 <model-company.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 <trytond:model-res.user>` current
+ `Employee <model-company.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 <model-company.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 <model-company.company>` of the record
+ in the header key and adds it to the context.
diff -r 19959855edb6 -r 4e7e648ccf7a doc/usage.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage.rst Sun Apr 11 21:33:54 2021 +0100
@@ -0,0 +1,28 @@
+*****
+Usage
+*****
+
+The `Companies <model-company.company>` and
+`Employees <model-company.employee>` 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 <model-company.company>` or
+`Employee <model-company.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 -r 19959855edb6 -r 4e7e648ccf7a setup.py
--- a/setup.py Sun Apr 11 18:37:41 2021 +0200
+++ b/setup.py Sun Apr 11 21:33:54 2021 +0100
@@ -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):
@@ -79,7 +82,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-company/',
"Forum": 'https://www.tryton.org/forum',
"Source Code": 'https://hg.tryton.org/modules/company',
},
