From 9f11b9fbfcbffabd9add960beb3b2c4d2bb9918e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Krier?= Date: Sun, 4 Jun 2023 11:05:31 +0200 Subject: [PATCH] Update documentation of stock package shipping UPS --- modules/stock_package_shipping_ups/CHANGELOG | 12 +++++ .../doc/configuration.rst | 17 +++++++ .../stock_package_shipping_ups/doc/design.rst | 51 +++++++++++++++++++ .../stock_package_shipping_ups/doc/index.rst | 47 ++++------------- .../doc/releases.rst | 7 +++ .../stock_package_shipping_ups/doc/usage.rst | 24 +++++++++ modules/stock_package_shipping_ups/setup.py | 9 +++- modules/stock_package_shipping_ups/tryton.cfg | 1 + 8 files changed, 130 insertions(+), 38 deletions(-) create mode 100644 modules/stock_package_shipping_ups/doc/configuration.rst create mode 100644 modules/stock_package_shipping_ups/doc/design.rst create mode 100644 modules/stock_package_shipping_ups/doc/releases.rst create mode 100644 modules/stock_package_shipping_ups/doc/usage.rst diff --git a/modules/stock_package_shipping_ups/CHANGELOG b/modules/stock_package_shipping_ups/CHANGELOG index abc2a6e701..138f0c6cee 100644 --- a/modules/stock_package_shipping_ups/CHANGELOG +++ b/modules/stock_package_shipping_ups/CHANGELOG @@ -13,43 +13,55 @@ Version 6.6.0 - 2022-10-31 * Update service types Version 6.4.0 - 2022-05-02 +-------------------------- * Bug fixes (see mercurial logs for details) * Add notification service option * Add support for Python 3.10 * Remove support for Python 3.6 Version 6.2.0 - 2021-11-01 +-------------------------- * Bug fixes (see mercurial logs for details) Version 6.0.0 - 2021-05-03 +-------------------------- * Bug fixes (see mercurial logs for details) Version 5.8.0 - 2020-11-02 +-------------------------- * Bug fixes (see mercurial logs for details) * Remove support for Python 3.5 Version 5.6.0 - 2020-05-04 +-------------------------- * Bug fixes (see mercurial logs for details) Version 5.4.0 - 2019-11-04 +-------------------------- * Bug fixes (see mercurial logs for details) Version 5.2.0 - 2019-05-06 +-------------------------- * Bug fixes (see mercurial logs for details) Version 5.0.0 - 2018-10-01 +-------------------------- * Bug fixes (see mercurial logs for details) * Remove support for Python 2.7 Version 4.8.0 - 2018-04-23 +-------------------------- * Bug fixes (see mercurial logs for details) Version 4.6.0 - 2017-10-30 +-------------------------- * Bug fixes (see mercurial logs for details) Version 4.4.0 - 2017-05-01 +-------------------------- * Bug fixes (see mercurial logs for details) * Use total weight of package Version 4.2.0 - 2016-11-28 +-------------------------- * Initial release diff --git a/modules/stock_package_shipping_ups/doc/configuration.rst b/modules/stock_package_shipping_ups/doc/configuration.rst new file mode 100644 index 0000000000..3bfc676392 --- /dev/null +++ b/modules/stock_package_shipping_ups/doc/configuration.rst @@ -0,0 +1,17 @@ +************* +Configuration +************* + +The *Stock Package Shipping UPS Module* uses values from the settings in the +``[stock_package_shipping_ups]`` section of the :doc:`configuration file +`. + +.. _config-stock_package_shipping_ups.requests_timeout: + +``requests_timeout`` +==================== + +The ``requests_timeout`` defines the time in seconds to wait for the UPS APIs +answer before failing. + +The default value is: ``300`` diff --git a/modules/stock_package_shipping_ups/doc/design.rst b/modules/stock_package_shipping_ups/doc/design.rst new file mode 100644 index 0000000000..4ee23ec72d --- /dev/null +++ b/modules/stock_package_shipping_ups/doc/design.rst @@ -0,0 +1,51 @@ +****** +Design +****** + +The *Stock Package Shipping UPS Module* introduces some new concepts. + +.. _model-carrier: + +Carrier +======= + +When the *Stock Package Shipping UPS Module* is activated, carrier can be +configured to use the "UPS" shipping service. +When this configuration is chosen, carrier gains some extra properties like the +UPS service type, the label image format and notifications. + +.. seealso:: + + The Carrier model is introduced by the :doc:`Carrier Module + `. + +.. _model-carrier.credential.ups: + +UPS Credential +============== + +A *UPS Credential* stores the credentials to communicate with the UPS APIs. + +The first matching credential is used for carrier with "UPS" shipping service. + +.. seealso:: + + Credentials are found by opening the main menu item: + + |Carrier --> Configuration --> UPS Credentials|__ + + .. |Carrier --> Configuration --> UPS Credentials| replace:: :menuselection:`Carrier --> Configuration --> UPS Credentials` + __ https://demo.tryton.org/model/carrier.credential.ups + +.. _model-stock.package.type: + +Package Type +============ + +When the *Stock Package Shipping UPS Module* is activated, the UPS code can be +defined on the package type. + +.. seealso:: + + The Package Type model is introduced by the :doc:`Stock Package Module + `. diff --git a/modules/stock_package_shipping_ups/doc/index.rst b/modules/stock_package_shipping_ups/doc/index.rst index 41eabdb891..4f79d999fb 100644 --- a/modules/stock_package_shipping_ups/doc/index.rst +++ b/modules/stock_package_shipping_ups/doc/index.rst @@ -1,39 +1,14 @@ -Stock Package Shipping UPS Module -################################# +########################## +Stock Package Shipping UPS +########################## -The Stock Package Shipping UPS module allows you to generate the UPS labels per -package using the UPS API. +The *Stock Package Shipping UPS Module* allows to generate `UPS +`_ labels per package using their APIs. -The credential for the API is specified by the following fields: +.. toctree:: + :maxdepth: 2 -UPS Carrier Credential -********************** - -This model allows to define the credential used to connect the UPS API. -The credentials used to connect to the UPS API will be automatically retrieved -based on the company of the Shipment. - -- *Company*: The company for which those credentials are valid -- *Client ID*: The Client ID of the App. -- *Client Secret*: The Client Secret of the App. -- *Account Number*: The account number UPS assigned to you when you requested the - API credentials (also known as the Shipper Number). -- *Server*: Are those credentials used for accessing the Testing or the - Production server of UPS. -- *Use Metric*: Use Metric units when communicating with the UPS API. - -Carrier -******* - -The Carrier model is extended with the following fields: - -- *Service Type*: The UPS service type requested -- *Label Image Format*: The Image Format used for the label sent by UPS -- *Label Image Height*: The Height of the label sent by UPS. - -Package Type -************ - -The Package Type model is extended with the following field: - -- *UPS Code*: The UPS Code of the package. + usage + configuration + design + releases diff --git a/modules/stock_package_shipping_ups/doc/releases.rst b/modules/stock_package_shipping_ups/doc/releases.rst new file mode 100644 index 0000000000..21b13c4745 --- /dev/null +++ b/modules/stock_package_shipping_ups/doc/releases.rst @@ -0,0 +1,7 @@ +.. _releases-index: + +============= +Release notes +============= + +.. include:: ../CHANGELOG diff --git a/modules/stock_package_shipping_ups/doc/usage.rst b/modules/stock_package_shipping_ups/doc/usage.rst new file mode 100644 index 0000000000..08b4188023 --- /dev/null +++ b/modules/stock_package_shipping_ups/doc/usage.rst @@ -0,0 +1,24 @@ +***** +Setup +***** + +.. _Setting up UPS credentials: + +Setting up UPS credentials +========================== + +The *Stock Package Shipping UPS Module* needs credentials to access the APIs by +`creating an Application `_. +The Application needs to have at least access to: + + * Shipping + +You need to copy the *Client ID* and *Client Secret* that have been generated. + +When setting the `UPS Credential `, you must fill +the "Account Number" with the same account the application was created and the +"Client ID" and "Client Secret" with the copied values. + +.. tip:: + + Try first with the "Testing" server before swicth to "Production". diff --git a/modules/stock_package_shipping_ups/setup.py b/modules/stock_package_shipping_ups/setup.py index 6e02672126..00048a3c18 100755 --- a/modules/stock_package_shipping_ups/setup.py +++ b/modules/stock_package_shipping_ups/setup.py @@ -11,9 +11,12 @@ from setuptools import find_packages, setup 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): @@ -63,7 +66,9 @@ 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-stock-package-shipping-ups'), "Forum": 'https://www.tryton.org/forum', "Source Code": 'https://code.tryton.org/tryton', }, diff --git a/modules/stock_package_shipping_ups/tryton.cfg b/modules/stock_package_shipping_ups/tryton.cfg index 96aa532f17..12a63d71b1 100644 --- a/modules/stock_package_shipping_ups/tryton.cfg +++ b/modules/stock_package_shipping_ups/tryton.cfg @@ -1,6 +1,7 @@ [tryton] version=6.9.0 depends: + carrier ir res party