Update documentation of authentication SMS

2024-10-15 17:43:50 +00:00
parent f3c767dc6f
commit 2f1446a5c0
6 changed files with 105 additions and 45 deletions
@@ -20,42 +20,54 @@ Version 6.6.0 - 2022-10-31
 * Bug fixes (see mercurial logs for details)

 Version 6.4.0 - 2022-05-02
+--------------------------
 * Bug fixes (see mercurial logs for details)
 * 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
 * Remove password_sms authentication method

 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)

 Version 4.2.0 - 2016-11-28
+--------------------------
 * Initial release
@@ -0,0 +1,50 @@
+*************
+Configuration
+*************
+
+The *Authentication SMS Module* introduces a new `authentication service
+<trytond:config-session.authentications>` ``sms`` and uses settings from the
+``[authentication_sms]`` section of the :ref:`trytond:topics-configuration`.
+
+.. _config-authentication_sms.function:
+
+``function``
+============
+
+The fully qualified name of the Python method used to send :abbr:`SMS (Short
+Message Service)` with the signature: ``(text, to, from)``.
+
+.. important::
+   The method is required to use this authentication method.
+
+.. _config-authentication_sms.from:
+
+``from``
+========
+
+The phone number from which the SMS are sent.
+
+.. _config.authentication_sms.length:
+
+``length``
+==========
+
+The number of figures for the generated authentication code sent by SMS.
+
+The default value is: ``6``
+
+.. _config.authentication_sms.ttl:
+
+``ttl``
+=======
+
+The duration in seconds for which the generated codes is still valid.
+
+The default value is: ``5 * 60``
+
+``name``
+========
+
+The name of the application used in the text of the SMS.
+
+The default value is: ``Tryton``
@@ -0,0 +1,22 @@
+******
+Design
+******
+
+The *Authentication SMS Module* extends the following concepts:
+
+.. _model-res.user:
+
+User
+====
+
+When *Authentication SMS Module* is activated, the *User* gains a new property
+for the user's :guilabel:`Mobile` number.
+
+.. note::
+   The :guilabel:`Mobile` is required in order to send the user the code they
+   need to authenticate with when using the ``sms`` method.
+
+.. seealso::
+
+   The `User <trytond:model-res.user>` concept is introduced by the `Resource
+   Module <trytond:res>`.
@@ -1,48 +1,13 @@
+#########################
 Authentication SMS Module
 #########################

-The `SMS <https://en.wikipedia.org/wiki/Short_Message_Service>`_ authentication
-module allows users to authenticate via SMS.  It adds a new authentication
-method ``sms``, which can be used in the list of ``authentications`` in the
-``session`` section of the configuration file.
+The *Authentication SMS Module* allows users to authenticate using a code
+received via `SMS <https://en.wikipedia.org/wiki/Short_Message_Service>`_.

-The ``sms`` method just sends a code via SMS to the user. Then the user needs
-to transcribe the code into the login dialog.
+.. toctree::
+   :maxdepth: 2

-This method requires that the user has the correct *Mobile* phone number
-defined otherwise it will not be possible for them to authenticate.
-
-Configuration
-*************
-
-The configuration of the module is set in the ``authentication_sms`` section.
-
-function
--------
-
-The fully qualified name of the method to send SMS. It must take three
-arguments: text, to and from.
-This method is required to send SMS.
-
-from
----
-
-The number from which the SMS are sent.
-
-length
------
-
-The length of the generated code.
-Default: 6
-
-ttl
---
-
-The time to live for the generated codes in seconds.
-Default: 300
-
-name
----
-
-The name used in the SMS text.
-Default: Tryton
+   configuration
+   design
+   releases
@@ -0,0 +1,7 @@
+.. _releases-index:
+
+=============
+Release notes
+=============
+
+.. include:: ../CHANGELOG
@@ -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):
@@ -59,7 +62,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/latest/modules-authentication-sms'),
        "Forum": 'https://www.tryton.org/forum',
        "Source Code": 'https://code.tryton.org/tryton',
        },