Fix Sphinx markup for USM crypto algorithm IDs

4 files changed, 108 insertions, 40 deletions

diff --git a/docs/source/docs/api-reference.rst b/docs/source/docs/api-reference.rst
index cb7c6d3f..2d0d9d42 100644
--- a/docs/source/docs/api-reference.rst
+++ b/docs/source/docs/api-reference.rst
@@ -49,10 +49,10 @@ saves its configuration for the lifetime of SNMP engine object.
 .. toctree::
    :maxdepth: 2
 
-.. autoclass:: pysnmp.hlapi.UdpTransportTarget
+.. autoclass:: pysnmp.hlapi.v3arch.UdpTransportTarget
    :members: setLocalAddress
 
-.. autoclass:: pysnmp.hlapi.Udp6TransportTarget
+.. autoclass:: pysnmp.hlapi.v3arch.Udp6TransportTarget
    :members: setLocalAddress
 
 High-level v3arch asyncore
@@ -183,7 +183,7 @@ Engine object on input.
 .. toctree::
    :maxdepth: 2
 
-.. autoclass:: pysnmp.hlapi.SnmpEngine(snmpEngineID=None)
+.. autoclass:: pysnmp.hlapi.v3arch.SnmpEngine(snmpEngineID=None)
 
 High-level v3arch auth
 ----------------------
@@ -199,41 +199,47 @@ Community-based
 +++++++++++++++
 
 Security Parameters object is Security Model specific. The
-:py:class:`~pysnmp.hlapi.CommunityData`
+:py:class:`~pysnmp.hlapi.v3arch.CommunityData`
 class is used for configuring Community-Based Security Model of SNMPv1/SNMPv2c.
 
 .. toctree::
    :maxdepth: 2
 
-.. autoclass:: pysnmp.hlapi.CommunityData(communityIndex, communityName=None, mpModel=1, contextEngineId=None, contextName='', tag='')
+.. autoclass:: pysnmp.hlapi.v3arch.CommunityData(communityIndex, communityName=None, mpModel=1, contextEngineId=None, contextName='', tag='')
 
 User-based
 ++++++++++
 
-The :py:class:`~pysnmp.hlapi.UsmUserData` class provides SNMPv3 User-Based
+The :py:class:`~pysnmp.hlapi.v3arch.UsmUserData` class provides SNMPv3 User-Based
 Security Model configuration for SNMP v3 systems.
 
-.. autoclass:: pysnmp.hlapi.UsmUserData(userName, authKey=None, privKey=None, authProtocol=usmNoAuthProtocol, privProtocol=usmNoPrivProtocol, securityEngineId=None)
+.. autoclass:: pysnmp.hlapi.v3arch.UsmUserData(userName, authKey=None, privKey=None, authProtocol=usmNoAuthProtocol, privProtocol=usmNoPrivProtocol, securityEngineId=None)
 
-Identification of Authentication and Privacy Protocols is done
-via constant OIDs:
+**Authentication protocol identifiers**
 
-.. autodata:: pysnmp.hlapi.usmNoAuthProtocol
-.. autodata:: pysnmp.hlapi.usmHMACMD5AuthProtocol
-.. autodata:: pysnmp.hlapi.usmHMACSHAAuthProtocol
-.. autodata:: pysnmp.hlapi.usmHMAC128SHA224AuthProtocol
-.. autodata:: pysnmp.hlapi.usmHMAC192SHA256AuthProtocol
-.. autodata:: pysnmp.hlapi.usmHMAC256SHA384AuthProtocol
-.. autodata:: pysnmp.hlapi.usmHMAC384SHA512AuthProtocol
+.. autodata:: pysnmp.hlapi.v3arch.usmNoAuthProtocol
+.. autodata:: pysnmp.hlapi.v3arch.usmHMACMD5AuthProtocol
+.. autodata:: pysnmp.hlapi.v3arch.usmHMACSHAAuthProtocol
+.. autodata:: pysnmp.hlapi.v3arch.usmHMAC128SHA224AuthProtocol
+.. autodata:: pysnmp.hlapi.v3arch.usmHMAC192SHA256AuthProtocol
+.. autodata:: pysnmp.hlapi.v3arch.usmHMAC256SHA384AuthProtocol
+.. autodata:: pysnmp.hlapi.v3arch.usmHMAC384SHA512AuthProtocol
 
-.. autodata:: pysnmp.hlapi.usmNoPrivProtocol
-.. autodata:: pysnmp.hlapi.usmDESPrivProtocol
-.. autodata:: pysnmp.hlapi.usm3DESEDEPrivProtocol
-.. autodata:: pysnmp.hlapi.usmAesCfb128Protocol
-.. autodata:: pysnmp.hlapi.usmAesCfb192Protocol
-.. autodata:: pysnmp.hlapi.usmAesCfb256Protocol
-.. autodata:: pysnmp.hlapi.usmAesBlumenthalCfb192Protocol
-.. autodata:: pysnmp.hlapi.usmAesBlumenthalCfb256Protocol
+**Privacy (encryption) protocol identifiers**
+
+.. autodata:: pysnmp.hlapi.v3arch.usmNoPrivProtocol
+.. autodata:: pysnmp.hlapi.v3arch.usmDESPrivProtocol
+.. autodata:: pysnmp.hlapi.v3arch.usm3DESEDEPrivProtocol
+.. autodata:: pysnmp.hlapi.v3arch.usmAesCfb128Protocol
+.. autodata:: pysnmp.hlapi.v3arch.usmAesCfb192Protocol
+.. autodata:: pysnmp.hlapi.v3arch.usmAesCfb256Protocol
+.. autodata:: pysnmp.hlapi.v3arch.usmAesBlumenthalCfb192Protocol
+.. autodata:: pysnmp.hlapi.v3arch.usmAesBlumenthalCfb256Protocol
+
+.. note::
+
+   SNMP authentication and encryption keys must be at least *eight*
+   octets long.
 
 Transport configuration is I/O framework specific and is described in
 respective sections.
@@ -263,12 +269,12 @@ SNMP engine. See :RFC:`3411#section-3.3.1` for details.
 
    The SNMP context information necessary for this mapping procedure
    to operate is supplied through the
-   :py:class:`~pysnmp.hlapi.CommunityData` object.
+   :py:class:`~pysnmp.hlapi.v3arch.CommunityData` object.
 
 .. toctree::
    :maxdepth: 2
 
-.. autoclass:: pysnmp.hlapi.ContextData
+.. autoclass:: pysnmp.hlapi.v3arch.ContextData
 
 High-level v1arch sync
 ----------------------
diff --git a/pysnmp/entity/config.py b/pysnmp/entity/config.py
index 835ecac9..63bed7c6 100644
--- a/pysnmp/entity/config.py
+++ b/pysnmp/entity/config.py
@@ -27,7 +27,9 @@ usmHMAC128SHA224AuthProtocol = hmacsha2.HmacSha2.sha224ServiceID
 usmHMAC192SHA256AuthProtocol = hmacsha2.HmacSha2.sha256ServiceID
 usmHMAC256SHA384AuthProtocol = hmacsha2.HmacSha2.sha384ServiceID
 usmHMAC384SHA512AuthProtocol = hmacsha2.HmacSha2.sha512ServiceID
+
 usmNoAuthProtocol = noauth.NoAuth.serviceID
+"""No authentication service"""
 
 # Privacy protocol
 usmDESPrivProtocol = des.Des.serviceID
diff --git a/pysnmp/hlapi/v3arch/__init__.py b/pysnmp/hlapi/v3arch/__init__.py
index 8f36181c..9e5f7779 100644
--- a/pysnmp/hlapi/v3arch/__init__.py
+++ b/pysnmp/hlapi/v3arch/__init__.py
@@ -7,9 +7,54 @@
 from pysnmp.proto.rfc1902 import *
 from pysnmp.proto.rfc1905 import NoSuchInstance, NoSuchObject, EndOfMibView
 from pysnmp.smi.rfc1902 import *
-from pysnmp.hlapi.v3arch.auth import *
+from pysnmp.hlapi.v3arch import auth
 from pysnmp.hlapi.v3arch.context import *
 from pysnmp.entity.engine import *
 
 # default is synchronous asyncore-based API
 from pysnmp.hlapi.v3arch.asyncore.sync import *
+
+usmNoAuthProtocol = auth.usmNoAuthProtocol
+"""No Authentication Protocol"""
+
+usmHMACMD5AuthProtocol = auth.usmHMACMD5AuthProtocol
+"""The HMAC-MD5-96 Digest Authentication Protocol (:RFC:`3414#section-6`)"""
+
+usmHMACSHAAuthProtocol = auth.usmHMACSHAAuthProtocol
+"""The HMAC-SHA-96 Digest Authentication Protocol AKA SHA-1 (:RFC:`3414#section-7`)"""
+
+usmHMAC128SHA224AuthProtocol = auth.usmHMAC128SHA224AuthProtocol
+"""The HMAC-SHA-2 Digest Authentication Protocols (:RFC:`7860`)"""
+
+usmHMAC192SHA256AuthProtocol = auth.usmHMAC192SHA256AuthProtocol
+"""The HMAC-SHA-2 Digest Authentication Protocols (:RFC:`7860`)"""
+
+usmHMAC256SHA384AuthProtocol = auth.usmHMAC256SHA384AuthProtocol
+"""The HMAC-SHA-2 Digest Authentication Protocols (:RFC:`7860`)"""
+
+usmHMAC384SHA512AuthProtocol = auth.usmHMAC384SHA512AuthProtocol
+"""The HMAC-SHA-2 Digest Authentication Protocols (:RFC:`7860`)"""
+
+usmNoPrivProtocol = auth.usmNoPrivProtocol
+"""No Privacy Protocol"""
+
+usmDESPrivProtocol = auth.usmDESPrivProtocol
+"""The CBC-DES Symmetric Encryption Protocol (:RFC:`3414#section-8`)"""
+
+usm3DESEDEPrivProtocol = auth.usm3DESEDEPrivProtocol
+"""The 3DES-EDE Symmetric Encryption Protocol (`draft-reeder-snmpv3-usm-3desede-00 <https:://tools.ietf.org/html/draft-reeder-snmpv3-usm-3desede-00#section-5>`_)"""
+
+usmAesCfb128Protocol = auth.usmAesCfb128Protocol
+"""The CFB128-AES-128 Symmetric Encryption Protocol (:RFC:`3826#section-3`)"""
+
+usmAesCfb192Protocol = auth.usmAesCfb192Protocol
+"""The CFB128-AES-192 Symmetric Encryption Protocol (`draft-blumenthal-aes-usm-04 <https:://tools.ietf.org/html/draft-blumenthal-aes-usm-04#section-3>`_) with Reeder key localization"""
+
+usmAesCfb256Protocol = auth.usmAesCfb256Protocol
+"""The CFB128-AES-256 Symmetric Encryption Protocol (`draft-blumenthal-aes-usm-04 <https:://tools.ietf.org/html/draft-blumenthal-aes-usm-04#section-3>`_) with Reeder key localization"""
+
+usmAesBlumenthalCfb192Protocol = auth.usmAesBlumenthalCfb192Protocol
+"""The CFB128-AES-192 Symmetric Encryption Protocol (`draft-blumenthal-aes-usm-04 <https:://tools.ietf.org/html/draft-blumenthal-aes-usm-04#section-3>`_)"""
+
+usmAesBlumenthalCfb256Protocol = auth.usmAesBlumenthalCfb256Protocol
+"""The CFB128-AES-256 Symmetric Encryption Protocol (`draft-blumenthal-aes-usm-04 <https:://tools.ietf.org/html/draft-blumenthal-aes-usm-04#section-3>`_)"""
diff --git a/pysnmp/hlapi/v3arch/auth.py b/pysnmp/hlapi/v3arch/auth.py
index e4650f4b..20db368f 100644
--- a/pysnmp/hlapi/v3arch/auth.py
+++ b/pysnmp/hlapi/v3arch/auth.py
@@ -151,35 +151,50 @@ class CommunityData(object):
             securityName is None and self.securityName or securityName
         )
 
-
-#: No Authentication Protocol.
 usmNoAuthProtocol = config.usmNoAuthProtocol
-#: The HMAC-MD5-96 Digest Authentication Protocol (:RFC:`3414#section-6`)
+"""No Authentication Protocol"""
+
 usmHMACMD5AuthProtocol = config.usmHMACMD5AuthProtocol
-#: The HMAC-SHA-96 Digest Authentication Protocol (:RFC:`3414#section-7`)
+"""The HMAC-MD5-96 Digest Authentication Protocol (:RFC:`3414#section-6`)"""
+
 usmHMACSHAAuthProtocol = config.usmHMACSHAAuthProtocol
-#: The HMAC-SHA-2 Digest Authentication Protocols (:RFC:`7860`)
+"""The HMAC-SHA-96 Digest Authentication Protocol AKA SHA-1 (:RFC:`3414#section-7`)"""
+
 usmHMAC128SHA224AuthProtocol = config.usmHMAC128SHA224AuthProtocol
+"""The HMAC-SHA-2 Digest Authentication Protocols (:RFC:`7860`)"""
+
 usmHMAC192SHA256AuthProtocol = config.usmHMAC192SHA256AuthProtocol
+"""The HMAC-SHA-2 Digest Authentication Protocols (:RFC:`7860`)"""
+
 usmHMAC256SHA384AuthProtocol = config.usmHMAC256SHA384AuthProtocol
+"""The HMAC-SHA-2 Digest Authentication Protocols (:RFC:`7860`)"""
+
 usmHMAC384SHA512AuthProtocol = config.usmHMAC384SHA512AuthProtocol
+"""The HMAC-SHA-2 Digest Authentication Protocols (:RFC:`7860`)"""
 
-#: No Privacy Protocol.
 usmNoPrivProtocol = config.usmNoPrivProtocol
-#: The CBC-DES Symmetric Encryption Protocol (:RFC:`3414#section-8`)
+"""No Privacy Protocol"""
+
 usmDESPrivProtocol = config.usmDESPrivProtocol
-#: The 3DES-EDE Symmetric Encryption Protocol (`draft-reeder-snmpv3-usm-3desede-00 <https://tools.ietf.org/html/draft-reeder-snmpv3-usm-3desede-00#section-5>`_)
+"""The CBC-DES Symmetric Encryption Protocol (:RFC:`3414#section-8`)"""
+
 usm3DESEDEPrivProtocol = config.usm3DESEDEPrivProtocol
-#: The CFB128-AES-128 Symmetric Encryption Protocol (:RFC:`3826#section-3`)
+"""The 3DES-EDE Symmetric Encryption Protocol (`draft-reeder-snmpv3-usm-3desede-00 <https:://tools.ietf.org/html/draft-reeder-snmpv3-usm-3desede-00#section-5>`_)"""
+
 usmAesCfb128Protocol = config.usmAesCfb128Protocol
-#: The CFB128-AES-192 Symmetric Encryption Protocol (`draft-blumenthal-aes-usm-04 <https://tools.ietf.org/html/draft-blumenthal-aes-usm-04#section-3>`_) with Reeder key localization
+"""The CFB128-AES-128 Symmetric Encryption Protocol (:RFC:`3826#section-3`)"""
+
 usmAesCfb192Protocol = config.usmAesCfb192Protocol
-#: The CFB128-AES-256 Symmetric Encryption Protocol (`draft-blumenthal-aes-usm-04 <https://tools.ietf.org/html/draft-blumenthal-aes-usm-04#section-3>`_) with Reeder key localization
+"""The CFB128-AES-192 Symmetric Encryption Protocol (`draft-blumenthal-aes-usm-04 <https:://tools.ietf.org/html/draft-blumenthal-aes-usm-04#section-3>`_) with Reeder key localization"""
+
 usmAesCfb256Protocol = config.usmAesCfb256Protocol
-#: The CFB128-AES-192 Symmetric Encryption Protocol (`draft-blumenthal-aes-usm-04 <https://tools.ietf.org/html/draft-blumenthal-aes-usm-04#section-3>`_)
+"""The CFB128-AES-256 Symmetric Encryption Protocol (`draft-blumenthal-aes-usm-04 <https:://tools.ietf.org/html/draft-blumenthal-aes-usm-04#section-3>`_) with Reeder key localization"""
+
 usmAesBlumenthalCfb192Protocol = config.usmAesBlumenthalCfb192Protocol
-#: The CFB128-AES-256 Symmetric Encryption Protocol (`draft-blumenthal-aes-usm-04 <https://tools.ietf.org/html/draft-blumenthal-aes-usm-04#section-3>`_)
+"""The CFB128-AES-192 Symmetric Encryption Protocol (`draft-blumenthal-aes-usm-04 <https:://tools.ietf.org/html/draft-blumenthal-aes-usm-04#section-3>`_)"""
+
 usmAesBlumenthalCfb256Protocol = config.usmAesBlumenthalCfb256Protocol
+"""The CFB128-AES-256 Symmetric Encryption Protocol (`draft-blumenthal-aes-usm-04 <https:://tools.ietf.org/html/draft-blumenthal-aes-usm-04#section-3>`_)"""
 
 
 class UsmUserData(object):