doc: use extlinks extension to manage links throughout

doc/devel/arch.rst

@@ -94,10 +94,9 @@ ensures the fastest simulation time as long as every simulator runs on its own
 physical CPU core.
 
 For the messages itself, interface-specific protocols are defined on top of the
-base SimBricks protocol (`lib/simbricks/base/proto.h
-<https://github.com/simbricks/simbricks/blob/main/lib/simbricks/base/proto.h#L118-L131>`_).
-The base SimBricks protocol stores two important fields at fixed offsets within
-the header (first 64 bytes) of each message:
+base SimBricks protocol (:lib-simbricks:`base/proto.h#L118-L131`). The base
+SimBricks protocol stores two important fields at fixed offsets within the
+header (first 64 bytes) of each message:
 
 * ``own_type`` - An integer identifying the type of message, required to
   correctly interpret the message when processing it later.
@@ -109,25 +108,21 @@ interface-specific protocol. Additionally, the message size is freely
 configurable per interface to accommodate payloads of arbitrary size.
 
 Let's walk through the memory protocol as a simple example. It is defined in the
-file `lib/simbricks/mem/proto.h
-<https://github.com/simbricks/simbricks/blob/main/lib/simbricks/mem/proto.h>`_
-and is used for the simulation of memory disaggregated systems. The high-level
-idea of memory disaggregation is that the host's memory resides somewhere
-externally, for example, it could be attached via the network. To simulate such
-a system, we introduced a simple memory simulator. In terms of the interface,
-the host issues read or write requests to the memory. For reads, the memory
-replies with the read value as the message's payload. Writes can be either
-regular or posted. For the former, the memory replies with a completion message
-while posted writes are send-and-forget.
+file :lib-simbricks:`mem/proto.h` and is used for the simulation of memory
+disaggregated systems. The high-level idea of memory disaggregation is that the
+host's memory resides somewhere externally, for example, it could be attached
+via the network. To simulate such a system, we introduced a simple memory
+simulator. In terms of the interface, the host issues read or write requests to
+the memory. For reads, the memory replies with the read value as the message's
+payload. Writes can be either regular or posted. For the former, the memory
+replies with a completion message while posted writes are send-and-forget.
 
 Notice that this interface is asymmetric, which means that we have to take into
 account the two directions when defining the different message types: host to
 memory (h2m) and memory to host (m2h). An interface doesn't have to necessarily
 be asymmetric. SimBricks also comes with a protocol for Ethernet
-(`lib/simbricks/network/proto.h
-<https://github.com/simbricks/simbricks/blob/main/lib/simbricks/network/proto.h>`_).
-Here, both sides transmit Ethernet packets to the other side in a
-send-and-forget manner, which is symmetric.
+(:lib-simbricks:`network/proto.h`). Here, both sides transmit Ethernet packets
+to the other side in a send-and-forget manner, which is symmetric.
 
 To define the layout of the different message types for the memory or any other
 interface-specific protocol, we simply add a struct per type containing the

doc/external_links.py

 """Definition of external links that can be used in Sphinx as :<key>:`%s`"""
 
 extlinks = {
-    # links to Python modules
+    'simbricks-repo': ('https://github.com/simbricks/simbricks%s', 'README%s'),
+    'gem5-fork': ('https://github.com/simbricks/gem5%s', None),
+    'slack': (
+        'https://join.slack.com/t/simbricks/shared_invite/zt-16y96155y-xspnVcm18EUkbUHDcSVonA%s',
+        None
+    ),
     'mod-orchestration': (
         'https://github.com/simbricks/simbricks/blob/main/experiments/simbricks/orchestration/%s',
         'orchestration/%s'
-    )
+    ),
+    'lib-simbricks': (
+        'https://github.com/simbricks/simbricks/blob/f260bf16b0bd110c3f1d48b851688f27c3f38a53/lib/simbricks/%s',
+        'lib/simbricks/%s'
+    ),
 }

doc/simulators/gem5.rst

@@ -27,17 +27,16 @@ gem5
 
 `gem5 <https://www.gem5.org/>`_ is a modular computer architecture simulator
 that can be configured to simulate a very broad range of different systems. For
-now, we maintain our own fork of gem5 `on GitHub
-<https://github.com/simbricks/gem5>`_, which contains our SimBricks adapters, a
-Python configuration script for full system x86 simulations with SimBricks
-adapters, and a few other extensions, such as MSI-X support. In the long term,
-we hope to upstream these changes.
+now, we maintain our :gem5-fork:`own fork of gem5 <>` on GitHub, which contains
+our SimBricks adapters, a Python configuration script for full system x86
+simulations with SimBricks adapters, and a few other extensions, such as MSI-X
+support. In the long term, we hope to upstream these changes.
 
 SimBricks Adapters
 ==================
 We have added SimBricks adapters for PCI and Ethernet. The source for these
-adapters and additional helper code are in `src/simbricks
-<https://github.com/simbricks/gem5/tree/main/src/simbricks>`_ in the gem5 repo.
+adapters and additional helper code are in
+:gem5-fork:`src/simbricks </tree/main/src/simbricks>` in the gem5 repo.
 
 Common Functionality
 --------------------

doc/user/howto.rst

@@ -66,9 +66,10 @@ If you plan to simulate a topology with multiple hosts, it may be helpful to
 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
-the following command from anywhere:
+Finally, to run your experiment, invoke
+:simbricks-repo:`experiments/run.py </blob/main/experiments/run.py>`
+and provide the path to your experiment module. In our docker containers, you
+can also just use the following command from anywhere:
 
 .. code-block:: bash
 

doc/user/orchestration.rst

@@ -49,7 +49,8 @@ connected. To define one, instantiate the class
 :class:`~simbricks.orchestration.experiments.Experiment` in your own Python
 module, which has member functions to further define the component simulators to
 run. SimBricks comes with many pre-defined experiments, which can serve as
-starting guides and are located in the repository under ``experiments/pyexps``.
+starting guides and are located in the repository under
+:simbricks-repo:`experiments/pyexps </blob/main/experiments/pyexps>`.
 
 .. autoclass:: simbricks.orchestration.experiments.Experiment
   :members: add_host, add_pcidev, add_nic, add_network, checkpoint
@@ -179,9 +180,10 @@ Running Experiments
 ******************************
 
 To run experiments using our orchestration framework, use the
-``experiments/run.py`` script. For your convenience, you can also use
-``simbricks-run`` in the Docker images from anywhere to run experiments. In
-practice, running experiments will look similar to this:
+:simbricks-repo:`experiments/run.py </blob/main/experiments/run.py>` script. For
+your convenience, you can also use ``simbricks-run`` in the Docker images from
+anywhere to run experiments. In practice, running experiments will look similar
+to this:
 
 .. code-block:: bash
 
@@ -189,7 +191,8 @@ practice, running experiments will look similar to this:
   # only available inside docker images
   $ simbricks-run --verbose --force pyexps/simple_ping.py
 
-Here are all the command line arguments for the ``experiments/run.py`` script:
+Here are all the command line arguments for the
+:simbricks-repo:`experiments/run.py </blob/main/experiments/run.py>` script:
 
 .. code-block:: text
 
@@ -288,8 +291,8 @@ second run, you can save the time for creating the checkpoint.
 Distributed Simulations
 ******************************
 
-For the moment, refer to our `GitHub Q&A on this topic
-<https://github.com/simbricks/simbricks/discussions/73#discussioncomment-6682260>`_.
+For the moment, refer to our
+:simbricks-repo:`GitHub Q&A on this topic </discussions/73#discussioncomment-6682260>`.
 
 
 ******************************

doc/user/quickstart.rst

@@ -28,9 +28,7 @@ Getting Started
 Welcome! We are happy that you want to give SimBricks a try.
 
 The easiest way to get started with just running a simulation is to use our
-Docker images, see our `README
-<https://github.com/simbricks/simbricks#using-pre-built-docker-images>`_ for
-details.
+Docker images, see :simbricks-repo:`#using-pre-built-docker-images` for details.
 
 Where you go from here depends on what you plan to do with SimBricks. Our
 :ref:`sec-howto` section provides instructions for some common scenarios. In
@@ -42,9 +40,8 @@ SimBricks simulations.
 
 If you are planning on making changes to the implementation of SimBricks
 components, you may next want to make sure you can build SimBricks from source.
-For instructions, refer to our `Quick Start section in the README
-<https://github.com/simbricks/simbricks#quick-start>`_. We recommend diving into
-our :ref:`sec-devel` for learning about the SimBricks architecture, internals,
-and APIs.
+For instructions, refer to :simbricks-repo:`#quick-start`. We recommend diving
+into our :ref:`sec-devel` for learning about the SimBricks architecture,
+internals, and APIs.
 
 If you run into problems please refer to :ref:`sec-troubleshoot-getting-help`.
\ No newline at end of file

doc/user/troubleshooting.rst

@@ -36,11 +36,10 @@ Getting Help
 ******************************
 
 We love to hear from you. If you have questions, want to discuss an idea, or
-encountered issues while using SimBricks, we are available on `Slack
-<https://join.slack.com/t/simbricks/shared_invite/zt-16y96155y-xspnVcm18EUkbUHDcSVonA>`_
+encountered issues while using SimBricks, we are available on :slack:`Slack <>`
 for quick answers and interactive discussions. If you find bugs or want to
-request a feature, feel free to open an `issue on GitHub
-<https://github.com/simbricks/simbricks/issues>`_.
+request a feature, feel free to open an
+:simbricks-repo:`Issue on GitHub </issues>`.
 
 
 .. _sec-convert-qcow-images-to-raw: