changeset 3860aed8d26e in modules/account_product:default
details:
https://hg.tryton.org/modules/account_product?cmd=changeset;node=3860aed8d26e
description:
Improve documentation
issue9655
review322191002
diffstat:
doc/conf.py | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++
doc/design.rst | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
doc/index.rst | 13 +++++++---
doc/usage.rst | 33 +++++++++++++++++++++++++++++
setup.py | 8 +++++-
5 files changed, 175 insertions(+), 6 deletions(-)
diffs (220 lines):
diff -r 2558aa39e5d4 -r 3860aed8d26e doc/conf.py
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/conf.py Tue Jan 05 16:44:34 2021 +0000
@@ -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 2558aa39e5d4 -r 3860aed8d26e doc/design.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design.rst Tue Jan 05 16:44:34 2021 +0000
@@ -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 <model-product.category>`.
+Unlike standard product categories, each product can only have a single
+accounting category.
+
+.. seealso::
+
+ The `Product <product:concept-product>` concept is introduced by the
+ :doc:`Product Module <product:index>`.
+
+.. _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 <account:model-account.tax>`, and revenue and expense
+`Accounts <account:model-account.account>` 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 <product:model-product.category>` concept is
+ introduced by the :doc:`Product Module <product:index>`.
+
+.. _model-analytic_account.rule:
+
+Analytic Account Rule
+=====================
+
+The *Account Product Module* extends the *Analytic Account Rules* allowing
+`Products <concept-product>` and `Categories <model-product.category>` 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 <analytic_account:model-analytic_account.rule>`
+ concept is introduced by the
+ :doc:`Analytic Account Module <analytic_account:index>`.
diff -r 2558aa39e5d4 -r 3860aed8d26e doc/index.rst
--- a/doc/index.rst Sat Dec 19 17:08:44 2020 +0100
+++ b/doc/index.rst Tue Jan 05 16:44:34 2021 +0000
@@ -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 -r 2558aa39e5d4 -r 3860aed8d26e doc/usage.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage.rst Tue Jan 05 16:44:34 2021 +0000
@@ -0,0 +1,33 @@
+*****
+Usage
+*****
+
+.. _Using product accounting categories:
+
+Using product accounting categories
+===================================
+
+You set the accounting properties of a `Product <concept-product>` in the
+product's accounting `Category <model-product.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 <account:model-account.account>` for the revenue generated from the
+sales of clothes and the revenue generated by selling shoes.
diff -r 2558aa39e5d4 -r 3860aed8d26e setup.py
--- a/setup.py Sat Dec 19 17:08:44 2020 +0100
+++ b/setup.py Tue Jan 05 16:44:34 2021 +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,8 @@
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',
},
