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..83e4f683fb --- /dev/null +++ b/doc/design.rst @@ -0,0 +1,66 @@ +****** +Design +****** + +The *Account Product Module* mainly extends existing accounting and product +concepts. + +.. _concept-product: + +Product +======= + +The *Product* concept is extended with a set of methods that allow access to +the product's accounting related properties. + +Many of these properties are set in the product's accounting category. +The accounting category is a special type of +`Product Category `. +Unlike standard product categories, each product can only have a single +accounting category. + +.. seealso:: + + The `Product ` concept is introduced by the + :doc:`Product Module `. + +.. _model-product.category: + +Product Category +================ + +The *Account Product Module* allows some *Product Categories* to be marked as +accounting categories. +These product categories can have accounting properties such as +`Taxes `, and revenue and expense +`Accounts ` associated with them. + +When placing categories into a structure all the categories in the structure +must be either standard categories or accounting categories. +This means an accounting category cannot have a standard category as its +parent or as any of its subcategories. + +.. seealso:: + + The `Product Category ` concept is + introduced by the :doc:`Product Module `. + +.. _model-analytic_account.rule: + +Analytic Account Rule +===================== + +The *Account Product Module* extends the *Analytic Account Rules* allowing +`Products ` and `Categories ` to be +used as criteria by the analytic rule engine. + +.. note:: + + This feature is only available when the *Analytic Account Module* is + activated. + +.. seealso:: + + The `Analytic Account Rule ` + concept is introduced by the + :doc:`Analytic Account Module `. diff --git a/doc/index.rst b/doc/index.rst index b23a701172..ceb54567ca 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,8 +1,13 @@ +###################### Account Product Module ###################### -The account product module adds accounting on product and category. +The *Account Product Module* allows products to be associated with accounting +properties such as taxes and expense or revenue accounts. +It allows these properties to be easily managed using accounting categories. -.. note:: - If the analytic account module is activated, it also adds the product and - category as criteria for the analytic rule engine. +.. toctree:: + :maxdepth: 2 + + usage + design diff --git a/doc/usage.rst b/doc/usage.rst new file mode 100644 index 0000000000..e2e267b914 --- /dev/null +++ b/doc/usage.rst @@ -0,0 +1,33 @@ +***** +Usage +***** + +.. _Using product accounting categories: + +Using product accounting categories +=================================== + +You set the accounting properties of a `Product ` in the +product's accounting `Category `. +You can only use product categories that have been specifically marked as +accounting categories for this. + +How you decide to structure your accounting categories is very dependent on +what your products are, and how you want to group and manage them. + +In a clothes company you may have some accounting categories for:: + + Clothes + Shirts + Children + Adults + Shoes + Children + Adults + +If you were using this structure then you could define different rates of +:abbr:`VAT (Value Added Tax)`, or :abbr:`GST (Goods and Services Tax)`, +for children's and adults' items. +It would also allow you to define different revenue +`Accounts ` for the revenue generated from the +sales of clothes and the revenue generated by selling shoes. diff --git a/setup.py b/setup.py index 14d6c95009..dcfd4aa8cc 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): @@ -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-product/', "Forum": 'https://www.tryton.org/forum', "Source Code": 'https://hg.tryton.org/modules/account_product', },