Skip to content

Commit 747b2fe

Browse files
edoputnemesifier
authored andcommitted
[doc] Improved "Create Your Backend" page
* added more instructions on how to use backends from plugins * added netjsonconfig as dependency in setup.py * explained how to use pip correctly * double quoted code keywords in create_your_backend.rst
1 parent 0f8f098 commit 747b2fe

File tree

1 file changed

+50
-11
lines changed

1 file changed

+50
-11
lines changed

docs/source/backends/create_your_backend.rst

Lines changed: 50 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ Create your backend
55
.. include:: ../_github.rst
66

77
Every backend is based on the common ground of some elements provided by the
8-
netjsonconfig library. The `BaseBackend`, `BaseConverter`, `BaseParser` and
9-
`BaseRenderer` are a battle proven set of tools that can be extended when
8+
netjsonconfig library. The ``BaseBackend``, ``BaseConverter``, ``BaseParser`` and
9+
``BaseRenderer`` are a battle proven set of tools that can be extended when
1010
creating you backend.
1111

1212
But the netjsonconfig package is not a playground to experiment, your contributions
@@ -21,13 +21,14 @@ project root directory.
2121

2222
.. code-block:: python
2323
24-
# setup.py
24+
# example_backend/setup.py
2525
from setuptools import setup, find_packages
2626
2727
setup(
2828
name='example_backend',
2929
version='0.0.0',
3030
description='an example to illustrate a netjsonconfig backend as an external module',
31+
install_requires=['netjsonconfig>=0.6.3'],
3132
packages=find_packages(),
3233
entry_points={
3334
'netjsonconfig.backends': [
@@ -42,7 +43,7 @@ in the python ecosystem. You can find more information about Python packaging
4243
and `at the hitchhikers guide to packaging <https://the-hitchhikers-guide-to-packaging.readthedocs.io/en/latest/>`_.
4344

4445
The most important part is to give your package a good name, a well thought description and
45-
to add the `entry_points` keyword argument with the following code
46+
to add the ``entry_points`` keyword argument with the following code
4647

4748
.. code-block:: python
4849
@@ -57,16 +58,16 @@ to add the `entry_points` keyword argument with the following code
5758
Now your package will be in the list of backends that netjsonconfig can use!
5859

5960
But we still have to give us a name to be unique! Netjsonconfig already
60-
defined the names `openwisp`, `openwrt` and `openvpn` but you can choose
61+
defined the names ``openwisp``, ``openwrt`` and ``openvpn`` but you can choose
6162
whatever you like most.
6263

63-
The name `netjsonconfig.backends` will be associated with a list of classes
64+
The name ``netjsonconfig.backends`` will be associated with a list of classes
6465
from your package that will be presented to netjconfig at runtime. To specify
65-
which classes you want to expose write the triple `name`, `path` and `class_name`
66-
using the format `name=path:class_name` as in the example below.
66+
which classes you want to expose write the triple ``name``, ``path`` and ``class_name``
67+
using the format ``name=path:class_name`` as in the example below.
6768

68-
The `path` part is simply the path to the file that contains the class
69-
you want to expose and the `class_name` is the name of the class.
69+
The ``path`` part is simply the path to the file that contains the class
70+
you want to expose and the ``class_name`` is the name of the class.
7071

7172
.. code-block:: python
7273
@@ -81,7 +82,7 @@ The previous example can be used with the following class definition
8182

8283
.. code-block:: python
8384
84-
# example_backend/__init__.py
85+
# example_backend/example_backend/__init__.py
8586
from netjsonconfig.backends.base.backend import BaseBackend
8687
from netjsonconfig.backends.base.renderer import BaseRenderer
8788
from netjsonconfig.backends.base.parser import BaseParser
@@ -93,3 +94,41 @@ The previous example can be used with the following class definition
9394
converter = []
9495
parser = BaseParser
9596
renderer = BaseRenderer
97+
98+
Once you have your python package configured with the correct entry points
99+
you should have a directory tree that looks like this.
100+
101+
.. code-block:: bash
102+
103+
$ tree example_backend
104+
example_backend
105+
├── example_backend
106+
│   └── __init__.py
107+
└── setup.py
108+
109+
And now you can install your package using ``pip install -e ./example_backend``
110+
or ``python setup.py install``.
111+
112+
As ``netjsonconfig`` is a dependency for ``example_backend`` you can use your backend
113+
directly from the command line, e.g.
114+
115+
.. code-block:: bash
116+
117+
$ netjsonconfig
118+
usage: netjsonconfig [-h] [--config CONFIG]
119+
[--templates [TEMPLATES [TEMPLATES ...]]]
120+
[--native NATIVE] --backend
121+
{openwrt,openwisp,openvpn,example} --method
122+
{render,generate,write,validate,json}
123+
[--args [ARGS [ARGS ...]]] [--verbose] [--version]
124+
netjsonconfig: error: the following arguments are required: --backend/-b, --method/-m
125+
126+
Notice the *example* in ``{openwrt,openwisp,openvpn,example}``? That's your backend!
127+
128+
The name exposed is the one chosen in the *name*, *path*, *class* triple
129+
from before
130+
131+
.. code-block:: python
132+
133+
# name=path:class
134+
'example=example_backend.__init__:ExampleBackend',

0 commit comments

Comments
 (0)