[network-topology-docs] Restructured Documentation: New Unified Documentation Website

docs/developer/index.rst

@@ -0,0 +1,16 @@
+Developer Docs
+==============
+
+.. include:: ../partials/developer-docs.rst
+
+.. toctree::
+    :maxdepth: 2
+
+    ./installation.rst
+    ./overriding-visualizer-templates.rst
+    ./extending.rst
+
+Other useful resources:
+
+    - :doc:`../user/rest-api`
+    - :doc:`../user/settings`

docs/developer/installation.rst

@@ -0,0 +1,119 @@
+Installation Instructions
+=========================
+
+.. include:: ../partials/developer-docs.rst
+
+.. contents:: **Table of contents**:
+    :depth: 2
+    :local:
+
+Installing for Development
+--------------------------
+
+Install the system dependencies:
+
+.. code-block:: shell
+
+    sudo apt install -y sqlite3 libsqlite3-dev
+    # Install system dependencies for spatialite which is required
+    # to run tests for openwisp-network-topology integrations with
+    # openwisp-network-topology and openwisp-monitoring.
+    sudo apt install libspatialite-dev libsqlite3-mod-spatialite
+
+Fork and clone the forked repository:
+
+.. code-block:: shell
+
+    git clone git://github.com/<your_fork>/openwisp-network-topology
+
+Navigate into the cloned repository:
+
+.. code-block:: shell
+
+    cd openwisp-network-topology/
+
+Start InfluxDB and Redis using Docker (required by the test project to run
+tests for :ref:`WiFi Mesh Integration
+<OPENWISP_NETWORK_TOPOLOGY_WIFI_MESH_INTEGRATION>`):
+
+.. code-block:: shell
+
+    docker-compose up -d influxdb redis
+
+Setup and activate a virtual-environment (we'll be using `virtualenv
+<https://pypi.org/project/virtualenv/>`_):
+
+.. code-block:: shell
+
+    python -m virtualenv env
+    source env/bin/activate
+
+Make sure that your base python packages are up to date before moving to
+the next step:
+
+.. code-block:: shell
+
+    pip install -U pip wheel setuptools
+
+Install development dependencies:
+
+.. code-block:: shell
+
+    pip install -e .
+    pip install -r requirements-test.txt
+
+Create database:
+
+.. code-block:: shell
+
+    cd tests/
+    ./manage.py migrate
+    ./manage.py createsuperuser
+
+You can access the admin interface at ``http://127.0.0.1:8000/admin/``.
+
+Run tests with:
+
+.. code-block:: shell
+
+    # Running tests without setting the "WIFI_MESH" environment
+    # variable will not run tests for WiFi Mesh integration.
+    # This is done to avoid slowing down the test suite by adding
+    # dependencies which are only used by the integration.
+    ./runtests.py
+    # You can run the tests only for WiFi mesh integration using
+    # the following command
+    WIFI_MESH=1 ./runtests.py
+
+Run qa tests:
+
+.. code-block:: shell
+
+    ./run-qa-checks
+
+Alternative Sources
+-------------------
+
+Pypi
+~~~~
+
+To install the latest stable version from pypi:
+
+.. code-block:: shell
+
+    pip install openwisp-network-topology
+
+Github
+~~~~~~
+
+To install the latest development version tarball via HTTPs:
+
+.. code-block:: shell
+
+    pip install https://github.com/openwisp/openwisp-network-topology/tarball/master
+
+Alternatively you can use the git protocol:
+
+.. code-block:: shell
+
+    pip install -e git+git://github.com/openwisp/openwisp-network-topology#egg=openwisp_network-topology

docs/developer/overriding-visualizer-templates.rst

@@ -0,0 +1,53 @@
+Overriding Visualizer Templates
+===============================
+
+.. include:: ../partials/developer-docs.rst
+
+Follow these steps to override and customize the visualizer's default
+templates:
+
+- create a directory in your django project and put its full path in
+  ``TEMPLATES['DIRS']``, which can be found in the django ``settings.py``
+  file
+- create a sub directory named ``netjsongraph`` and add all the templates
+  which shall override the default ``netjsongraph/*`` templates
+- create a template file with the same name of the template file you want
+  to override
+
+More information about the syntax used in django templates can be found in
+the `django templates documentation
+<https://docs.djangoproject.com/en/4.2/ref/templates/>`_.
+
+Example: Overriding the ``<script>`` Tag
+----------------------------------------
+
+Here's a step by step guide on how to change the javascript options passed
+to `netjsongraph.js <https://github.com/openwisp/netjsongraph.js>`_,
+remember to replace ``<project_path>`` with the absolute filesytem path of
+your project.
+
+**Step 1**: create a directory in
+``<project_path>/templates/netjsongraph``
+
+**Step 2**: open your ``settings.py`` and edit the ``TEMPLATES['DIRS']``
+setting so that it looks like the following example:
+
+.. code-block:: python
+
+    # settings.py
+    TEMPLATES = [
+        {
+            "DIRS": [os.path.join(BASE_DIR, "templates")],
+            # ... all other lines have been omitted for brevity ...
+        }
+    ]
+
+**Step 3**: create a new file named ``netjsongraph-script.html`` in the
+new ``<project_path>/templates/netjsongraph/`` directory, eg:
+
+.. code-block:: html
+
+    <!-- <project_path>/templates/netjsongraph/netjsongraph-script.html -->
+    <script>
+        // custom JS code here
+    </script>

docs/index.rst

@@ -0,0 +1,57 @@
+Network Topology
+================
+
+.. seealso::
+
+    **Source code**: `github.com/openwisp/openwisp-network-topology
+    <https://github.com/openwisp/openwisp-network-topology>`_.
+
+OpenWISP Network Topology is a network topology collector and visualizer
+web application and API, it allows to collect network topology data from
+different networking software (dynamic mesh routing protocols, OpenVPN),
+store it, visualize it, edit its details, it also provides hooks (a.k.a
+`Django signals <https://docs.djangoproject.com/en/3.1/topics/signals/>`_)
+to execute code when the status of a link changes.
+
+When used in conjunction with :doc:`OpenWISP Controller
+</controller/index>` and :doc:`OpenWISP Monitoring </monitoring/index>`,
+it :doc:`makes the monitoring system faster in detecting change to the
+network <./user/integrations>`.
+
+For a comprehensive overview of features, please refer to the
+:doc:`user/intro` page.
+
+The following diagram illustrates the role of the Network Topology module
+within the OpenWISP architecture.
+
+.. figure:: images/architecture-v2-openwisp-network-topology.png
+    :target: ../_images/architecture-v2-openwisp-network-topology.png
+    :align: center
+    :alt: OpenWISP Architecture: Network Topology module
+
+    **OpenWISP Architecture: highlighted network topology module**
+
+.. important::
+
+    For an enhanced viewing experience, open the image above in a new
+    browser tab.
+
+    Refer to :doc:`/general/architecture` for more information.
+
+.. toctree::
+    :caption: Network Topology Usage Docs
+    :maxdepth: 1
+
+    ./user/intro.rst
+    ./user/quickstart.rst
+    ./user/strategies.rst
+    ./user/integrations.rst
+    ./user/rest-api.rst
+    ./user/settings.rst
+    ./user/management-commands.rst
+
+.. toctree::
+    :caption: Network Topology Developer Docs
+    :maxdepth: 2
+
+    Developer Docs Index <developer/index.rst>

docs/partials/developer-docs.rst

@@ -0,0 +1,13 @@
+.. note::
+
+    This documentation page is aimed at developers who want to customize,
+    change or extend the code of OpenWISP Network Topology in order to
+    modify its behavior (eg: for personal or commercial purposes or to fix
+    a bug, implement a new feature or contribute to the project in
+    general).
+
+    If you aren't a developer and you are looking for information on how
+    to use OpenWISP, please refer to:
+
+    - :doc:`General OpenWISP Quickstart </user/quickstart>`
+    - :doc:`OpenWISP Network Topology User Docs </network-topology/index>`

docs/user/integrations.rst

@@ -0,0 +1,73 @@
+Integrations with other OpenWISP modules
+========================================
+
+If you use :doc:`OpenWISP Controller </controller/index>` or
+:doc:`OpenWISP Monitoring </monitoring/index>` and you use OpenVPN,
+Wireguard or ZeroTier for the management VPN, you can use the integration
+available in ``openwisp_network_topology.integrations.device``.
+
+This additional and optional module provides the following features:
+
+- whenever the status of a link changes:
+
+  - the management IP address of the related device is updated
+    straightaway
+  - if OpenWISP Monitoring is enabled, the device checks are triggered
+    (e.g.: ping)
+
+- if :doc:`OpenWISP Monitoring </monitoring/index>` is installed and
+  enabled, the system can automatically create topology for the WiFi Mesh
+  (802.11s) interfaces using the monitoring data provided by the agent.
+  You can enable this by setting
+  :ref:`OPENWISP_NETWORK_TOPOLOGY_WIFI_MESH_INTEGRATION
+  <openwisp_network_topology_wifi_mesh_integration>` to ``True``.
+
+This integration makes the whole system a lot faster in detecting
+important events in the network.
+
+.. include:: /partials/settings-note.rst
+
+In order to use this module simply add
+``openwisp_network_topology.integrations.device`` to ``INSTALLED_APPS``:
+
+.. code-block:: python
+
+    INSTALLED_APPS = [
+        # other apps (eg: openwisp-controller, openwisp-monitoring)
+        "openwisp_network_topology",
+        "openwisp_network_topology.integrations.device",
+        "openwisp_users.accounts",
+        "allauth",
+        "allauth.account",
+        "openwisp_users",
+        "rest_framework",
+    ]
+
+If you have enabled WiFI Mesh integration, you will also need to update
+the ``CELERY_BEAT_SCHEDULE`` as follow:
+
+.. code-block:: python
+
+    CELERY_BEAT_SCHEDULE = {
+        "create_mesh_topology": {
+            # This task generates the mesh topology from monitoring data
+            "task": "openwisp_network_topology.integrations.device.tasks.create_mesh_topology",
+            # Execute this task every 5 minutes
+            "schedule": timedelta(minutes=5),
+            "args": (
+                # List of organization UUIDs. The mesh topology will be
+                # created only for devices belonging these organizations.
+                [
+                    "4e002f97-eb01-4371-a4a8-857faa22fe5c",
+                    "be88d4c4-599a-4ca2-a1c0-3839b4fdc315",
+                ],
+                # The task won't use monitoring data reported
+                # before this time (in seconds)
+                6 * 60,  # 6 minutes
+            ),
+        },
+    }
+
+If you are enabling this integration on a pre-existing system, use the
+:ref:`create_device_nodes <network_topology_create_device_nodes>`
+management command to create the relationship between devices and nodes.

docs/user/intro.rst

@@ -0,0 +1,32 @@
+Network Topology: Features
+==========================
+
+OpenWISP Network Topology module offers robust features for managing,
+visualizing, and monitoring network topologies. Key features include:
+
+.. _network_topology_collectors:
+
+- **network topology collector** supporting different formats:
+      - NetJSON NetworkGraph
+      - OLSR (jsoninfo/txtinfo)
+      - batman-adv (jsondoc/txtinfo)
+      - BMX6 (q6m)
+      - CNML 1.0
+      - OpenVPN
+      - Wireguard
+      - ZeroTier
+      - additional formats can be added by `writing custom netdiff parsers
+        <https://github.com/openwisp/netdiff#parsers>`_
+- **network topology visualizer** based on `netjsongraph.js
+  <https://github.com/openwisp/netjsongraph.js>`_
+- :doc:`rest-api` that exposes data in `NetJSON <http://netjson.org>`__
+  *NetworkGraph* format
+- **admin interface** that allows to easily manage, audit, visualize and
+  debug topologies and their relative data (nodes, links)
+- :ref:`RECEIVE network topology data <network_topology_receive_strategy>`
+  from multiple nodes
+- **topology history**: allows saving daily snapshots of each topology
+  that can be viewed in the frontend
+- **faster monitoring**: :doc:`integrates with OpenWISP Controller and
+  OpenWISP Monitoring <integrations>` for faster detection of critical
+  events in the network