Improve documentation

issue9655
review322191002

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

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 <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>`.

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

doc/usage.rst

@@ -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.

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',
         },