docs: add more usage examples an move them to their own page

mroethke · mroethke · commit c7112e6a1ce3 · 2017-02-20T16:49:19.000+01:00
diff --git a/docs/conf.py b/docs/conf.py
@@ -36,6 +36,7 @@
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.autosectionlabel',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/docs/index.rst b/docs/index.rst
@@ -42,33 +42,8 @@ Download and Installation
 - ``python setup.py build``
 - ``python setup.py install``
 
-Example
--------
-::
-
-    from rtrlib import RTRManager, PfxvState
-
-    mgr = RTRManager('rpki-validator.realmv6.org', 8282)
-    mgr.start()
-    result = mgr.validate(12345, '10.10.0.0', 24)
-
-    if result == PfxvState.valid:
-        print('Prefix Valid')
-    elif result == PfxvState.invalid:
-        print('Prefix Invalid')
-    elif result == PfxvState.not_found:
-        print('Prefix not found')
-    else:
-        print('Invalid response')
-
-    # iterate over all ipv4 record and print them
-    for recordv4 in mgr.ipv4_records():
-        print(recordv4)
-
-    mgr.stop()
-
-
-Further examples can be found in the tools_ dir of the repository.
+For usage examples see here :ref:`here <Usage Examples>`
+or in the tools_ dir of the repository.
 
 
 .. _rtrlib-python: https://github.com/rtrlib/python-binding
@@ -82,6 +57,7 @@ Contents:
 
    api
    callbacks
+   usage
 
 
 
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -0,0 +1,80 @@
+
+Usage Examples
+==============
+
+Validation
+----------
+
+::
+
+    from rtrlib import RTRManager, PfxvState
+
+    mgr = RTRManager('rpki-validator.realmv6.org', 8282)
+    mgr.start()
+    result = mgr.validate(12345, '10.10.0.0', 24)
+
+    if result == PfxvState.valid:
+        print('Prefix Valid')
+    elif result == PfxvState.invalid:
+        print('Prefix Invalid')
+    elif result == PfxvState.not_found:
+        print('Prefix not found')
+    else:
+        print('Invalid response')
+
+    mgr.stop()
+
+
+PFX Table iteration (with iterator)
+-----------------------------------
+
+::
+
+    from rtrlib import RTRManager, PfxvState
+
+    mgr = RTRManager('rpki-validator.realmv6.org', 8282)
+    mgr.start()
+    result = mgr.validate(12345, '10.10.0.0', 24)
+
+    for recordv4 in mgr.ipv4_records():
+        print(recordv4)
+
+    mgr.stop()
+
+
+PFX Table iteration (with callback)
+-----------------------------------
+
+::
+
+    from rtrlib import RTRManager, PfxvState
+
+    def callback(pfx_record, data):
+        print(pfx_record)
+
+    mgr = RTRManager('rpki-validator.realmv6.org', 8282)
+    mgr.start()
+    result = mgr.validate(12345, '10.10.0.0', 24)
+
+    mgr.for_each_ipv4_record(callback, None)
+
+    mgr.stop()
+
+
+Print PFX updates
+-------------------
+
+::
+
+    from rtrlib import RTRManager, register_pfx_update_callback
+
+    def callback(pfx_record, added):
+        print('%s %s' % ('+' if added else '-', pfx_record))
+
+    register_pfx_update_callback(callback)
+
+    mgr = RTRManager('rpki-validator.realmv6.org', 8282)
+    mgr.start()
+
+    mgr.stop()
+

Original file line number	Diff line number	Diff line change
`@@ -36,6 +36,7 @@`
`36`	`36`	`'sphinx.ext.coverage',`
`37`	`37`	`'sphinx.ext.viewcode',`
`38`	`38`	`'sphinx.ext.intersphinx',`
	`39`	`+ 'sphinx.ext.autosectionlabel',`
`39`	`40`	`]`
`40`	`41`
`41`	`42`	`# Add any paths that contain templates here, relative to this directory.`