Commit 25feb431 authored by Ales Mrazek's avatar Ales Mrazek

sphinx documentation

parent 4a722c62
......@@ -20,7 +20,7 @@ example-data.json
``example-data.json`` is example of Json-encoded file, which is valid against `resolvers-yang` data model
If you edit this Json, you can validate it against data model using::
You can edit this Json and validate it against data model using::
$ make validate
......@@ -42,8 +42,8 @@ If generated ``unbound.conf`` is converted to JSON using ``unb_to_json.py`` scri
unb_to_json.py
============================
This script will convert ``unbound.conf`` to valid ``unb-data.json``.
As example configuration file can be used ``unbound.conf`` created after running ``generate_conf.py``
This script will convert Unbound configuration text file``unbound.conf`` to `resolvers-yang` data model valid Json-encoded file ``unb-data.json``.
As example configuration file can be used ``unbound.conf`` created by running ``generate_conf.py``
Run ``unb_to_conf.py`` with path to ``unbound.conf`` as parameter::
......@@ -51,4 +51,4 @@ Run ``unb_to_conf.py`` with path to ``unbound.conf`` as parameter::
No output means that the JSON data in created ``unb-data.json`` is valid.
If you generate another ``unbound.conf`` from this Json, it should be equal to ``unbound.conf``, which was used as input parameter to ``unb_to_json.py`` script.
\ No newline at end of file
If you generate another ``unbound.conf`` from this Json using ``generate_conf.py`` script, it should be equal to ``unbound.conf``, which was used as input parameter to ``unb_to_json.py`` script.
\ No newline at end of file
......@@ -11,13 +11,13 @@ Library Usage
For better understanding, look at the :ref:`examples` and `Yangson library <https://yangson.labs.nic.cz/quickstart.html#>`_
`Yangson <https://yangson.labs.nic.cz/quickstart.html#>`_ is a library for working with JSON encoded configuration and state data modelled using the YANG data modelling language.
=============
Using Yangson
Yangson
=============
This `library <https://yangson.labs.nic.cz/quickstart.html#>`_ is used to load and validate data against data model.
`Yangson <https://yangson.labs.nic.cz/quickstart.html#>`_ is a Python3 library for working with JSON-encoded [RFC7951]_
configuration and state data modelled using the YANG [RFC7895]_
data modelling language. Here `Yangson` is used to work with data model and validate loaded Json data against it.
Import necessary python modules.
......@@ -33,7 +33,7 @@ by reading YANG library data [RFC7895]_ from a file:
>>> model = DataModel.from_file('yang-modules/yanglib.json')
Load data from Json-encoded file
Load data from Json-encoded file [RFC7951]_
.. doctest::
......@@ -51,13 +51,13 @@ Validate data against the data model:
Now you can use Resolvers-YANG utilities.
=================
Library utilities
Library Modules
=================
Generator
---------
Import ``gen_unbound`` and ``gen_kresd`` functions to generate Unbound and Knot Resolver configuration strings from valid python dictionary loaded from Json.
Import ``gen_unbound`` and ``gen_kresd`` functions to generate Unbound and Knot Resolver configuration strings from valid python dictionary loaded from Json. Returns string.
.. doctest::
......@@ -65,12 +65,13 @@ Import ``gen_unbound`` and ``gen_kresd`` functions to generate Unbound and Knot
Call generator functions to generate `unbound.conf` and `kresd.conf`.
.. doctest::
>>> unbound_conf = gen_unbound(json_data)
>>> kresd_conf = gen_kresd(json_data)
``unbound_conf`` and ``kresd_conf`` are configuration strings , which can be save as text files.
Converter
---------
......@@ -79,18 +80,15 @@ Import ``from_unbound`` function for converting Unbound configuration string to
.. doctest::
>>> from resolvers_yang.converter import from_unbound
>>> from resolvers_yang.converter import from_unbound
Input parameter of ``from_unbound`` function is string loaded from ``unbound.con`` file. Returns python dictionary.
.. code-block:: python
# import of Converter module
from resolvers_yang.converter import from_unbound
# call of conversion function
json_data = Converter.from_unbound(unbound_conf)
.. doctest::
>>> json_data = from_unbound(unbound_conf)
``json_data`` variable is python dictionary, which can be easily validate against data model by ``Yangson`` library and save to Json-encoded file.
.. testcleanup::
......
......@@ -8,3 +8,7 @@ References
__ https://tools.ietf.org/html/rfc7895
.. [RFC7951] Lhotka, L. *JSON Encoding of Data Modeled with YANG.*
`RFC 7951`__, IETF, August 2016. 20 p. ISSN 2070-1721.
__ https://tools.ietf.org/html/rfc7951
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment