Revamped docs.

.vscode/settings.json

@@ -3,5 +3,8 @@
         "tests"
     ],
     "python.testing.unittestEnabled": false,
-    "python.testing.pytestEnabled": true
-}
+    "python.testing.pytestEnabled": true,
+    "editor.rulers": [
+        79
+    ],
+}

LICENSE.rst

@@ -1,5 +1,7 @@
 Copyright (c) 2015-2020 Ilya Etingof <[email protected]>
+
 Copyright (c) 2022-2024, LeXtudio Inc. <[email protected]>
+
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

README.md

@@ -1,6 +1,8 @@
 
-SNMP MIB parser
----------------
+SNMP MIB Compiler
+-----------------
+
+[![Become a Sponsor](https://img.shields.io/badge/Become%20a%20Sponsor-lextudio-orange.svg?style=for-readme)](https://github.com/sponsors/lextudio)
 [![PyPI](https://img.shields.io/pypi/v/pysmi-lextudio.svg?maxAge=2592000)](https://pypi.org/project/pysmi-lextudio)
 [![PyPI Downloads](https://img.shields.io/pypi/dd/pysmi-lextudio)](https://pypi.python.org/pypi/pysmi-lextudio/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/pysmi-lextudio.svg)](https://pypi.org/project/pysmi-lextudio/)
@@ -9,26 +11,26 @@ SNMP MIB parser
 PySMI is a pure-Python implementation of
 [SNMP SMI](https://en.wikipedia.org/wiki/Management_information_base) MIB parser.
 This tool is designed to turn ASN.1 MIBs into various formats. As of this moment,
-JSON and [pysnmp](https://github.com/lextudio/pysnmp) modules can be generated
+JSON and [PySNMP](https://github.com/lextudio/pysnmp) modules can be generated
 from ASN.1 MIBs.
 
 Features
 --------
 
 * Understands SMIv1, SMIv2 and de-facto SMI dialects
-* Turns MIBs into pysnmp classes and JSON documents
+* Turns MIBs into PySNMP classes and JSON documents
 * Maintains an index of MIB objects over many MIB modules
 * Automatically pulls ASN.1 MIBs from local directories, ZIP archives,
   and HTTP servers
-* 100% Python, works with Python 3.7+
+* 100% Python, works with Python 3.8+
 
-Rendered PySMI documentation can be found at [pysmi site](https://www.pysnmp.com/pysmi).
+Rendered PySMI documentation can be found at [PySMI site](https://www.pysnmp.com/pysmi).
 
 How to use PySMI
 ----------------
 
-If you are using pysnmp, you might never notice pysmi presence - pysnmp
-calls pysmi for MIB download and compilation behind the scenes (you can
+If you are using PySNMP, you might never notice PySMI presence - PySNMP
+calls PySMI for MIB download and compilation behind the scenes (you can
 still can do that manually by invoking *mibdump* tool).
 
 To turn ASN.1 MIB into a JSON document, call *mibdump* tool like this:
@@ -65,7 +67,7 @@ JSON document build from
 [IF-MIB module](https://mibs.pysnmp.com/asn1/IF-MIB)
 would hold information such as:
 
-```
+``` json
    {
       "ifMIB": {
           "name": "ifMIB",
@@ -77,7 +79,7 @@ would hold information such as:
             "1993-11-08 21:55"
           ]
         },
-      ...
+      // ...
       "ifTestTable": {
         "name": "ifTestTable",
         "oid": "1.3.6.1.2.1.31.1.3",
@@ -108,7 +110,7 @@ would hold information such as:
         },
         "maxaccess": "read-write"
       },
-      ...
+      // ...
    }
 ```
 
@@ -119,13 +121,14 @@ file.
 
 Besides one-to-one MIB conversion, PySMI library can produce JSON index to
 facilitate fast MIB information lookup across large collection of MIB files.
+
 For example, JSON index for
 [IP-MIB.json](https://mibs.pysnmp.com/json/asn1/IP-MIB),
 [TCP-MIB.json](https://mibs.pysnmp.com/json/asn1/TCP-MIB) and
 [UDP-MIB.json](https://mibs.pysnmp.com/json/asn1/UDP-MIB)
 modules would keep information like this:
 
-```
+``` json
    {
       "compliance": {
          "1.3.6.1.2.1.48.2.1.1": [
@@ -196,5 +199,5 @@ If something does not work as expected,
 post your question [on Stack Overflow](https://stackoverflow.com/questions/ask).
 
 Copyright (c) 2015-2020, [Ilya Etingof](mailto:[email protected]).
-Copyright (c) 2022, [LeXtudio Inc.](mailto:[email protected]).
+Copyright (c) 2022-2024, [LeXtudio Inc.](mailto:[email protected]).
 All rights reserved.

docs/source/conf.py

@@ -56,7 +56,7 @@
 master_doc = "index"
 
 # General information about the project.
-project = "SNMP SMI compiler"
+project = "SNMP SMI Compiler"
 copyright = "2015-2020, Ilya Etingof; © Copyright 2022-2024, LeXtudio Inc."
 author = "LeXtudio Inc. <[email protected]>"
 

docs/source/library-reference.rst → docs/source/docs/api-reference.rst

@@ -1,5 +1,4 @@
-
-PySMI library
+PySMI Library
 =============
 
 The *MibCompiler* object is the top-most interface to PySMI library features.
@@ -43,8 +42,8 @@ This example showcases some of its features:
 .. toctree::
    :maxdepth: 2
 
-   /pysmi/compiler/mibcompiler
-   /pysmi/compiler/mibstatus
+   /docs/compiler/mibcompiler
+   /docs/compiler/mibstatus
 
 MIB sources
 -----------
@@ -57,10 +56,10 @@ possible changes to MIB file name.
 .. toctree::
    :maxdepth: 2
 
-   /pysmi/reader/localfile/filereader
-   /pysmi/reader/zipreader/zipreader
-   /pysmi/reader/httpclient/httpreader
-   /pysmi/reader/callback/callbackreader
+   /docs/reader/localfile/filereader
+   /docs/reader/zipreader/zipreader
+   /docs/reader/httpclient/httpreader
+   /docs/reader/callback/callbackreader
 
 Conditional compilation
 -----------------------
@@ -83,9 +82,9 @@ such filtering.
 .. toctree::
    :maxdepth: 2
 
-   /pysmi/searcher/pyfile/pyfilesearcher
-   /pysmi/searcher/pypackage/pypackagesearcher
-   /pysmi/searcher/stub/stubsearcher
+   /docs/searcher/pyfile/pyfilesearcher
+   /docs/searcher/pypackage/pypackagesearcher
+   /docs/searcher/stub/stubsearcher
 
 Parser configuration
 --------------------
@@ -99,8 +98,8 @@ grammars as well as to recover from well-known errors in MIB files.
 .. toctree::
    :maxdepth: 2
 
-   /pysmi/parser/smi/parserfactory
-   /pysmi/parser/smi/dialect
+   /docs/parser/smi/parserfactory
+   /docs/parser/smi/dialect
 
 Code generators
 ---------------
@@ -111,9 +110,9 @@ AST into desired representation of the MIB.
 .. toctree::
    :maxdepth: 2
 
-   /pysmi/codegen/jsondoc/jsoncodegen
-   /pysmi/codegen/pysnmp/pysnmpcodegen
-   /pysmi/codegen/null/nullcodegen
+   /docs/codegen/jsondoc/jsoncodegen
+   /docs/codegen/pysnmp/pysnmpcodegen
+   /docs/codegen/null/nullcodegen
 
 Borrow pre-compiled MIBs
 ------------------------
@@ -127,8 +126,8 @@ already transformed MIB to complete the request successfully.
 .. toctree::
    :maxdepth: 2
 
-   /pysmi/borrower/anyfile/anyfileborrower
-   /pysmi/borrower/pyfile/pyfileborrower
+   /docs/borrower/anyfile/anyfileborrower
+   /docs/borrower/pyfile/pyfileborrower
 
 Write compiled MIBs
 -------------------
@@ -139,31 +138,6 @@ object given to :ref:`MibCompiler <compiler.MibCompiler>` on instantiation.
 .. toctree::
    :maxdepth: 2
 
-   /pysmi/writer/localfile/filewriter
-   /pysmi/writer/pyfile/pyfilewriter
-   /pysmi/writer/callback/callbackwriter
-
-Examples
---------
-
-The following examples focus on various feature of the PySMI library.
-
-.. toctree::
-   :maxdepth: 2
-
-   /examples/download-and-compile-smistar-mibs-into-json.rst
-   /examples/download-and-compile-smistar-mibs-into-pysnmp-files.rst
-   /examples/compile-smistar-mibs-into-pysnmp-files-if-needed.rst
-   /examples/compile-smiv2-mibs-from-text-into-pysnmp-code.rst
-   /examples/borrow-precompiled-pysnmp-files-on-failure.rst
-   /examples/always-borrow-precompiled-pysnmp-files.rst
-
-In case of any troubles or confusion, try enabling PySMI debugging
-and watch the output:
-
-.. code-block:: python
-
-   from pysmi import debug
-
-   debug.setLogger(debug.Debug('all'))
-
+   /docs/writer/localfile/filewriter
+   /docs/writer/pyfile/pyfilewriter
+   /docs/writer/callback/callbackwriter

docs/source/mibcopy.rst → docs/source/docs/mibcopy.rst

@@ -1,5 +1,5 @@
 
-The *mibcopy* tool
+The *mibcopy* Tool
 ==================
 
 .. toctree::

docs/source/mibdump.rst → docs/source/docs/mibdump.rst

@@ -1,5 +1,5 @@
 
-The *mibdump* tool
+The *mibdump* Tool
 ==================
 
 .. toctree::

docs/source/download.rst

@@ -1,15 +1,24 @@
+.. include:: /includes/_links.rst
 
-Download & Install
-==================
+Downloads
+=========
 
-The best way to obtain SNMP SMI library is by running `pip`:
+.. toctree::
+   :maxdepth: 2
+
+The PySMI software is provided under terms and conditions of BSD-style
+license, and can be freely downloaded from `PySMI PyPI package`_.
+
+Besides official releases, if you want to try the cutting-edge development
+code then it could be taken from `PySMI GitHub repository`_. It may
+be less stable in regards to general operation and changes to public
+interfaces, but it's first to contain fixes to recently discovered bugs.
+
+The best way to obtain PySMI and dependencies is to run:
 
 .. code-block:: bash
 
-   $ virtualenv venv
-   $ source venv/bin/activate
-   $ pip install pysmi-lextudio
+   pip install pysmi-lextudio
 
-Alternatively, you can download the latest release from
-`GitHub <https://github.com/lextudio/pysmi/releases>`_
-or `PyPI <https://pypi.org/project/pysmi-lextudio/>`_.
+In case of any issues, please open a new `GitHub issue`_ so we could try to
+help out.

docs/source/includes/_links.rst

@@ -0,0 +1,33 @@
+.. toctree::
+
+.. _LeXtudio Inc.: https://www.lextudio.com
+.. _PySNMP PyPI package: http://pypi.python.org/pypi/pysnmp-lextudio
+.. _PySMI PyPI package: http://pypi.python.org/pypi/pysmi-lextudio
+.. _PySNMP GitHub repository: https://github.com/lextudio/pysnmp
+.. _PySMI GitHub repository: https://github.com/lextudio/pysmi
+.. _GitHub issue: https://github.com/lextudio/pysnmp/issues/new
+.. _Stack Overflow: http://stackoverflow.com/questions/tagged/pysnmp
+.. _demo.pysnmp.com: https://www.pysnmp.com/snmp-simulation-service#
+.. _mibs.pysnmp.com: https://mibs.pysnmp.com/
+.. _PySMI: https://www.pysnmp.com/pysmi/
+.. _PySNMP: https://www.pysnmp.com/pysnmp/
+.. _SNMP Proxy Forwarder: https://www.pysnmp.com/snmpfwd/
+.. _snmpsim: https://www.pysnmp.com/snmpsim/
+.. _PyASN1: https://pyasn1.readthedocs.io/
+.. _mibdump: https://www.pysnmp.com/pysmi/mibdump
+.. _command line tools: https://www.pysnmp.com/snmpclitools/
+.. _Python: https://www.python.org/
+.. _SNMP: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol
+.. _PSF: https://www.python.org/psf/
+.. _ASN.1: https://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One
+.. _RFC3413: https://www.ietf.org/rfc/rfc3413.txt
+.. _RFC3418: https://www.ietf.org/rfc/rfc3418.txt
+.. _pyenv: https://github.com/pyenv/pyenv
+.. _pyenv-win: https://github.com/pyenv-win/pyenv-win
+.. _Wireshark: https://www.wireshark.org/
+.. _tcpdump: https://www.tcpdump.org/
+.. _Net-SNMP: http://www.net-snmp.org/
+.. _IF-MIB: https://mibs.pysnmp.com/asn1/IF-MIB
+.. _IF-MIB.json: https://mibs.pysnmp.com/json/fulltexts/IF-MIB.json
+.. _full index: https://mibs.pysnmp.com/json/index.json
+.. _SNMP SMI: https://en.wikipedia.org/wiki/Management_information_base