Revisited the docs.

lextudio · Oct 5, 2024 · 5932769 · 5932769
1 parent 39441de
commit 5932769
Show file tree

Hide file tree

Showing 12 changed files with 40 additions and 27 deletions.
diff --git a/docs/source/docs/api-reference.rst b/docs/source/docs/api-reference.rst
@@ -19,22 +19,25 @@ Most of SNMP operations involve packet exchange over network. PySNMP
 is shipped with asyncio binding that let you run PySNMP in parallel with
 other tasks your application may perform.
 
-High-level, v3arch, sync
-------------------------
+High-level v3arch sync
+----------------------
 
 Most simple and straightforward way to use PySNMP is by employing its
-Synchronous, blocking API. It's also the default API offered by
-users on *pysnmp.hlapi* sub-package import.
+Synchronous, blocking API. It used to be the default API to offer on
+*pysnmp.hlapi* sub-package import. However, it is now deprecated and
+removed.
 
-.. warning:: Completely deprecated in PySNMP 6.2 release.
+.. warning:: First deprecated in PySNMP 6.0, and completely removed in
+   PySNMP 6.2.
 
 High-level v3arch asyncio
 -------------------------
 
 The :mod:`asyncio` module first appeared in standard library since
 Python 3.3 (in provisional basis). Its main design feature is that
-it makes asynchronous code looking like synchronous one. That greatly
-simplifies development and maintenance.
+it makes asynchronous code looking like synchronous one, especially after
+the introduction of async/await pattern. That greatly simplifies
+development and maintenance.
 
 Command Generator
 
@@ -188,6 +191,11 @@ The :mod:`asyncio` module is in Python standard library since ancient
 times. Main loop is built around :mod:`select` dispatcher, user
 code is invoked through callback callables.
 
+Different from `v3arch` asyncio, `v1arch` asyncio API aims to avoid the
+complexity of the `v3arch` asyncio API, and to provide a simpler and more
+straightforward API for users who only need to perform SNMP v1 and v2c
+operations.
+
 Command Generator
 
 .. toctree::

diff --git a/docs/source/docs/hlapi/v1arch/asyncio/agent/ntforg/notification.rst b/docs/source/docs/hlapi/v1arch/asyncio/agent/ntforg/notification.rst
@@ -1,6 +1,6 @@
 
-TRAP/INFORM notification
-========================
+TRAP/INFORM Operation
+=====================
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/docs/hlapi/v1arch/asyncio/manager/cmdgen/bulkcmd.rst b/docs/source/docs/hlapi/v1arch/asyncio/manager/cmdgen/bulkcmd.rst
@@ -1,6 +1,6 @@
 
-GETBULK command
-===============
+GETBULK Operation
+=================
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/docs/hlapi/v1arch/asyncio/manager/cmdgen/getcmd.rst b/docs/source/docs/hlapi/v1arch/asyncio/manager/cmdgen/getcmd.rst
@@ -1,6 +1,6 @@
 
-GET command
-===========
+GET Operation
+=============
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/docs/hlapi/v1arch/asyncio/manager/cmdgen/nextcmd.rst b/docs/source/docs/hlapi/v1arch/asyncio/manager/cmdgen/nextcmd.rst
@@ -1,6 +1,6 @@
 
-GETNEXT command
-===============
+GETNEXT Operation
+=================
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/docs/hlapi/v1arch/asyncio/manager/cmdgen/setcmd.rst b/docs/source/docs/hlapi/v1arch/asyncio/manager/cmdgen/setcmd.rst
@@ -1,6 +1,6 @@
 
-SET command
-===========
+SET Operation
+=============
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/docs/hlapi/v3arch/asyncio/agent/ntforg/notification.rst b/docs/source/docs/hlapi/v3arch/asyncio/agent/ntforg/notification.rst
@@ -1,6 +1,6 @@
 
-TRAP/INFORM notification
-========================
+TRAP/INFORM Operation
+=====================
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/docs/hlapi/v3arch/asyncio/manager/cmdgen/bulkcmd.rst b/docs/source/docs/hlapi/v3arch/asyncio/manager/cmdgen/bulkcmd.rst
@@ -1,6 +1,6 @@
 
-GETBULK command
-===============
+GETBULK Operation
+=================
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/docs/hlapi/v3arch/asyncio/manager/cmdgen/getcmd.rst b/docs/source/docs/hlapi/v3arch/asyncio/manager/cmdgen/getcmd.rst
@@ -1,6 +1,6 @@
 
-GET command
-===========
+GET Operation
+=============
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/docs/hlapi/v3arch/asyncio/manager/cmdgen/nextcmd.rst b/docs/source/docs/hlapi/v3arch/asyncio/manager/cmdgen/nextcmd.rst
@@ -1,6 +1,6 @@
 
-GETNEXT command
-===============
+GETNEXT Operation
+=================
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/docs/hlapi/v3arch/asyncio/manager/cmdgen/setcmd.rst b/docs/source/docs/hlapi/v3arch/asyncio/manager/cmdgen/setcmd.rst
@@ -1,6 +1,6 @@
 
-SET command
-===========
+SET Operation
+=============
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst
@@ -166,6 +166,11 @@ Using these examples
    It is difficult to cover all examples on this site, so you might want to
    visit the ``examples`` folder in `PySNMP GitHub repository`_.
 
+   When examples are not enough or out-of-date, you might want to refer to
+   the latest unit test cases under the ``tests`` folder in the
+   `PySNMP GitHub repository`_. They are the most reliable resources to see
+   the API in action.
+
 Before using the sample code, make sure ``pysnmp`` and its
 dependencies are installed. You might refer to :doc:`/quick-start` for
 details.