opensourcerouting · eznix86 · Oct 17, 2023 · Oct 18, 2023 · Oct 18, 2023
diff --git a/doc/conf.py b/doc/conf.py
@@ -36,7 +36,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.todo", "sphinx.ext.graphviz", "sphinx.ext.autodoc"]
+extensions = ["sphinx.ext.todo", "sphinx.ext.graphviz", "sphinx.ext.autodoc", "sphinx_rtd_theme"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

diff --git a/doc/getting-started/first-test.rst b/doc/getting-started/first-test.rst
@@ -0,0 +1,114 @@
+:description: Writing your first topotato test
+
+=======================
+Writing your first test
+=======================
+
+
+Example test
+------------
+
+1. Create a new file called `test_sample.py` in topotato folder, containing a function, and a test:
+
+.. code-block:: python
+
+    # content of test_sample.py
+
+    #!/usr/bin/env python3
+    # SPDX-License-Identifier: GPL-2.0-or-later
+    # Copyright (C) 2018-2023  YOUR NAME HERE for NetDEF, Inc.
+    """
+    Simple demo test for topotato.
+    """
+
+    from topotato.v1 import *
+
+    @topology_fixture()
+    def topology(topo):
+        """
+        [ r1 ]---[ noprot ]
+        [    ]
+        [    ]---[ rip ]
+        [    ]
+        [    ]---[ ripng ]
+        [    ]
+        [    ]---[ ospfv2 ]
+        [    ]
+        [    ]---[ ospfv3 ]
+        [    ]
+        [    ]---[ isisv4 ]
+        [    ]
+        [    ]---[ isisv6 ]
+        """
+        topo.router("r1").iface_to("ripng").ip6.append("fc00:0:0:1::1/64")
+
+
+    class Configs(FRRConfigs):
+        routers = ["r1"]
+
+        zebra = """
+        #% extends "boilerplate.conf"
+        #% block main
+        #%   for iface in router.ifaces
+        interface {{ iface.ifname }}
+        description {{ iface.other.endpoint.name }}
+        no link-detect
+        !
+        #%   endfor
+        !
+        ip forwarding
+        ipv6 forwarding
+        !
+        #% endblock
+        """
+
+        ripd = """
+        #% extends "boilerplate.conf"
+        #% block main
+        debug rip events
+        debug rip zebra
+        !
+        router rip
+        version 2
+        network {{ router.iface_to('rip').ip4[0].network }}
+        #% endblock
+        """
+
+        ripngd = """
+        #% extends "boilerplate.conf"
+        #% block main
+        debug ripng events
+        debug ripng zebra
+        !
+        router ripng
+        network {{ router.iface_to('ripng').ip6[0].network }}
+        #% endblock
+        """
+
+
+    class AllStartupTest(TestBase, AutoFixture, topo=topology, configs=Configs):
+        """
+        docstring here
+        """
+
+        @topotatofunc
+        def test_running(self, topo, r1):
+            """
+            just check that all daemons are running
+            """
+            for daemon in Configs.daemons:
+                if not hasattr(Configs, daemon):
+                    continue
+                yield from AssertVtysh.make(r1, daemon, command="show version")
+
+
+2. Run the following command in your command line to run the test:
+
+.. code-block:: bash
+
+    ./run_userns.sh --frr-builddir=$PATH_TO_FRR_BUILD \
+                    --log-cli-level=DEBUG \
+                    -v -v -x \ 
+                    sameple_test.py 
+
+3. If you should see all your test in green it means every works fine.
diff --git a/doc/getting-started/installation.rst b/doc/getting-started/installation.rst
@@ -0,0 +1,48 @@
+:description: Topotato installation 
+
+=========================
+Installing topotato
+=========================
+
+
+Package installation
+--------------------
+
+Topotato lives inside FRR project so there is no installation for topotato itself.
+What is needed is to install its dependencies.
+
+.. note::
+    ``topotato`` requires Python >= 3.8
+
+Run theses commands below:
+
+
+.. code-block:: bash
+
+    sysctl -w kernel.unprivileged_userns_clone=1
+
+
+.. code-block::
+   :caption: Required packages
+
+    apt-get satisfy \
+        'graphviz' 'tshark (>=4.0)' 'wireshark-common (>=4.0)' 'tini' \
+        'python3 (>=3.8)' \
+        'python3-pytest (>=6.1)' 'python3-pytest-xdist' \
+        'python3-typing-extensions' 'python3-docutils' 'python3-pyinotify' \
+        'python3-scapy (>=2.4.5)' 'python3-exabgp (>=4.2)' \
+        'python3-jinja2 (>=3.1)' 'python3-lxml' 'python3-markupsafe' \
+        'wireshark-common' 'tini'
+
+
+.. note::
+    if you are using ``non-debian`` based distribution, you can install theses packages above and below manually
+
+    - unshare - run program with some namespaces unshared from parent
+    - nsenter - run program with namespaces of other processes
+    - tini_ - Tini is a tiny init
+    - dumpcap - Dump network traffic
+    - ip - show / manipulate routing, network devices, interfaces and tunnels
+
+
+.. _tini: https://github.com/krallin/tini
diff --git a/doc/getting-started/introduction.rst b/doc/getting-started/introduction.rst
@@ -0,0 +1,32 @@
+:description: Learn how to get started with Topotato for FRRouting
+
+=======================
+Welcome to Topotato 🔝🥔
+=======================
+
+Topotato is a work-in-progress test framework designed for conducting system-level conformance tests for FRRouting.
+Its primary purpose is to execute FRR through various scenarios and validate its behavior.
+
+Goals
+-----
+
+The creation of Topotato was motivated by addressing the limitations of the existing FRR test framework, topotests.
+
+Topotato aims to achieve the following objectives:
+
+- Enhance the readability and comprehensibility of tests, particularly when failures occur.
+- Improve the reliability of tests, ensuring consistent outcomes irrespective of factors like system load, parallelization, execution order, operating system, or architecture.
+- Simplify the test-writing process.
+- Minimize the variability in expressing a specific test, ideally reducing it to a single way. This streamlines the process of identifying the correct approach to articulate a test condition, minimizing the potential for creating unstable tests (i.e., flaky tests). A standardized approach to expressing tests also reduces the learning curve and facilitates troubleshooting when a test fails.
+- Enhance the utility of test reports, primarily for failure cases but also for successful ones. Test behavior and reasons for failure should be readily understandable without the need for extensive investigation, debugging statements, or repeated test runs.
+- Enable easy execution of the test suite on developers' local development systems, ensuring accessibility and speed.
+
+Secondary Goals
+---------------
+
+In addition to the primary objectives, Topotato also aims to achieve the following secondary goals, which are influenced by the aforementioned aims:
+
+- Encapsulate tests within a single file to eliminate the need to navigate through multiple files.
+- Replace hardcoded IP addresses with semantic expressions to improve readability. For instance, while ``192.168.13.57`` is an opaque IPv4 address, the expression ``r1.iface_to('r2').ip4[0]`` could represent the same address while being more comprehensible and easier to maintain.
+- Enable the test suite to run without necessitating "root" access to the system or the installation of FRR. This approach ensures ease of execution and guarantees that the test suite cannot disrupt the developer's system due to kernel-level protection. Additionally, it mitigates issues stemming from broken or mismatched installations.
+- Support FreeBSD.
diff --git a/doc/index.rst b/doc/index.rst
@@ -1,13 +1,27 @@
-topotato manual
 ===============
+Topotato Manual
+===============
+
+Getting Started (Guide)
+-----------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   getting-started/introduction
+   getting-started/installation
+   getting-started/first-test
+
+Topotato Internals
+------------------
 
 .. toctree::
    :maxdepth: 2
 
-   introduction
-   parse
-   assertions
-   machinery
-   frrglue
-   pytest_lowlevel
-   utils
+   internals/introduction
+   internals/parse
+   internals/assertions
+   internals/machinery
+   internals/frrglue
+   internals/pytest_lowlevel
+   internals/utils
diff --git a/doc/assertions.rst → doc/internals/assertions.rst b/doc/assertions.rst → doc/internals/assertions.rst
diff --git a/doc/frrglue.rst → doc/internals/frrglue.rst b/doc/frrglue.rst → doc/internals/frrglue.rst
diff --git a/doc/introduction.rst → doc/internals/introduction.rst b/doc/introduction.rst → doc/internals/introduction.rst
diff --git a/doc/machinery.rst → doc/internals/machinery.rst b/doc/machinery.rst → doc/internals/machinery.rst
diff --git a/doc/parse.rst → doc/internals/parse.rst b/doc/parse.rst → doc/internals/parse.rst
diff --git a/doc/pytest_lowlevel.rst → doc/internals/pytest_lowlevel.rst b/doc/pytest_lowlevel.rst → doc/internals/pytest_lowlevel.rst
diff --git a/doc/utils.rst → doc/internals/utils.rst b/doc/utils.rst → doc/internals/utils.rst
diff --git a/vm/ubuntu/topotato-install.sh b/vm/ubuntu/topotato-install.sh
@@ -9,3 +9,7 @@ sudo DEBIAN_FRONTEND=noninteractive apt install graphviz tshark \
    python3-venv wireshark-common python3-pip tini -y
 
 pip install -r requirements.txt
+
+# sphinx documentation
+
+pip install sphinx_rtd_theme