Improve documentation
issue9601 review296281002
This commit is contained in:
David Harper
+61
@@ -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
|
||||
@@ -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.
|
||||
+11
-29
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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',
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user