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..3c55e3a4d7 --- /dev/null +++ b/doc/design.rst @@ -0,0 +1,53 @@ +****** +Design +****** + +The *Country Module* introduces the following concepts: + +.. _model-country.country: + +Country +======= + +This is the top level concept provided by the *Country Module*. +Each country record in Tryton represents a specific country, political state +or nation. + +The ISO 3166 standard defines the codes and names of countries and is used when +`Loading and updating countries and subdivisions`. + +.. seealso:: + + Countries can be found under the main menu entry: + + |Administration --> Countries|__ + + .. |Administration --> Countries| replace:: :menuselection:`Administration --> Countries` + __ https://demo.tryton.org/model/country.country + +.. _model-country.subdivision: + +Subdivision +=========== + +The *Subdivision* of a `Country ` represents a well +defined area of that country. +Subdivisions can be any size, ranging from regions, provinces, states, and +counties down to municipalities, cities and boroughs. + +The ISO 3166-2 standard defines codes and names for country subdivisions. +These are automatically loaded and updated along with the countries. + +.. _model-country.zip: + +Zip +=== + +The *Zip* concept is used to store postal codes, and their relationship to +`Countries `, `Subdivisions ` +and cities. +Depending on the country they relate to these codes are known locally as +either postcodes, post codes, :abbr:`PIN (Postal Index Number)` or +:abbr:`ZIP (Zone Improvement Plan)` codes. + +A script is provided for `loading and updating postal codes`. diff --git a/doc/index.rst b/doc/index.rst index 7030e7c595..e26241a418 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,36 +1,15 @@ +############## Country Module ############## -The country module defines the concepts of country and subdivision and -comes preloaded with the ISO 3166 list of countries and subdivisions -thanks to the pycountry module. +The *Country Module* provides the basic features needed to handle data +related to countries, their subdivisions, and their postal codes. +It also provides some scripts that are used to load standard countries, +subdivisions, and selected countries' postal codes into Tryton. +.. toctree:: + :maxdepth: 2 -Country -******* - -A country is defined by the full name of the country, a code (the ISO -country code made of two chars) and the list of subdivisions. - - -Subdivision -*********** - -A subdivision is defined by a name, a code and a type (e.g, Capital -City, Province, Emirate, etc) - - -Zip -*** - -A zip links a zip code of a country to a city. - -Scripts -******* - -There are two scripts: - -* `trytond_import_countries` to create and update countries and - subdivisions from the ISO database. - -* `trytond_import_zip` to create zips by country from the geonames database. + setup + usage + design diff --git a/doc/setup.rst b/doc/setup.rst new file mode 100644 index 0000000000..bc82113fe2 --- /dev/null +++ b/doc/setup.rst @@ -0,0 +1,39 @@ +***** +Setup +***** + +When the *Country Module* is activated it does not create any country, +subdivision or postal code records. +You do this using the provided scripts. + +.. _Loading and updating countries and subdivisions: + +Loading and updating countries and subdivisions +=============================================== + +The :command:`trytond_import_countries` script loads and updates Tryton with +the `ISO 3166`_ list of `Countries ` and +`Subdivisions `. + +You run it with: + +.. code-block:: sh + + trytond_import_countries -c trytond.conf -d + +.. _ISO 3166: https://en.wikipedia.org/wiki/ISO_3166 + +.. _Loading and updating postal codes: + +Loading and updating postal codes +================================= + +You can use the :command:`trytond_import_zip` script to load and update the +`Postal Codes ` in Tryton from the `GeoNames Database`_. +It is run with: + +.. code-block:: bash + + trytond_import_zip -c trytond.conf -d + +.. _GeoNames Database: https://www.geonames.org/ diff --git a/doc/usage.rst b/doc/usage.rst new file mode 100644 index 0000000000..eb3ea77471 --- /dev/null +++ b/doc/usage.rst @@ -0,0 +1,13 @@ +***** +Usage +***** + +This module provides a list of `Countries ` and other +reference data which is normally managed using the +:doc:`provided scripts `. + +.. tip:: + + From a country you can :guilabel:`Open related records` and select + :guilabel:`Zip` to find a list of all the `Postal Codes ` + for that country. diff --git a/setup.py b/setup.py index 81c4757c36..ecc63ac630 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,7 @@ 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-country/', "Forum": 'https://www.tryton.org/forum', "Source Code": 'https://hg.tryton.org/modules/country', },