changeset 95bc22323d2f in modules/currency:default
details: https://hg.tryton.org/modules/currency?cmd=changeset;node=95bc22323d2f
description:
Improve documentation
issue9124
COLLABORATOR=d...@libateq.org
review293171005
diffstat:
doc/conf.py | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
doc/design.rst | 39 +++++++++++++++++++++++++++++++++++++
doc/index.rst | 36 +++++++++-------------------------
doc/setup.rst | 20 +++++++++++++++++++
doc/usage.rst | 37 +++++++++++++++++++++++++++++++++++
setup.py | 7 ++++-
6 files changed, 171 insertions(+), 28 deletions(-)
diffs (243 lines):
diff -r 6cb21d12e299 -r 95bc22323d2f doc/conf.py
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/conf.py Tue Dec 15 12:27:38 2020 +0000
@@ -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 -r 6cb21d12e299 -r 95bc22323d2f doc/design.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design.rst Tue Dec 15 12:27:38 2020 +0000
@@ -0,0 +1,39 @@
+******
+Design
+******
+
+The *Currency Module* introduces the following concepts:
+
+.. _model-currency.currency:
+
+Currency
+========
+
+Each currency of interest is represented in Tryton by a currency record.
+These currencies are used together with a numeric value to represent an amount
+of money.
+Tryton can convert monetary amounts from one currency to another using the
+exchange `Rate <model-currency.currency.rate>` for a given date.
+This is important for multi-currency transactions, and if you want to manage
+money in a range of different currencies.
+
+.. seealso::
+
+ Currencies can be found by opening the main menu item:
+
+ |Currency --> Currencies|__
+
+ .. |Currency --> Currencies| replace:: :menuselection:`Currency -->
Currencies`
+ __ https://demo.tryton.org/model/currency.currency
+
+.. _model-currency.currency.rate:
+
+Rate
+====
+
+The exchange rates that are used when converting money between
+`Currencies <model-currency.currency>` are saved next to their associated
+currencies.
+As exchange rates vary over time they are stored along with the date from
+when they apply.
+All exchange rates are relative with respect to each other.
diff -r 6cb21d12e299 -r 95bc22323d2f doc/index.rst
--- a/doc/index.rst Tue Dec 15 11:42:55 2020 +0000
+++ b/doc/index.rst Tue Dec 15 12:27:38 2020 +0000
@@ -1,31 +1,15 @@
+###############
Currency Module
###############
-The currency module defines the concepts of currency and rate.
-
-
-Currency
-********
-
-A currency is defined by a name, a symbol, a code, a list of rates, a
-rounding factor and some formatting properties: the digits to be
-displayed after the decimal separator, the way the numbers should be
-grouped, the thousands separator, the decimal separator, the positive
-and negative signs and their positions, the currency symbol position
-and if it should be separated from the number by a space.
-
+The *Currency Module* defines the basics needed to work with currencies in
+Tryton including a list of standard currencies.
+It is also possible to define the rates used to convert amounts between
+different currencies.
-Rate
-****
-
-A rate is defined by a date and a numeric value. The date gives the
-time from which this rate is correct. All rates are defined implicitly
-with respect to the same currency (the one whose rate is 1).
+.. toctree::
+ :maxdepth: 2
-Scripts
-*******
-
-There is a scripts:
-
- * `trytond_import_currencies` to create and update currencies from the ISO
- database.
+ setup
+ usage
+ design
diff -r 6cb21d12e299 -r 95bc22323d2f doc/setup.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/setup.rst Tue Dec 15 12:27:38 2020 +0000
@@ -0,0 +1,20 @@
+*****
+Setup
+*****
+
+On activation, the module does not create any currency records.
+It is possible to load them from the ISO database.
+
+.. _Loading and updating currencies:
+
+Loading and updating currencies
+===============================
+
+There is a script called :command:`trytond_import_currencies` that creates and
+updates `Currencies <model-currency.currency>`.
+
+You can run it with:
+
+.. code-block:: bash
+
+ trytond_import_currencies -c trytond.conf -d <database>
diff -r 6cb21d12e299 -r 95bc22323d2f doc/usage.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage.rst Tue Dec 15 12:27:38 2020 +0000
@@ -0,0 +1,37 @@
+*****
+Usage
+*****
+
+In order to perform conversions between currencies exchange rates must be
+defined.
+
+.. _Setting currency exchange rates:
+
+Setting currency exchange rates
+===============================
+
+All the `Currency <model-currency.currency>` values are relative.
+Best practice is to define which currency you want to use as the base currency
+by setting its exchange `Rate <model-currency.currency.rate>` to 1 for the
+date when it is first used.
+Then the rates of all other currencies are set as a multiplier of the base
+currency.
+
+In order to set an exchange rate of ``1.0 EUR = 1.1222 USD`` for the 1st of
+January the following records should be created:
+
+* A rate of ``1.0`` for the :abbr:`EUR (Euro)` currency with the 1st of
+ January as the date.
+* A rate of ``1.1222`` for the :abbr:`USD (US Dollar)` currency with the 1st
+ of January as the date.
+
+If you then wanted to update the exchange rate to ``1.0 EUR = 1.1034 USD`` for
+the 15th of January you just need to set the rate on the USD currency to
+``1.1034`` for that date.
+
+.. note::
+
+ In this example, as there isn't any rate set for the dates between the 2nd
+ and 14th of January the last available rate will be used.
+ Here this rate would be ``1.1222`` as this was the rate set for the 1st of
+ January.
diff -r 6cb21d12e299 -r 95bc22323d2f setup.py
--- a/setup.py Tue Dec 15 11:42:55 2020 +0000
+++ b/setup.py Tue Dec 15 12:27:38 2020 +0000
@@ -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):
@@ -80,7 +83,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-currency/',
"Forum": 'https://www.tryton.org/forum',
"Source Code": 'https://hg.tryton.org/modules/currency',
},
