Sphinx theme changed to Alabaster, minor documentation tweaks

7 files changed, 40 insertions, 167 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 6ed56337..bf7c1d06 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,13 +1,14 @@
 
-Revision 4.4.1, released 2017-10-XX
+Revision 4.4.1, released 2017-10-07
 ------------------------------------
 
 - HMAC-SHA-2 Authentication Protocols support added (RFC-7860)
 - The pycryptodome dependency replaced with pycryptodomex as
   it is recommended by the upstream to avoid unwanted interference
-  with PyCrypto package should it also be installed.
+  with PyCrypto package should it also be installed
+- Sphinx theme changed to Alabaster
 
-Revision 4.3.10, released 2017-10-XX
+Revision 4.3.10, released 2017-10-06
 ------------------------------------
 
 - Refactored partial SNMP message decoding to make it less dependent
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 95cae292..c15bdffd 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -38,7 +38,7 @@ extensions = [
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['.templates']
+#templates_path = ['.templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -52,7 +52,7 @@ source_suffix = '.rst'
 master_doc = 'contents'
 
 # General information about the project.
-project = u'PySNMP'
+project = u'SNMP library for Python'
 copyright = u'2005-2017, Ilya Etingof <etingof@gmail.com>'
 author = u'Ilya Etingof <etingof@gmail.com>'
 
@@ -61,9 +61,9 @@ author = u'Ilya Etingof <etingof@gmail.com>'
 # built documents.
 #
 # The short X.Y version.
-version = '4.3'
+version = '4.4'
 # The full version, including alpha/beta/rc tags.
-release = '4.3'
+release = '4.4'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -114,8 +114,8 @@ todo_include_todos = True
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#html_theme = 'alabaster'
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'alabaster'
+#html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -128,7 +128,7 @@ html_theme = 'sphinx_rtd_theme'
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None
-html_title = "PySNMP"
+#html_title = "PySNMP"
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None
@@ -145,12 +145,12 @@ html_title = "PySNMP"
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-if 'PYSNMPDEV' in os.environ:
-    html_static_path = ['.static']
+#if 'PYSNMPDEV' in os.environ:
+#    html_static_path = ['.static']
 
 # Custom CSS theme
-if 'PYSNMPDEV' in os.environ:
-    html_style = 'css/rtdimproved.css'
+#if 'PYSNMPDEV' in os.environ:
+#    html_style = 'css/rtdimproved.css'
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -302,9 +302,11 @@ texinfo_documents = [
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = { 'python': ('https://docs.python.org/3.4/', None),
-                        'pysmi': ('http://pysmi.sf.net/', None),
-                        'twisted': ('https://twistedmatrix.com/documents/15.4.0/api/', None) }
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3.4/', None),
+    'pysmi': ('http://pysmi.sf.net/', None),
+    'twisted': ('https://twistedmatrix.com/documents/15.4.0/api/', None)
+}
 
 # this merges constructor docstring with class docstring
 autoclass_content = 'both'
diff --git a/docs/source/contents.rst b/docs/source/contents.rst
index 494d2084..2319bbfa 100644
--- a/docs/source/contents.rst
+++ b/docs/source/contents.rst
@@ -11,16 +11,16 @@ engine implementation. It features fully-functional SNMP engine capable
 to act in Agent/Manager/Proxy roles, talking SNMP v1/v2c/v3 protocol 
 versions over IPv4/IPv6 and other network transports.
 
-Despite its name, SNMP is not a really simple protocol. For instance its 
+Despite its name, SNMP is not really a simple protocol. For instance its
 third version introduces complex and open-ended security framework, 
 multilingual capabilities, remote configuration and other features. 
 PySNMP implementation closely follows intricate system details and features 
 bringing most possible power and flexibility to its users.
 
-Current PySNMP stable version is 4.3. It runs with Python 2.4 through 3.5 
+Current PySNMP stable version is 4.4. It runs with Python 2.4 through 3.6
 and is recommended for new applications as well as for migration from
 older, now obsolete, PySNMP releases. All site documentation and 
-examples are written for the 4.3 and later versions in mind.
+examples are written for the 4.4 and later versions in mind.
 Older materials are still available under the obsolete section.
 
 Besides the libraries, a set of pure-Python 
@@ -121,11 +121,9 @@ are collected in the following section.
 Contact
 -------
 
-Please, use our
-`mailing list <https://lists.sourceforge.net/lists/listinfo/pysnmp-users>`_
-or refer to
-`Stack Overflow <http://stackoverflow.com/questions/tagged/pysnmp>`_ 
-should you have any questions or issues in regards to PySNMP.
+In case of questions or troubles using PySNMP, please open up an
+`issue <https://github.com/etingof/pysnmp/issues>`_ at GitHub or ask at
+`Stack Overflow <http://stackoverflow.com/questions/tagged/pysnmp>`_ .
 
 Old site archive
 ----------------
diff --git a/docs/source/development.rst b/docs/source/development.rst
index abe9cba8..56175947 100644
--- a/docs/source/development.rst
+++ b/docs/source/development.rst
@@ -11,14 +11,14 @@ hands on in the future.
 PySNMP library
 ++++++++++++++
 
-#. Built-in MIB parser. PySNMP uses a data model of its own to work with 
-   information contained in MIB files. To convert ASN.1-based MIB texts 
-   into Python modules, an off-line, third-party tool is employed. As it 
-   turns out, this approach has two major drawback: one is that PySNMP 
-   users may need to pre-process MIB texts to use them with their 
-   PySNMP-based applications. Another is that LibSMI's Python driver 
-   seems to miss some information carried by MIBs. Thus the solution would 
-   be to write another MIB parser and code generator which would produce 
+#. Built-in MIB parser. PySNMP uses a data model of its own to work with
+   information contained in MIB files. To convert ASN.1-based MIB texts
+   into Python modules, an off-line, third-party tool is employed. As it
+   turns out, this approach has two major drawback: one is that PySNMP
+   users may need to pre-process MIB texts to use them with their
+   PySNMP-based applications. Another is that LibSMI's Python driver
+   seems to miss some information carried by MIBs. Thus the solution would
+   be to write another MIB parser and code generator which would produce
    PySNMP compliant Python code right from MIB text files all by itself.
 
    **Done:** see `PySMI project <http://pysmi.sf.net>`_ in conjuction with the latest PySNMP codebase.
@@ -54,7 +54,6 @@ PySNMP library
    SMI/MIB subsystem into a database. PySNMP engine would talk to it 
    through its simple and well defined SMI API.
 
-
 Stand-alone PySNMP-based tools
 ++++++++++++++++++++++++++++++
 
@@ -94,7 +93,7 @@ sponsoring it. Please get back to us to discuss details.
 
 Contributions to the PySNMP source code is greatly appreciated as well. 
 We require contributed code to run with Python 2.4 through the latest 
-Python version (which is 3.3 at the time of this writing). Contributed 
+Python version (which is 3.6 at the time of this writing). Contributed
 code will be redistributed under the terms of the same 
 `license <http://pysnmp.sourceforge.net/license.html>`_ as PySNMP is.
 
diff --git a/docs/source/examples/contents.rst b/docs/source/examples/contents.rst
index a3f5c134..e2ece0e5 100644
--- a/docs/source/examples/contents.rst
+++ b/docs/source/examples/contents.rst
@@ -5,12 +5,12 @@ Example scripts
 .. toctree::
    :maxdepth: 2
 
-SNMP is not really simple (PySNMP implementation takes over 15K lines of
-Python code), but PySNMP tries to isolate the complexities and let you 
-perform typical SNMP operations in a quick and intuitive way.
+SNMP is not simple (PySNMP implementation takes over 15K lines of
+Python code), but PySNMP tries to hide the complexities and let you
+carry out typical SNMP operations in a quick and intuitive way.
 
 PySNMP offers three groups of programming interfaces to deal with 
-SNMP protocol. In the order from most consice to most detailed those 
+SNMP protocol. In the order from most concise to most detailed those
 APIs follow.
 
 High-level SNMP
@@ -24,7 +24,7 @@ wrapped into a nearly one-line Python expression.
 It comes in several flavours: one synchronous and a bunch of bindings to
 popular asynchronous I/O frameworks. Those varieties of APIs bring
 subtile differences, mostly to better match particular I/O framework
-customs. Unless you have a vary specific task, one of high-level APIs might
+customs. Unless you have a very specific task, the high-level API might
 solve your SNMP needs.
 
 .. toctree::
diff --git a/examples/v3arch/asyncore/agent/cmdrsp/implementing-dynamic-snmp-table.py b/examples/v3arch/asyncore/agent/cmdrsp/implementing-dynamic-snmp-table.py
deleted file mode 100644
index f7015e51..00000000
--- a/examples/v3arch/asyncore/agent/cmdrsp/implementing-dynamic-snmp-table.py
+++ /dev/null
@@ -1,127 +0,0 @@
-"""
-Implementing conceptual table
-+++++++++++++++++++++++++++++
-
-Listen and respond to SNMP GET/SET/GETNEXT/GETBULK queries with
-the following options:
-
-* SNMPv2c
-* with SNMP community "public"
-* define a simple SNMP Table within a newly created EXAMPLE-MIB
-* pre-populate SNMP Table with a single row of values
-* allow read access only to the subtree where example SNMP Table resides
-* over IPv4/UDP, listening at 127.0.0.1:161
-
-The following Net-SNMP commands will populate and walk a table:
-
-| $ snmpset -v2c -c public 127.0.0.1 1.3.6.6.1.5.2.97.98.99 s "my value"
-| $ snmpset -v2c -c public 127.0.0.1 1.3.6.6.1.5.4.97.98.99 i 4
-| $ snmpwalk -v2c -c public 127.0.0.1 1.3.6
-
-...while the following command will destroy the same row
-
-| $ snmpset -v2c -c public 127.0.0.1 1.3.6.6.1.5.4.97.98.99 i 6
-| $ snmpwalk -v2c -c public 127.0.0.1 1.3.6
-
-"""  #
-from pysnmp.entity import engine, config
-from pysnmp.entity.rfc3413 import cmdrsp, context
-from pysnmp.carrier.asyncore.dgram import udp
-from pysnmp.proto.api import v2c
-
-# Create SNMP engine
-snmpEngine = engine.SnmpEngine()
-
-# Transport setup
-
-# UDP over IPv4
-config.addTransport(
-    snmpEngine,
-    udp.domainName,
-    udp.UdpTransport().openServerMode(('127.0.0.1', 161))
-)
-
-# SNMPv2c setup
-
-# SecurityName <-> CommunityName mapping.
-config.addV1System(snmpEngine, 'my-area', 'public')
-
-# Allow read MIB access for this user / securityModels at VACM
-config.addVacmUser(snmpEngine, 2, 'my-area', 'noAuthNoPriv', (1, 3, 6, 6), (1, 3, 6, 6))
-
-# Create an SNMP context
-snmpContext = context.SnmpContext(snmpEngine)
-
-# --- define custom SNMP Table within a newly defined EXAMPLE-MIB ---
-
-mibBuilder = snmpContext.getMibInstrum().getMibBuilder()
-
-(MibTable,
- MibTableRow,
- MibTableColumn,
- MibScalarInstance) = mibBuilder.importSymbols(
-    'SNMPv2-SMI',
-    'MibTable',
-    'MibTableRow',
-    'MibTableColumn',
-    'MibScalarInstance'
-)
-
-RowStatus, = mibBuilder.importSymbols('SNMPv2-TC', 'RowStatus')
-
-mibBuilder.exportSymbols(
-    '__EXAMPLE-MIB',
-    # table object
-    exampleTable=MibTable((1, 3, 6, 6, 1)).setMaxAccess('readcreate'),
-    # table row object, also carries references to table indices
-    exampleTableEntry=MibTableRow((1, 3, 6, 6, 1, 5)).setMaxAccess('readcreate').setIndexNames(
-        (0, '__EXAMPLE-MIB', 'exampleTableColumn1')),
-    # table column: string index
-    exampleTableColumn1=MibTableColumn((1, 3, 6, 6, 1, 5, 1), v2c.OctetString()).setMaxAccess('readcreate'),
-    # table column: string value
-    exampleTableColumn2=MibTableColumn((1, 3, 6, 6, 1, 5, 2), v2c.OctetString()).setMaxAccess('readcreate'),
-    # table column: integer value with default
-    exampleTableColumn3=MibTableColumn((1, 3, 6, 6, 1, 5, 3), v2c.Integer32(123)).setMaxAccess('readcreate'),
-    # table column: row status
-    exampleTableStatus=MibTableColumn((1, 3, 6, 6, 1, 5, 4), RowStatus('notExists')).setMaxAccess('readcreate')
-)
-
-# --- end of custom SNMP table definition, empty table now exists ---
-
-# --- populate custom SNMP table with one row ---
-
-(exampleTableEntry,
- exampleTableColumn2,
- exampleTableColumn3,
- exampleTableStatus) = mibBuilder.importSymbols(
-    '__EXAMPLE-MIB',
-    'exampleTableEntry',
-    'exampleTableColumn2',
-    'exampleTableColumn3',
-    'exampleTableStatus'
-)
-rowInstanceId = exampleTableEntry.getInstIdFromIndices('example record one')
-mibInstrumentation = snmpContext.getMibInstrum()
-mibInstrumentation.writeVars(
-    ((exampleTableColumn2.name + rowInstanceId, 'my string value'),
-     (exampleTableColumn3.name + rowInstanceId, 123456),
-     (exampleTableStatus.name + rowInstanceId, 'createAndGo'))
-)
-
-# --- end of SNMP table population ---
-
-# Register SNMP Applications at the SNMP engine for particular SNMP context
-cmdrsp.GetCommandResponder(snmpEngine, snmpContext)
-cmdrsp.SetCommandResponder(snmpEngine, snmpContext)
-cmdrsp.NextCommandResponder(snmpEngine, snmpContext)
-cmdrsp.BulkCommandResponder(snmpEngine, snmpContext)
-
-# Register an imaginary never-ending job to keep I/O dispatcher running forever
-snmpEngine.transportDispatcher.jobStarted(1)
-
-# Run I/O dispatcher which would receive queries and send responses
-try:
-    snmpEngine.transportDispatcher.runDispatcher()
-except:
-    snmpEngine.transportDispatcher.closeDispatcher()
-    raise
diff --git a/examples/v3arch/asyncore/agent/cmdrsp/implementing-static-snmp-table.py b/examples/v3arch/asyncore/agent/cmdrsp/implementing-snmp-table.py
index 0e15599a..0e15599a 100644
--- a/examples/v3arch/asyncore/agent/cmdrsp/implementing-static-snmp-table.py
+++ b/examples/v3arch/asyncore/agent/cmdrsp/implementing-snmp-table.py