tryton-do/tryton
2
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Improve documentation

Browse Source 
issue9708
review308351002
This commit is contained in:
David Harper
2021-02-17 13:41:42 +00:00
parent 72ad0f5124
commit ef06bb6aa5
9 changed files with 581 additions and 163 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/conf.py
+61
View File
@@ -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
doc/configuration.rst
+28
View File
@@ -0,0 +1,28 @@
*************
Configuration
*************
The *Account Invoice Module* uses some settings from the ``[account_invoice]``
section of the :doc:`configuration file <trytond:topics/configuration>`.
.. _config-account_invoice.filestore:
``filestore``
=============
This configuration value indicates whether the cached copy of the
`Customer Invoice Reports <report-account.invoice>` should be stored in the
:py:mod:`trytond:trytond.filestore` (``True``) or the database (``False``).
The default value is: ``False``
.. _config-account_invoice.store_prefix:
``store_prefix``
================
This is the prefix to use with the :py:mod:`trytond:trytond.filestore`.
This value is only used when the
`filestore <config-account_invoice.filestore>` setting is in use.
The default value is: ``None``
doc/design.rst
+198
View File
@@ -0,0 +1,198 @@
Design
******
The *Account Invoice Module* adds some new concepts and extends some existing
concepts.
.. _model-account.invoice:
Invoice
=======
The main concept introduced by the *Account Invoice Module* is the *Invoice*.
This contains details of a purchase, or sales, transaction between the
`Company <company:model-company.company>` and another
`Party <party:model-party.party>`.
Each invoice has a type that indicates whether it is an invoice from a
supplier, or to a customer.
Credit notes are represented by invoices with negative totals.
Additional information is also stored for each invoice, including things like
a unique `Sequence <model-account.fiscalyear.invoice_sequence>` number,
invoice, accounting and payment term dates,
`Payment Terms <model-account.invoice.payment_term>`,
`Tax Identifiers <party:model-party.identifier>`,
`Currency <currency:model-currency.currency>` information,
the customer's or supplier's invoice `Address <party:model-party.address>`,
and other descriptions and reference numbers.
An invoice is made up from one, or more, invoice lines.
Most lines normally contain information about the items that were bought or
sold, including information about the `Products <product:concept-product>`,
quantities, `Taxes <account:model-account.tax>` and prices that make up the
transaction.
There are also some types of line that add other information like titles,
descriptions or subtotals.
The taxes that are included on an invoice are calculated from the tax
amounts for each of the invoice's lines.
These amounts are rounded at either the line or invoice level depending on the
setting in the `Account Configuration <account:model-account.configuration>`.
Additional taxes can be manually added to the invoice when required.
It is also possible to change calculated tax amounts, although these changes
get overwritten if the invoice's tax amounts get recalculated.
When an invoice is processed an `Account Move <account:model-account.move>` is
automatically created for it.
This account move records the transaction represented by the invoice and
places the total in the specified payable or receivable
`Account <account:model-account.account>`.
.. note::
For customer invoices the `Invoice Report <report-account.invoice>` is
generated and stored at the point when the invoice is posted.
.. seealso::
Customer invoices and credit notes can be seen by opening the main menu
item:
|Financial --> Invoices --> Customer Invoices|__
.. |Financial --> Invoices --> Customer Invoices| replace:: :menuselection:`Financial --> Invoices --> Customer Invoices`
__ https://demo.tryton.org/model/account.invoice;domain=[["type"%2C"%3D"%2C"out"]]
Supplier invoices and credit note are available from the main menu item:
|Financial --> Invoices --> Supplier Invoices|__
.. |Financial --> Invoices --> Supplier Invoices| replace:: :menuselection:`Financial --> Invoices --> Supplier Invoices`
__ https://demo.tryton.org/model/account.invoice;domain=[["type"%2C"%3D"%2C"in"]]
Wizards
-------
.. _wizard-account.invoice.pay:
Pay Invoice
^^^^^^^^^^^
The *Pay Invoice* wizard allows a cash payment for an invoice to be registered
against the invoice.
It uses the values from an
`Invoice Payment Method <model-account.invoice.payment.method>` when creating
the `Account Move <account:model-account.move>`.
The wizard supports partial payments, and can also be used to write-off some
of the invoice amount.
.. _wizard-account.invoice.credit:
Credit Invoice
^^^^^^^^^^^^^^
The *Credit Invoice* wizard enables a credit note to be raised for the
selected invoices.
For customer invoices that are posted, the wizard allows the invoice to be
credited with a refund.
When this is done the credit note is automatically posted and the invoice is
cancelled.
Reports
-------
.. _report-account.invoice:
Invoice
^^^^^^^
The *Invoice* report is used to output a hard copy of the invoice or credit
note.
It includes all the information that is needed in order to send the document
to a customer or supplier.
.. _model-account.invoice.payment.method:
Invoice Payment Method
======================
The concept of an *Invoice Payment Method* brings together an
`Account Journal <account:model-account.journal>`,
a debit `Account <account:model-account.account>` and a credit account.
This is normally used during the `Pay Invoice <wizard-account.invoice.pay>`
wizard.
.. seealso::
Invoice payment methods can be found using the main menu item:
|Financial --> Configuration --> Journals --> Invoice Payment Methods|__
.. |Financial --> Configuration --> Journals --> Invoice Payment Methods| replace:: :menuselection:`Financial --> Configuration --> Journals --> Invoice Payment Methods`
__ https://demo.tryton.org/model/account.invoice.payment.method
.. _model-account.fiscalyear.invoice_sequence:
Fiscal Year Invoice Sequence
============================
The *Fiscal Year Invoice Sequence* concept allows a set of
`Sequences <trytond:model-ir.sequence.strict>` to be defined for use with
`Invoices <model-account.invoice>`.
It allows different sequences to be used for each of the different types of
invoices and credit notes.
It also allows the use of different sequences for each accounting
`Period <account:model-account.period>`.
.. seealso::
The fiscal year sequences are defined in the
`Fiscal Year <account:model-account.fiscalyear>`.
.. _model-account.invoice.payment_term:
Payment Term
============
The *Payment Term* stores the method that is used to calculate an
`Invoice's <model-account.invoice>` payment due dates.
An invoice may be due for payment in full on a particular day, or may become
due for payment over time in parts.
To allow for this each payment term is made up of one or more lines.
Each line defines an amount that should be paid, and when that payment is
expected.
The amounts can be defined as either fixed amounts, percentages, or a
remainder.
.. seealso::
Payment terms are create and managed from the main menu item:
|Financial --> Configuration --> Payment Terms --> Payment Terms|__
.. |Financial --> Configuration --> Payment Terms --> Payment Terms| replace:: :menuselection:`Financial --> Configuration --> Payment Terms --> Payment Terms`
__ https://demo.tryton.org/model/account.invoice.payment_term
Wizards
-------
.. _wizard-account.invoice.payment_term.test:
Test Payment Term
^^^^^^^^^^^^^^^^^
The *Test Payment Term* wizard shows how a specific invoice amount is
broken down for a particular
`Payment Term <model-account.invoice.payment_term>`.
It allows a date and an amount to be entered and then calculates the due dates
and amounts for each payment that will be required for that payment term.
.. seealso::
Payment terms can be tested out by opening the main menu item:
:menuselection:`Financial --> Configuration --> Payment Terms --> Test Payment Term`
doc/index.rst
+9 -161
View File
@@ -1,166 +1,14 @@
######################
Account Invoice Module
######################
The account_invoice module adds the invoice, payment term.
The *Account Invoice Module* adds the concept of invoicing to Tryton.
It allows the creation of customer and supplier invoices, and can handle the
payment terms related to the invoices and show when they have been paid.
Invoice
*******
.. toctree::
:maxdepth: 2
There are 4 types of invoice: *Invoice*, *Supplier Invoice*, *Credit Note* and
*Supplier Credit Note*. An invoice can be in *Draft*, *Validated*, *Posted*,
*Paid* or *Cancelled*.
- Company: The company for which the invoice is created.
- Tax Identifier: The tax identifier that will be printed on the invoice
(By default the first tax identifier of the company).
- Number: The invoice number set on validation for supplier invoices and on
posting for others using the sequence defined on the fiscalyear.
- Reference: The optional external reference of the invoice.
- Party: The party for which or from which the invoice is issued.
- Invoice Address: The address of the party.
- Party Tax Identifier: The tax identifier of the party.
- Description: An optional description of the invoice.
- Comment: A text fields to add custom comments.
- Invoice Date: The date of the invoice. It is set on posting the invoice if not.
- Accounting Date: The date to use for accounting if set otherwise it is the
invoice date.
- Currency: The currency of the invoice.
- Journal: The journal on which the accounting must be booked.
- Account: The payable or receivable account.
- Payment Term: The payment term to apply for the invoice
(default value comes from the party).
- Lines: The lines invoiced.
- Taxes: The taxes related to the lines.
- Untaxed, Tax, Total Amount: The amounts computed by the invoice.
- Move: The accounting move created by the invoice on validation for supplier
invoices and on posting for others.
- Cancel Move: The accounting move created to cancel a posted invoice.
The *Invoice* report is stored when the invoice is posted and thus it is always
the same that is returned for consistency.
A wizard allow to register a cash payment directly on the invoice. The payment
could be partial or with write-off.
An other wizard allow to create a credit note from the invoice. If the option
to refund is checked, the original invoice will be cancelled by the credit note.
Invoice Line
************
There are 4 types of lines: *Line*, *Subtotal*, *Title*, *Comment*.
The *Line* are composed of:
- Product: An optional reference to the product to invoice.
- Account: The account to book the expense or revenue.
- Quantity: The quantity invoiced.
- Unit: The unit of measure in which is expressed the quantity.
- Unit Price: The unit price of the quantity in the currency of the invoice.
- Amount: The amount of the line (Unit Price multiplied by Quantity).
- Description: The description of the product or the line.
- Note: A text fields to add custom comments.
- Taxes: The taxes to apply to the amount of the line.
Invoice Tax
***********
It groups the taxes of all the lines.
The rounding of the taxes is defined in the accounting configuration and can
be: *Per Document* or *Per Line*.
- Description: The description of the tax.
- Account: The account on which the tax is booked.
- Base: The base amount on which the tax is computed.
- Base Code: The *Tax Code* to record the base amount.
- Base Sign: The sign used to record the base amount on the tax code.
- Amount: The amount of the tax.
- Tax Code: The *Tax Code* to record the tax amount.
- Tax Sing: The sign used to record the tax amount on the tax code.
- Tax: The tax used for computation.
- Manual: A boolean to define manual tax
(which is not linked to an invoice line).
Payment Term
************
It defines the maximum dates of how an due amount should be paid.
- Name: The name of the term.
- Description: The long description of the term.
- Lines:
- Relative Deltas:
- Day: The day of the month.
- Month: The month of the year.
- Day of the Week: One of the week day.
- Months: The number of months to add.
- Weeks: The number of weeks to add.
- Days: The number of days to add.
- Type:
- *Fixed*:
- Amount: The maximum fixed amount to pay at this date.
- Currency: The currency of the amount.
- *Percentage on Remainder*:
- Ratio: The ratio to use on the remainder amount.
- Divisor: The reversed ratio.
- *Percentage on Total*:
- Ratio: The ratio to use on the total amount.
- Divisor: The reversed ratio.
- *Remainder*
The computation of relative delta is based on the `python-dateutil library`_.
The payment term create a term for each line as far as there is still a
remainder amount.
A wizard is provided to test the behaviour of the payment term. It display
computed terms base on an amount and a date.
.. note:: The last line of payment term must be a remainder.
Payment Method
**************
The payment options available when paying an invoice. It has the following
fields:
- Name
- Company
- Journal: Will be used for creating the payment move
- Credit Account and Debit Account: The accounts used for the payment move
depending on the amount sign.
- Active: A checkbox that allow to disable the payment method.
Fiscal Year Sequences
*********************
The sequence used to compute the invoice number is retrieved from the
fiscalyear sequences model. At least one record must be defined for each
fiscalyear. Additional criteria can be used like:
* By period
Configuration
*************
The account_invoice module uses the section `account_invoice` to retrieve some
parameters:
- `filestore`: a boolean value to store invoice report cache in the FileStore.
The default value is `False`.
- `store_prefix`: the prefix to use with the FileStore. The default value is
`None`.
.. _`python-dateutil library`: http://labix.org/python-dateutil#head-72c4689ec5608067d118b9143cef6bdffb6dad4e
usage/index
configuration
design
doc/usage/amend.rst
+57
View File
@@ -0,0 +1,57 @@
.. _Correcting invoices:
Correcting invoices
===================
`Invoices <model-account.invoice>` can only be changed when they are in a
draft state.
Once an invoice has been posted you will need to
`credit it <Crediting customers and suppliers>`, and reissue it by creating
a new invoice with the correct information on.
.. tip::
If you need to create a new invoice that is almost the same as an existing
invoice you can use the :guilabel:`Duplicate` item from the form's menu to
copy the existing invoice.
The duplicate invoice will be created in a draft state, so you can change
anything that was incorrect.
.. _Cancelling invoices:
Cancelling invoices
===================
Most `Invoices <model-account.invoice>` can be cancelled up to the point they
are paid.
Once they are paid you need to credit them instead.
You do this by `creating a credit note <Crediting customers and suppliers>`
for them.
.. note::
Legislation may not allow you to cancel a posted customer invoice.
If this is the case, then you should instead create a credit note for it.
You can allow posted invoices to be credited by changing the setting in your
`Company <company:model-company.company>`.
Cancelling an invoice removes its effect on your accounts by either removing
its `Account Move <account:model-account.move>`, or negating it with a
cancelling move.
.. _Crediting customers and suppliers:
Crediting customers and suppliers
=================================
In Tryton you credit customers and suppliers by creating *Credit Notes*.
These are just `Invoices <model-account.invoice>` with negative totals.
You can create a credit note manually or create one based on an existing
invoice.
To credit existing invoices you must first select the invoices that need to
be credited.
Next you run the `Credit <wizard-account.invoice.credit>` invoice wizard from
the :guilabel:`Launch action` menu.
doc/usage/index.rst
+13
View File
@@ -0,0 +1,13 @@
*****
Usage
*****
Customer and supplier invoices can be found under the
:menuselection:`Financial --> Invoices` menu item.
.. toctree::
:maxdepth: 1
prepare
process
amend
doc/usage/prepare.rst
+105
View File
@@ -0,0 +1,105 @@
.. _Setting a party's invoice address:
Setting a party's invoice address
=================================
Tryton lets you mark which `Addresses <party:model-party.address>`, and
also `Contact Mechanisms <party:model-party.contact_mechanism>`, should be
used with `Invoices <model-account.invoice>`.
.. tip::
If you don't set an invoice addresses or contact mechanisms, then the
party's first address or contact mechanism is used.
.. _Setting default accounts:
Setting default accounts
========================
Receivable and payable
^^^^^^^^^^^^^^^^^^^^^^
You can set the default receivable and payable
`Accounts <account:model-account.account>` that are used for the invoice
totals, for customers and suppliers respectively, in the
`Account Configuration <account:model-account.configuration>`.
A `Party <party:model-party.party>` can override these default accounts
and normally allows you to set which accounts you want to use with that party.
Revenue and Expense
^^^^^^^^^^^^^^^^^^^
The default revenue and expense accounts for the
`Products <product:concept-product>` that appear on the invoice's lines are
also set in the *Account Configuration*.
These default accounts are used unless the product overrides them.
Normally this is done by setting the revenue and expense accounts in the
product's `Account Category <account_product:model-product.category>`.
Tax
^^^
The accounts that are used for any `Taxes <account:model-account.tax>` are set
on the taxes themselves.
.. _Creating payment terms:
Creating payment terms
======================
Any `Payment Term <model-account.invoice.payment_term>` that you want to use
must be created before you can use them.
You can do this at the point where you need to use them, or beforehand.
The payment term defines when payment for an `Invoice <model-account.invoice>`
is expected.
Each part of a payment term allows you specify an amount and a date by adding
months, weeks and days to the invoice date, and also setting a day of the
month, month of the year, or day of the week that the payment is due.
This calculation is done using |python-dateutil's relativedeltas|__.
.. |python-dateutil's relativedeltas| replace:: python-dateutil's ``relativedeltas``
__ https://dateutil.readthedocs.io/en/stable/relativedelta.html
One payment term that is sometimes used is "30 Days", this means you expect
payment 30 days after the date on the invoice.
In Tryton you would set this up by creating a payment term like this::
Name: 30 Days
Line 1:
Type: Remainder
Number of Days: 30
You may want to request payment at the end of the month that the invoice
was raised in, you can do this with::
Name: End Of Month
Line 1:
Type: Remainder
Day of Month: 31
You can also define payment terms in which the payment is expected in stages.
For example, to require a fixed amount of 100 immediately, then 50% of what
is left after 7 days and the remaining amount after 14 days you would use::
Name: Payment in Stages
Line 1:
Type: Fixed
Amount: 100
Number of Days: 0
Line 2:
Type: Percentage on Remainder
Ratio: 50%
Number of Days: 7
Line 3:
Type: Remainder
Number of Days: 14
.. tip::
For complex payment terms if you want to check what dates and amounts
it will generate you can try it out using the
`Test Payment Term <wizard-account.invoice.payment_term.test>` wizard.
doc/usage/process.rst
+104
View File
@@ -0,0 +1,104 @@
.. _Invoicing customers:
Invoicing customers
===================
If your `Company <company:model-company.company>` has sold some things and
you want to issue an invoice to the customer, then in Tryton you need to
create a customer `Invoice <model-account.invoice>`.
.. tip::
Tryton provides additional modules that can be used to automatically create
customer invoices.
These modules normally create draft invoices for you with almost all the
data already filled in.
If you need to manually create a new customer `Invoice <model-account.invoice>`
you will need to enter in a few details such as the name of the
`Party <party:model-party.party>`, the
`Currency <currency:model-currency.currency>` and the lines that make up the
invoice.
Most of the other fields are optional or have sensible default values.
.. tip::
If the invoice you want to create is almost the same as an existing
invoice then you can use the :guilabel:`Duplicate` item from the form's
menu to avoid creating it from scratch.
You should post the invoice before you issue it to your customer.
Once the invoice has been posted the `Invoice report <report-account.invoice>`
can be printed out or saved, and sent to your customer.
.. tip::
The *Invoice report* generates a *Pro forma invoice* for invoices that are
validated, but not yet posted.
.. tip::
The *Invoice report* is saved for posted customer invoices.
This means that every time you print it you will get an identical copy
of it.
.. _Handling supplier invoices:
Handling supplier invoices
==========================
Supplier `Invoices <model-account.invoice>` are issued to your
`Company <company:model-company.company>` by a supplier for things that you
purchase.
For each invoice that you receive you need a new supplier invoice in Tryton.
.. tip::
Tryton provides additional modules that automatically create, or help
create, supplier invoices.
If you are using these modules then the supplier invoices or invoice lines
are often automatically created for you.
.. tip::
If the invoice you want to create is almost the same as an existing
invoice then you can use the :guilabel:`Duplicate` item from the form's
menu to avoid creating it from scratch.
Once you have created, or found, the supplier invoice on Tryton you should
check that it matches the one provided by the supplier.
If you see any differences due to the way the taxes have been calculated
then these can be fixed once all the lines are entered.
You can do this by manually changing the tax amounts on the supplier invoice
on Tryton.
When you are happy the supplier invoice is correct, and it matches the one
on Tryton you can post it.
.. _Paying an invoice:
Paying an invoice
=================
Each `Invoice <model-account.invoice>` tracks how much still needs to be paid.
Once an invoice has been fully paid it automatically updates its state to
indicate that it is now paid.
If you are manually registering payments against invoices, then you can use
the invoice's :guilabel:`Pay` button to run the
`Pay Invoice <wizard-account.invoice.pay>` wizard and register a cash payment
against the invoice.
When doing this you will need to have already setup an appropriate
`Invoice Payment Method <model-account.invoice.payment.method>`.
This then makes it easy to use consistent
`Journals <account:model-account.journal>` and
`Accounts <account:model-account.account>` when manually entering payments.
.. note::
Some of the other accounting modules allow you to automatically register
payments against invoices.
So, if you are using those modules you will not normally need to do this
manually.
setup.py
+6 -2
View File
@@ -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):
@@ -80,7 +83,8 @@ 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-account-invoice/',
"Forum": 'https://www.tryton.org/forum',
"Source Code": 'https://hg.tryton.org/modules/account_invoice',
},