Improve documentation
issue9598 review312311002
This commit is contained in:
David Harper
+61
@@ -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
|
||||
@@ -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`.
|
||||
+10
-31
@@ -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
|
||||
|
||||
@@ -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/
|
||||
@@ -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.
|
||||
@@ -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',
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user