doc: link to Modules on GitHub instead of rendering them in documentation

To manage external links such as for Python Modules, we are now using the extension sphinx.ext.extlinks to define all of them in the file doc/external_links.py.

doc/conf.py

@@ -15,8 +15,9 @@
 
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../experiments'))
-
+sys.path.append(os.path.abspath('../experiments'))
+sys.path.append(os.path.abspath('.'))
+from external_links import *
 
 # -- Project information -----------------------------------------------------
 
@@ -44,7 +45,8 @@ release = ''
 extensions = [
     'breathe',
     'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon'
+    'sphinx.ext.napoleon',
+    'sphinx.ext.extlinks'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

doc/external_links.py

+"""Definition of external links that can be used in Sphinx as :<key>:`%s`"""
+
+extlinks = {
+    # links to Python modules
+    'mod-orchestration': (
+        'https://github.com/simbricks/simbricks/blob/main/experiments/simbricks/orchestration/%s',
+        'orchestration/%s'
+    )
+}

doc/user/howto.rst

@@ -37,34 +37,34 @@ Create and Run an Experiment
 Experiments are defined in a declarative fashion inside Python modules using
 classes. Basically, create a `.py` file and add a global variable
 ``experiments``, a list which contains multiple instances of the class
-:class:`simbricks.orchestration.experiments.Experiment`, each one describing a
+:class:`~simbricks.orchestration.experiments.Experiment`, each one describing a
 standalone experiment. This is very helpful if you wish to evaluate your work in
 different environments, for example, you may want to swap out some simulator or
 investigate multiple topologies with different scale. 
 
 The class :class:`~simbricks.orchestration.experiments.Experiment` provides
 methods to add the simulators you wish to run. All available simulators can be
-found in the module :mod:`simbricks.orchestration.simulators`. Instantiating
+found in the module :mod-orchestration:`simulators.py`. Instantiating
 :class:`~simbricks.orchestration.simulators.HostSim` requires you to specify a
 :class:`~simbricks.orchestration.nodeconfig.NodeConfig`, which contains the
 configuration for your host, for example, its networking settings, how much
 system memory it should have, and most importantly, which applications to run by
 assigning an :class:`~simbricks.orchestration.nodeconfig.AppConfig`. You can
 find predefined classes for node and app configs in the module
-:mod:`simbricks.orchestration.nodeconfig`. Feel free to add new ones or just
-create a new class locally in your experiment's module. For more details, see :ref:`sec-orchestration`.
+:mod-orchestration:`nodeconfig.py`. Feel free to add new ones or just create a
+new class locally in your experiment's module. For more details, see
+:ref:`sec-orchestration`.
 
 The last step to complete your virtual testbed is to specify which virtual
 components connect to each other. You do this by invoking the respective methods
 on the simulators you have instantiated. See the different simulator types' base
-classes in the module :mod:`~simbricks.orchestration.simulators` for more
-information. A simple and complete experiment module in which a client host
-pings a server can be found :ref:`below <simple_ping_experiment>`.
+classes in the module :mod-orchestration:`simulators.py` for more information. A
+simple and complete experiment module in which a client host pings a server can
+be found :ref:`below <simple_ping_experiment>`.
 
 If you plan to simulate a topology with multiple hosts, it may be helpful to
-take a look at the module :mod:`simbricks.orchestration.simulator_utils` in
-which we provide some helper functions to reduce the amount of code you have to
-write.
+take a look at the module :mod-orchestration:`simulator_utils.py` in which we
+provide some helper functions to reduce the amount of code you have to write.
 
 Finally, to run your experiment, invoke ``experiments/run.py`` and provide the
 path to your experiment module. In our docker containers, you can also just use
@@ -106,13 +106,13 @@ Add a Node or Application Config
 
 A host's configuration and the workload to run are defined via
 :ref:`sec-node_app_config`. SimBricks already comes with a few examples in the
-module :mod:`simbricks.orchestration.nodeconfig`. If they don't fit your
-use-case, you need to add your own by overriding the pre-defined member
-functions of :class:`~simbricks.orchestration.nodeconfig.NodeConfig` and
-:class:`~simbricks.orchestration.nodeconfig.AppConfig`. The most notably is
-:meth:`~simbricks.orchestration.nodeconfig.AppConfig.run_cmds`, which defines
+module :mod-orchestration:`nodeconfig.py`. If they don't fit your use-case, you
+need to add your own by overriding the pre-defined member functions of
+:class:`~simbricks.orchestration.nodeconfig.NodeConfig` and
+:class:`~simbricks.orchestration.nodeconfig.AppConfig`. The most important one
+is :meth:`~simbricks.orchestration.nodeconfig.AppConfig.run_cmds`, which defines
 the commands to execute for your workload/application. Further information can
-be found in the module :mod:`simbricks.orchestration.nodeconfig` directly.
+be found in the module :mod-orchestration:`nodeconfig.py` directly.
 
 .. _sec-howto-custom_image:
 
@@ -130,10 +130,10 @@ SimBricks adapter for it. You can find the necessary information in the
 experiments and setting up the communication channels with other simulators more
 convenient, add a class for the simulator to the orchestration framework that
 inherits from :class:`~simbricks.orchestration.simulators.Simulator` or one of
-the more specialized base classes in :mod:`simbricks.orchestration.simulators`.
-In this class you define the command to execute the simulator together with
-further parameters, for example, to connect to the communication channels with
-other simulators. Below is an example of what this looks like.
+the more specialized base classes in :mod-orchestration:`simulators.py`. In
+this class you define the command to execute the simulator together with further
+parameters, for example, to connect to the communication channels with other
+simulators. Below is an example of what this looks like.
 
 .. code-block:: python
   :linenos:

doc/user/orchestration.rst

@@ -71,18 +71,15 @@ in this case. For more information, see :ref:`sec-checkpointing`.
 Component Simulators
 ====================
 
-SimBricks comes with multiple, ready-to-use component simulators for your
-experiments in :mod:`simbricks.orchestration.simulators`. These include host,
-NIC, network, and PCIe device simulators. On the orchestration side, each
-simulator is implemented in a class deriving from
+SimBricks defines multiple, ready-to-use component simulators in the module
+:mod-orchestration:`simulators.py`. These include host, NIC, network, and PCIe
+device simulators. Each simulator is defined by a class deriving from
 :class:`~simbricks.orchestration.simulators.Simulator`, which provides the
 necessary commands for their execution. We also offer more specialized base
 classes for the different component types, which implement common member
 functions, for example, to connect NICs or network component simulators to a
 host simulator.
 
-.. automodule:: simbricks.orchestration.simulators
-  
 .. autoclass:: simbricks.orchestration.simulators.Simulator
   :members: prep_cmds, run_cmd, resreq_cores, resreq_mem
 
@@ -125,8 +122,6 @@ specify additional files to be copied into the host. These are specified as key
 value pairs, where the key represents the path/filename inside the simulated
 guest system and the value is an IO handle of the file to be copied over.
 
-.. automodule:: simbricks.orchestration.nodeconfig
-
 .. autoclass:: simbricks.orchestration.nodeconfig.NodeConfig
   :members: ip, prefix, mtu, cores, memory, disk_image, app, run_cmds,
     cleanup_cmds, config_files 
@@ -157,10 +152,10 @@ advances its virtual time when there's nothing available to process.
 Link Latency and Synchronization Period
 ***************************************
 
-Most of the pre-defined simulators in :mod:`simbricks.orchestration.simulators`
-provide an attribute for tuning link latencies and the synchronization period.
-Both are configured in nanoseconds and apply to the message flow from the
-configured simulator to connected ones.
+Most of the pre-defined simulators in :mod-orchestration:`simulators.py` provide
+an attribute for tuning link latencies and the synchronization period. Both are
+configured in nanoseconds and apply to the message flow from the configured
+simulator to connected ones.
 
 Some simulators have interfaces for different link types, for example, NIC
 simulators based on :class:`~simbricks.orchestration.simulators.NICSim` have a