changeset 0a79e3d9bc2a in modules/country:default
details: https://hg.tryton.org/modules/country?cmd=changeset;node=0a79e3d9bc2a
description:
Improve documentation
issue9598
review312311002
diffstat:
doc/conf.py | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
doc/design.rst | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++
doc/index.rst | 41 +++++++++-----------------------------
doc/setup.rst | 39 +++++++++++++++++++++++++++++++++++++
doc/usage.rst | 13 ++++++++++++
setup.py | 7 ++++-
6 files changed, 181 insertions(+), 33 deletions(-)
diffs (258 lines):
diff -r bcff300599a0 -r 0a79e3d9bc2a doc/conf.py
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/conf.py Wed Dec 30 16:28:18 2020 +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 bcff300599a0 -r 0a79e3d9bc2a doc/design.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/design.rst Wed Dec 30 16:28:18 2020 +0000
@@ -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 <model-country.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 <model-country.country>`, `Subdivisions <model-country.subdivision>`
+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 -r bcff300599a0 -r 0a79e3d9bc2a doc/index.rst
--- a/doc/index.rst Sat Dec 19 17:08:45 2020 +0100
+++ b/doc/index.rst Wed Dec 30 16:28:18 2020 +0000
@@ -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.
-
-
-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
-***********
+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.
-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.
+.. toctree::
+ :maxdepth: 2
-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 -r bcff300599a0 -r 0a79e3d9bc2a doc/setup.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/setup.rst Wed Dec 30 16:28:18 2020 +0000
@@ -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 <model-country.country>` and
+`Subdivisions <model-country.subdivision>`.
+
+You run it with:
+
+.. code-block:: sh
+
+ trytond_import_countries -c trytond.conf -d <database>
+
+.. _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 <model-country.zip>` in Tryton from the `GeoNames Database`_.
+It is run with:
+
+.. code-block:: bash
+
+ trytond_import_zip -c trytond.conf -d <database> <two_letter_country_code>
+
+.. _GeoNames Database: https://www.geonames.org/
diff -r bcff300599a0 -r 0a79e3d9bc2a doc/usage.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/usage.rst Wed Dec 30 16:28:18 2020 +0000
@@ -0,0 +1,13 @@
+*****
+Usage
+*****
+
+This module provides a list of `Countries <model-country.country>` and other
+reference data which is normally managed using the
+:doc:`provided scripts <setup>`.
+
+.. tip::
+
+ From a country you can :guilabel:`Open related records` and select
+ :guilabel:`Zip` to find a list of all the `Postal Codes <model-country.zip>`
+ for that country.
diff -r bcff300599a0 -r 0a79e3d9bc2a setup.py
--- a/setup.py Sat Dec 19 17:08:45 2020 +0100
+++ b/setup.py Wed Dec 30 16:28:18 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-country/',
"Forum": 'https://www.tryton.org/forum',
"Source Code": 'https://hg.tryton.org/modules/country',
},
