mkdocs: Fix doc/README.md and move the file listings to correct sections

- as it will be generated and injected via python script

doc/README.md

@@ -13,123 +13,221 @@ Beware if you previously pulled the `develop` branch that your repository may be
 
 ## General
 
-- [FEATURE_SET.md](./FEATURE_SET.md): lists supported features
-- [GET_SOURCES.md](./GET_SOURCES.md): how to download the sources
-- [BUILD.md](./BUILD.md): how to build the sources
-- [code-style-contrib.md](./code-style-contrib.md): overall working practices, code style, and review process
-- [cross-compile.md](./cross-compile.md): how to cross-compile OAI for ARM
-- [clang-format.md](./clang-format.md): how to format the code
-- [sanitizers.md](./dev_tools/sanitizers.md): how to run with ASan/UBSan/MemSAN/TSan
-- [environment-variables.md](./environment-variables.md): the environment variables used by OAI
-- [tuning_and_security.md](./tuning_and_security.md): performance and security considerations
+- [Contributing](../CONTRIBUTING.md): how to contribute to the project
+- [Changelog](../CHANGELOG.md): release notes and version history
+- [Notice](../NOTICE.md): third-party software credits and licenses
+- [License](../LICENSE): software license and terms of use
+- [Mailing Lists](https://gitlab.eurecom.fr/oai/openairinterface5g/-/wikis/MailingList): subscribe for updates and get support from the community.
+- [OAI Developer Meetings](https://gitlab.eurecom.fr/oai/openairinterface5g/-/wikis/OpenAirDevMeetings): weekly OAI Developer Calls open to all OAI community members
+- [System Requirements](./system_requirements.md): system requirements for running the OAI 4G/5G stack
+- [Feature Set](./FEATURE_SET.md): lists supported features
+- [Get Sources](./GET_SOURCES.md): how to download the sources
+- [Build](./BUILD.md): how to build the sources
+- [Code Style & Contribution](./code-style-contrib.md): overall working practices, code style, and review process
+- [Cross Compile](./cross-compile.md): how to cross-compile OAI for ARM
+- [Clang Format](./clang-format.md): how to format the code
+- [Sanitizers](./dev_tools/sanitizers.md): how to run with ASan/UBSan/MemSAN/TSan
+- [Environment Variables](./environment-variables.md): the environment variables used by OAI
+- [Tuning and Security](./tuning_and_security.md): performance and security considerations
 
 There is some general information in the [OpenAirInterface Gitlab Wiki](https://gitlab.eurecom.fr/oai/openairinterface5g/-/wikis/home)
 
 ## Tutorials
 
-- Step-by-step tutorials to set up 5G:
-    * [OAI 5GC](./NR_SA_Tutorial_OAI_CN5G.md)
-    * [OAI gNB with COTS UE](./NR_SA_Tutorial_COTS_UE.md)
-    * [OAI NR-UE](./NR_SA_Tutorial_OAI_nrUE.md)
-    * [Multiple OAI NR-UE with RFsimulator](./NR_SA_Tutorial_OAI_multi_UE.md)
-- [RUNMODEM.md](./RUNMODEM.md): Generic information on how to
-    * Run simulators
-    * Run with hardware
-    * Specific OAI modes (phy-test, do-ra, noS1)
-    * (5G) Using SDAP and custom DRBs
-    * IF setups and arbitrary frequencies
-    * MIMO
-- [How to run OAI with O-RAN 7.2 FHI](./ORAN_FHI7.2_Tutorial.md)
-- [How to run a 5G-NSA setup](./TESTING_OAI_NSA_COTS_UE.md)
-- [How to run a 4G setup using L1 simulator](./L1SIM.md) _Note: we recommend the RFsimulator_
-- [How to use the L2 simulator](./L2NFAPI.md)
-- [How to use the OAI channel simulator](../openair1/SIMULATION/TOOLS/DOC/channel_simulation.md)
-- [How to use GPU-accelerated channel simulation](../openair1/SIMULATION/TOOLS/DOC/gpu_acceleration.md)
-- [How to use multiple BWPs](./RUN_NR_multiple_BWPs.md)
+- [OAI 5GC](./NR_SA_Tutorial_OAI_CN5G.md): Step-by-step tutorial to set up 5G Core Network
+- [OAI gNB with COTS UE](./NR_SA_Tutorial_COTS_UE.md): Step-by-step tutorial for gNB with COTS-UE
+- [OAI NR-UE](./NR_SA_Tutorial_OAI_nrUE.md): Step-by-step tutorial for NR-UE
+- [Multiple OAI NR-UE with RFsimulator](./NR_SA_Tutorial_OAI_multi_UE.md): Setup for multiple UEs
+- [RUNMODEM](./RUNMODEM.md): Generic information on how to run simulators, run
+  with hardware, specific OAI modes (phy-test, do-ra, noS1), (5G) using SDAP and
+  custom DRBs, IF setups and arbitrary frequencies, and MIMO.
+- [How to run OAI with O-RAN 7.2 FHI](./ORAN_FHI7.2_Tutorial.md): Use OAI with O-RAN 7.2 fronthaul interface
+- [How to run a 5G-NSA setup](./TESTING_OAI_NSA_COTS_UE.md): Guide to set up and test 5G Non-Standalone (NSA)
+- [How to run a 4G setup using L1 simulator](./L1SIM.md): _Note: we recommend the RFsimulator_
+- [How to use the L2 simulator](./L2NFAPI.md): L2 nFAPI Simulator Usage
+- [How to use the OAI channel simulator](../openair1/SIMULATION/TOOLS/DOC/channel_simulation.md): Guide to configure and run OAI channel simulation
+- [How to use GPU-accelerated channel simulation](../openair1/SIMULATION/TOOLS/DOC/gpu_acceleration.md): CUDA GPU acceleration for channel simulation
 - [How to run OAI-VNF and OAI-PNF](./nfapi.md): how to run the FAPI/nFAPI split,
   including some general remarks on FAPI/nFAPI.
-- [How to use the positioning reference signal (PRS)](./RUN_NR_PRS.md)
-- [How to use device-to-device communication (D2D, 4G)](./d2d_emulator_setup.md)
-- [How to run with E2 agent](../openair2/E2AP/README.md)
-- [How to run the physical simulators](./physical-simulators.md)
-- [How to setup OAI with Nvidia Aerial and Foxconn](./Aerial_FAPI_Split_Tutorial.md)
-- [How to setup OAI with LDPC accelerators (Xilinx T2/Intel ACCs)](./LDPC_OFFLOAD_SETUP.md)
-- [How to setup OAI with the XDMA FPGA LDPC accelerator](./LDPC_XDMA_offload_setup.md)
-- [How to do a handover](./handover-tutorial.md)
-- [How to setup gNB frequency](./gNB_frequency_setup.md)
-- [How to use the RT data recording app](./data_recording.md)
-- [How to use packages](./packages.md)
+- [How to use the positioning reference signal (PRS)](./RUN_NR_PRS.md): How to run NR PRS with OAI gNB and nrUE
+- [How to use device-to-device communication (D2D, 4G)](./d2d_emulator_setup.md): Setup and test D2D communication in 4G
+- [How to run with E2 agent](../openair2/E2AP/README.md): Guide to deploy 5G OAI RAN with E2 Agent and FlexRIC nearRT-RIC
+- [How to run the physical simulators](./physical-simulators.md): Guide for using physims
+- [How to setup OAI with Nvidia Aerial and Foxconn](./Aerial_FAPI_Split_Tutorial.md): Guide to setup OAI with Nvidia Aerial FAPI split and Foxconn Radio Units
+- [How to setup OAI with LDPC accelerators (Xilinx T2/Intel ACCs)](./LDPC_OFFLOAD_SETUP.md): Guide to setup OAI LDPC offload
+- [How to setup OAI with the XDMA FPGA LDPC accelerator](./LDPC_XDMA_offload_setup.md): Guide to setup LDPC offload with XDMA driver
+- [How to do a handover](./handover-tutorial.md): Guide to perform F1 and N2 handovers
+- [How to setup gNB frequency](./gNB_frequency_setup.md): Instructions to configure 5G gNB frequency
+- [How to use the RT data recording app](./data_recording.md): Synchronized real-time 5G data recording
+- [How to use packages](./packages.md): Build OAI Deb/RPM packages using CMake
+- [NR LDPC AAL](../openair1/PHY/CODING/nrLDPC_coding/nrLDPC_coding_aal/README.md): implementation for O-RAN LDPC BBDEV
 
-Legacy unmaintained files:
-- [`L2NFAPI_NOS1.md`](./L2NFAPI_NOS1.md), [`L2NFAPI_S1.md`](./L2NFAPI_S1.md):
-  old L2simulator, not valid anymore
+### Legacy unmaintained files
+
+- [L2NFAPI_NOS1](./L2NFAPI_NOS1.md): old L2simulator, not valid anymore
+- [L2NFAPI_S1](./L2NFAPI_S1.md): old L2simulator, not valid anymore
 
 ## Designs
 
-- General software architecture notes: [SW_archi.md](./SW_archi.md)
-- [Information on E1](./E1AP/E1-design.md)
-- [Information on F1](./F1AP/F1-design.md)
-- [Information on how NR nFAPI works](./NR_NFAPI_archi.md)
-- [Flow graph of the L1 in gNB](SW-archi-graph.md)
-- [L1 threads in NR-UE](./nr-ue-design.md)
-- [Information on gNB MAC](./MAC/mac-usage.md)
-- [Information on gNB RRC](./RRC/rrc-usage.md)
-- [Information on analog beamforming implementation](./analog_beamforming.md)
-- [Information on the UE 5G NAS implementation](./5Gnas.md)
+- [Software Architecture](./SW_archi.md): General software architecture notes
+- [Information on E1](./E1AP/E1-design.md): E1 interface between CU-CP and CU-UP
+- [E1AP Procedures](./E1AP/e1ap_procedures.md): Information on E1 interface procedures
+- [F1AP Messages Encoding & Decoding Library](./F1AP/F1AP-lib.md): Library for encoding, decoding, and testing F1AP messages
+- [Information on F1](./F1AP/F1-design.md): F1 interface design between CU and DU
+- [Information on how NR nFAPI works](./NR_NFAPI_archi.md): SmallCellForum 5G (n)FAPI split and message handling
+- [Flow graph of the L1 in gNB](SW-archi-graph.md): L1 threading and scheduler flow in gNB
+- [L1 threads in NR-UE](./nr-ue-design.md): L1 PHY-MAC flow and UE thread processing
+- [Information on gNB MAC](./MAC/mac-usage.md): 5G MAC scheduler and configuration
+- [Information on gNB RRC](./RRC/rrc-usage.md): 5G RRC layer functioning and configuration
+- [5G RRC Layer](./RRC/rrc-dev.md): 5G RRC procedures and UE handling
+- [Information on analog beamforming implementation](./analog_beamforming.md): Implementation of analog beamforming in OAI codebase.
+- [Information on the UE 5G NAS implementation](./5Gnas.md): 5GS NAS protocol and its implementation in OAI
 - [Information on UL-MIMO](./UL_MIMO.md): UL-MIMO specific notes
+- [gNB RACH Processing](./rach_processing_in_gNB.md): gNB RACH handling from sample collection to response scheduling
 
 ## Building and running from images
 
-- [How to build images](../docker/README.md)
-- [How to run 5G with the RFsimulator from images](../ci-scripts/yaml_files/5g_rfsimulator/README.md)
-- [How to run 4G with the RFsimulator from images](../ci-scripts/yaml_files/4g_rfsimulator_fdd_05MHz/README.md)
-- [How to run physical simulators in OpenShift](../openshift/README.md)
+- [How to build images](../docker/README.md): Build and Use OAI with Docker/Podman
+- [How to run 5G with the RFsimulator from images](../ci-scripts/yaml_files/5g_rfsimulator/README.md): Run 5G NR using RF simulator with Docker containers
+- [How to run 4G with the RFsimulator from images](../ci-scripts/yaml_files/4g_rfsimulator_fdd_05MHz/README.md): Run 4G-LTE using RF simulator with Docker containers
+- [How to run physical simulators in OpenShift](../openshift/README.md): OpenShift Build and Usage Procedures
 
 ## Libraries
 
 ### General
 
-- The [T tracer](../common/utils/T/DOC/T.md): a generic tracing tool (VCD, Wireshark, GUI, to save for later, ...)
+- [T tracer](../common/utils/T/DOC/T.md): a generic tracing tool (VCD, Wireshark, GUI, to save for later, ...)
 - [OPT](../openair2/UTIL/OPT/README.txt): how to trace to wireshark
-- The [configuration module](../common/config/DOC/config.md)
-- The [logging module](../common/utils/LOG/DOC/log.md)
-- The [shared object loader](../common/utils/DOC/loader.md)
-- The [threadpool](../common/utils/threadPool/thread-pool.md) used in L1
-- The [LDPC implementation](../openair1/PHY/CODING/DOC/LDPCImplementation.md) is a shared library
-- The [time management](time_management.md) module
+- [Threadpool](../common/utils/threadPool/thread-pool.md): used in L1
+- [LDPC Implementation](../openair1/PHY/CODING/DOC/LDPCImplementation.md): It is a shared library
+- [Time Management](time_management.md): manages time for OAI components
+- [LTE RRC Configuration (ASN.1 Based)](../openair2/RRC/LTE/MESSAGES/README.md): generates LTE RRC data structures based on the ASN.1
+
+#### Configuration Module
+
+- [OAI Configuration Module](../common/config/DOC/config.md): Manages and validates OAI parameters
+- [Config Runtime Usage](../common/config/DOC/config/rtusage.md): overview of config runtime usage
+- [Config Architecture](../common/config/DOC/config/arch.md): config module source files and components
+- [Config Dev Usage API](../common/config/DOC/config/devusage/api.md): information on configuration module API
+- [Config Dev Usage Add A Param](../common/config/DOC/config/devusage/addaparam.md): add parameters in an existing section
+- [Config Dev Usage Add Param Set](../common/config/DOC/config/devusage/addparamset.md): add a parameter set in a new section
+- [Config Dev Usage Struct](../common/config/DOC/config/devusage/struct.md): configuration module public structures
+- [Config Dev Usage](../common/config/DOC/config/devusage.md): overview of config dev usage
+
+#### Loader
+
+- [Shared Object Loader](../common/utils/DOC/loader.md): manage modular shared libraries
+- [Loader Runtime Usage](../common/utils/DOC/loader/rtusage.md): information on loader runtime usage
+- [Loader Architecture](../common/utils/DOC/loader/arch.md): details on loader source files
+- [Loader Dev Usage Loading](../common/utils/DOC/loader/devusage/loading.md): implementation of a shared library dynamic load using the oai loader
+- [Loader Dev Usage API](../common/utils/DOC/loader/devusage/api.md): information on loader API
+- [Loader Dev Usage Struct](../common/utils/DOC/loader/devusage/struct.md): `loader_shlibfunc_t` structure
+- [Loader Dev Usage](../common/utils/DOC/loader/devusage.md): overview of loader dev usage
+
+
+#### Logging
+
+- [Logging Module](../common/utils/LOG/DOC/log.md): OAI console logging facility
+- [LOG Add Console Trace](../common/utils/LOG/DOC/addconsoletrace.md): Adding console traces in oai code
+- [LOG LTTng Logs](../common/utils/LOG/DOC/lttng_logs.md): OAI gNB LTTng Tracing Setup Guide
+- [LOG Configure Log](../common/utils/LOG/DOC/configurelog.md): Initializing and configuring the logging facility
+- [LOG Runtime Usage](../common/utils/LOG/DOC/rtusage.md): details on LOG Runtime Usage
+- [LOG Architecture](../common/utils/LOG/DOC/arch.md): logging facility source files
+- [LOG Dev Usage](../common/utils/LOG/DOC/devusage.md): logging facility developer usage
 
 ### Radios
 
 Some directories under `radio` contain READMEs:
 
-- [RFsimulator](../radio/rfsimulator/README.md)
-- [USRP](../radio/USRP/README.md)
-- [BladeRF](../radio/BLADERF/README.md)
-- [IQPlayer](../radio/iqplayer/DOC/iqrecordplayer_usage.md), and [general documentation](./iqrecordplayer_usage.md)
-- [fhi_72](../radio/fhi_72/README.md)
-- [vrtsim](../radio/vrtsim/README.md)
-- [rf_emulator](../radio/emulator/README.md)
+- [RFsimulator](../radio/rfsimulator/README.md): Guide to using the RF Simulator
+- [USRP](../radio/USRP/README.md): USRP Radio Setup and Usage Guide.
+- [BladeRF](../radio/BLADERF/README.md): BladeRF 2.0 Micro Setup instructions
+- [IQPlayer](./iqrecordplayer_usage.md): general documentation for the IQ player
+- [IQ Record Playback](../radio/iqplayer/DOC/iqrecordplayer_usage.md): specific usage documentation in the `radio` directory
+- [FHI 7.2](../radio/fhi_72/README.md): XRAN Driver (FHI 7.2) Setup
+- [vrtsim](../radio/vrtsim/README.md): VRTSim Setup and Usage Guide
+- [RF Emulator](../radio/emulator/README.md): RF Emulator Library
+- [Ethernet Drivers](../radio/ETHERNET/ethernet.md): Ethernet-based drivers for fronthaul
 
 The other SDRs (AW2S, LimeSDR, ...) have no READMEs.
 
 ### Special-purpose libraries
 
-- OAI has two scopes: one based on Xforms and one based on imgui, described in [this README](../openair1/PHY/TOOLS/readme.md)
-- OAI comes with an integrated [telnet server](../common/utils/telnetsrv/DOC/telnethelp.md) to monitor and control
-- OAI comes with an integrated [web server](../common/utils/websrv/DOC/websrv.md)
+- [OAI Scopes](../openair1/PHY/TOOLS/readme.md): OAI has two scopes (one based on Xforms and one based on imgui)
+
+#### Telnet Server
+
+- [Telnet Server Help](../common/utils/telnetsrv/DOC/telnethelp.md): OAI comes with an integrated telnet server to monitor and control
+- [Telnet Server](../common/utils/telnetsrv/DOC/telnetsrv.md): OAI embedded telnet server
+- [Telnet Add Command](../common/utils/telnetsrv/DOC/telnetaddcmd.md): example of adding a command to the telnet server
+- [Telnet Log](../common/utils/telnetsrv/DOC/telnetlog.md): telnet log command
+- [Telnet Measurement](../common/utils/telnetsrv/DOC/telnetmeasur.md): information on telnet `measur` command
+- [Telnet Usage](../common/utils/telnetsrv/DOC/telnetusage.md): Using the telnet server
+- [Telnet Loop](../common/utils/telnetsrv/DOC/telnetloop.md): information on telnet `loop` command
+- [Telnet Loader](../common/utils/telnetsrv/DOC/telnetloader.md): information on telnet `loader` command
+- [Telnet History](../common/utils/telnetsrv/DOC/telnethist.md): implementation of simple history system
+- [Telnet Get/Set](../common/utils/telnetsrv/DOC/telnetgetset.md): information on telnet `getall` command
+- [Telnet Architecture](../common/utils/telnetsrv/DOC/telnetarch.md): overview of telnet server architecture
+- [Telnet O1](../common/utils/telnetsrv/DOC/telneto1.md): telnet module to perform some O1-related actions
+
+#### Web Server
+
+- [Web Server](../common/utils/websrv/DOC/websrv.md): OAI comes with an integrated web server
+- [Web Server Architecture](../common/utils/websrv/DOC/websrvarch.md): web server interface implementation
+- [Web Server Usage](../common/utils/websrv/DOC/websrvuse.md): building the web server
+- [Web Server Development](../common/utils/websrv/DOC/websrvdev.md): enhancing the web server
+- [Web Server Frontend](../common/utils/websrv/frontend/README.md): information on web server frontend
 
 ## Testing
 
-- [UnitTests.md](./UnitTests.md) explains the unit testing setup
-- Component tests are under `tests/`. Currently, there is a simple CU-UP
-  tester, see the corresponding [README.md](../tests/nr-cuup/README.md).
-- [TESTBenches.md](./TESTBenches.md) lists the CI setup and links to pipelines
-- The CI setup uses a [custom framework](../ci-scripts/README.md) to run
-  end-to-end tests.
+- [Unit Tests](./UnitTests.md): explains the unit testing setup
+- [CU-UP Tester](../tests/nr-cuup/README.md): Component tests are under `tests/` (currently, a simple CU-UP tester)
+- [Test Benches](./TESTBenches.md): Lists the CI setup and links to pipelines
+- [CI Framework](../ci-scripts/README.md): The CI setup uses a custom framework to run end-to-end tests.
 
 ## Developer tools
 
-- [formatting](../tools/formatting/README.md) is a clang-format error detection tool
-- [iwyu](../tools/iwyu/README.md) is a tool to detect `#include` errors
-- [docker-dev-env](../tools/docker-dev-env/README.md) is a ubuntu24 docker development environment
-- [doc_best_practices.md](./doc_best_practices.md): overall best practices for writing documentations
+- [Formatting](../tools/formatting/README.md): a clang-format error detection tool
+- [IWYU](../tools/iwyu/README.md): a tool to detect `#include` errors
+- [Docker Dev Environment](../tools/docker-dev-env/README.md): Ubuntu 24 Docker development environment
+- [Plotting tools](../tools/plots/README.md): tools to visualize 5G NR simulation results
+- [Documentation Best Practices](./doc_best_practices.md): overall best practices for writing documentations
+- [Documentations using MkDocs](../tools/mkdocs/README.md): generate and serve documentation with MkDocs
+
+## CI
+
+- [Configuration Files](../ci-scripts/conf_files/README.md): naming style guide for config files
+- [OAI O-RAN 7.2 Front-haul VVDN RU](../ci-scripts/yaml_files/sa_fhi_7.2_vvdn_gnb/README.md): OAI O-RAN 7.2 Front-haul Docker Compose with VVDN RU
+- [OAI O-RAN 7.2 Front-haul Metanoia RU](../ci-scripts/yaml_files/sa_fhi_7.2_metanoia_2x2_gnb/README.md): OAI O-RAN 7.2 Front-haul Docker Compose with Metanoia RU
+- [OAI O-RAN 7.2 Front-haul Benetel RU](../ci-scripts/yaml_files/sa_fhi_7.2_benetel550_gnb/README.md): OAI O-RAN 7.2 Front-haul Docker Compose with Benetel RU
+- [CI test for 5G F1+E1 splits with RFsimulator](../ci-scripts/yaml_files/5g_rfsimulator_e1/README.md): CI test for 5G F1+E1 splits with RFsimulator
+- [CI tests](../ci-scripts/tests/README.md): CI code test cases and helper scripts
+- [Colosseum Testing](../ci-scripts/colosseum_scripts/README.md): automated testing of OpenAirInterface (OAI) gNB and softUE on the Colosseum
+
+## nFAPI
+
+- [Open-nFAPI](../nfapi/open-nFAPI/README.md): implementation of the Small Cell Forum's Network Functional API (nFAPI)
+- [Open-nFAPI License](../nfapi/open-nFAPI/LICENSE.md): licensing information for Open-nFAPI
+- [Open-nFAPI Examples](../nfapi/open-nFAPI/utils/examples.md): Open-nFAPI usage examples
+- [Open-nFAPI Changelog](../nfapi/open-nFAPI/CHANGELOG.md): release notes for Open-nFAPI
+- [nFAPI Changes](../nfapi/CHANGES.md): information on nFAPI changes
+
+## Common Utilities
+
+
+- [OCP ITTI](../common/utils/ocp_itti/itti.md): interthread interface (ITTI)
+- [T Tracer Wireshark](../common/utils/T/DOC/T/wireshark.md): MAC PDUs and wireshark
+- [T Tracer CSV](../common/utils/T/DOC/T/csv.md): tracer to dump information of a single trace to a CSV.
+- [T Tracer Record](../common/utils/T/DOC/T/record.md): how to use the `record` tracer
+- [T Tracer ENB](../common/utils/T/DOC/T/enb.md): information on T Tracer eNB
+- [T Tracer Replay](../common/utils/T/DOC/T/replay.md): how to use the `replay` tracer
+- [T Tracer Basic](../common/utils/T/DOC/T/basic.md): Basic usage of the T tracer
+- [T Tracer How To New Trace](../common/utils/T/DOC/T/howto_new_trace.md): simple tutorial on T tracer
+- [T Tracer Multi](../common/utils/T/DOC/T/multi.md): Multiple tracers
+- [T Tracer To VCD](../common/utils/T/DOC/T/to_vcd.md): tracer to dump a VCD trace of the softmodem.
+- [Actor README](../common/utils/actor/README.md): simple actor model implementation
+
+## L2 Emulator (deprecated)
+
+- [LTE Mode L2 Emulator](./episys/lte_mode_l2_emulator/README.md): Multi-UE Proxy for UEs to communicate with eNB (LTE mode)
+- [NSA Mode L2 Emulator](./episys/nsa_mode_l2_emulator/README.md): Multi-UE Proxy for UEs to communicate with gNB (NSA mode)

doc/assets/stylesheets/extra.css

@@ -0,0 +1,22 @@
+:root {
+    --md-primary-fg-color:        #224C98;
+    --md-primary-fg-color--light: #4C74C0;
+    --md-primary-fg-color--dark:  #183A76;
+    --md-accent-fg-color:         #224C98;
+  }
+
+
+.md-content {
+  padding-left: 1rem;
+  padding-right: 1rem;
+}
+
+.md-grid {
+    max-width: none;
+}
+
+/* Style the footer copyright text */
+.md-footer-copyright p {
+  font-size: 0.6rem; /* Increase the font size */
+  padding: 1rem; /* Add some top and bottom padding */
+}

doc/overrides/main.html

@@ -0,0 +1,23 @@
+{% extends "base.html" %}
+
+{% block content %}
+  {# Rewrite all .md links to directory URLs #}
+  {{ super()
+       | replace(".md", "/")
+       | replace("README/", "")
+  }}
+{% endblock %}
+
+
+{% block footer %}
+  <footer class="md-footer">
+    <div class="md-footer-meta" style="display: flex; justify-content: space-between; align-items: center; padding: 0 40px;">
+      <div class="md-footer-left">
+        <p><em>© Copyright 2026 <a href="https://openairinterface.org/" target="_blank" rel="noopener">OpenAirInterface.org</a></em></p>
+      </div>
+      <div class="md-footer-right">
+        <p><em>For any bug or problems please raise an issue on <a href="https://gitlab.eurecom.fr/groups/oai/-/issues" target="_blank" rel="noopener">GitLab ↗.</a></em></p>
+      </div>
+    </div>
+  </footer>
+{% endblock %}

mkdocs.yml

@@ -0,0 +1,85 @@
+################################################################################
+# Licensed to the OpenAirInterface (OAI) Software Alliance under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The OpenAirInterface Software Alliance licenses this file to You under
+# the OAI Public License, Version 1.1  (the "License"); you may not use this file
+# except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.openairinterface.org/?page_id=698
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#-------------------------------------------------------------------------------
+# For more information about the OpenAirInterface (OAI) Software Alliance:
+#      contact@openairinterface.org
+################################################################################
+
+site_name: OpenAirInterface
+site_url: ""
+site_author: OpenAirInterface Software Alliance
+docs_dir: doc
+theme:
+  name: material
+  custom_dir: doc/overrides
+  logo: assets/images/OPEN_AIR_INTERFACE_LOGO.png
+  favicon: assets/images/oai-logo-favicon.png
+  features:
+    - navigation.top
+    - content.collapse
+    - content.code.copy
+  palette:
+    primary: custom
+    accent: custom
+  font:
+    text: Roboto
+    code: Roboto Mono
+extra:
+  version:
+    provider: mike
+
+extra_css:
+  - assets/stylesheets/extra.css
+
+# Repository
+repo_name: OAI Documentation GitLab
+repo_url: https://gitlab.eurecom.fr/oai/openairinterface5g
+
+## Navigation Entries Block Starts
+
+
+## Navigation Entries Block Ends
+
+
+markdown_extensions:
+  - toc:
+      permalink: true
+  - tables
+  - attr_list
+  - admonition
+  - codehilite
+  - footnotes
+  - smarty
+  - pymdownx.details
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:mermaid2.fence_mermaid_custom
+
+validation:
+  links:
+    not_found: ignore
+
+plugins:
+  - search
+  - mermaid2
+  - simple:
+      include: [".txt", ".mmd", "README", ".conf", ".c", ".yaml", ".yml", ".cpp", ".md", ".png", ".h", ".json", ".patch", ".py", ".sh"]
+      merge_docs_dir: true
+      ignore:
+        - README.md

tools/mkdocs/Dockerfile

@@ -0,0 +1,42 @@
+#/*
+# * Licensed to the OpenAirInterface (OAI) Software Alliance under one or more
+# * contributor license agreements.  See the NOTICE file distributed with
+# * this work for additional information regarding copyright ownership.
+# * The OpenAirInterface Software Alliance licenses this file to You under
+# * the OAI Public License, Version 1.1  (the "License"); you may not use this file
+# * except in compliance with the License.
+# * You may obtain a copy of the License at
+# *
+# *      http://www.openairinterface.org/?page_id=698
+# *
+# * Unless required by applicable law or agreed to in writing, software
+# * distributed under the License is distributed on an "AS IS" BASIS,
+# * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# * See the License for the specific language governing permissions and
+# * limitations under the License.
+# *-------------------------------------------------------------------------------
+# * For more information about the OpenAirInterface (OAI) Software Alliance:
+# *      contact@openairinterface.org
+# */
+#---------------------------------------------------------------------
+
+FROM python:3.10-alpine
+
+# Copy the entire repo into the container
+
+WORKDIR /openairinterface5g
+COPY . . 
+
+
+# Install dependencies, process Markdown, and build MkDocs
+RUN pip install --no-cache-dir -r tools/mkdocs/requirements.txt && \
+    python3 tools/mkdocs/main.py && \
+    mkdocs build --clean
+
+# Expose MkDocs port
+EXPOSE 8000
+
+# Serve MkDocs
+ENTRYPOINT ["mkdocs"]
+CMD ["serve", "-a", "0.0.0.0:8000"]
+

tools/mkdocs/README.md

@@ -0,0 +1,183 @@
+# OAI Documentation using MkDocs
+
+<h1 align="center">
+    <a href="https://openairinterface.org/">
+        <img src="https://openairinterface.org/wp-content/uploads/2015/06/cropped-oai_final_logo.png" alt="OAI" width="550">
+    </a>
+</h1>
+
+<p align="center">
+    <a href="https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-fed/-/blob/master/LICENSE">
+        <img src="https://img.shields.io/badge/license-OAI--Public--V1.1-blue" alt="License">
+    </a>
+    <a href="https://www.mkdocs.org/">
+        <img src="https://img.shields.io/badge/Documentation_Using-MkDocs-20c997?style=flat&logo=mkdocs&logoColor=white" alt="MkDocs">
+    </a>
+    <a href="https://squidfunk.github.io/mkdocs-material/getting-started/">
+        <img src="https://img.shields.io/badge/Theme-Material_for_MkDocs-ffc107" alt="Material for MkDocs">
+    </a>
+    <a href="https://www.python.org/">
+        <img src="https://img.shields.io/badge/Python-fd7e14?style=flat&logo=python&logoColor=white" alt="Python">
+    </a>
+    <a href="https://althack.dev/mkdocs-simple-plugin/v3.2.4/">
+        <img src="https://img.shields.io/badge/mkdocs--simple--plugin-6f42c1" alt="mkdocs-simple-plugin v3.2.4">
+    </a>
+</p>
+
+
+---
+
+## Overview
+
+This is a guide to build and serve the `openairinterface5g` documentation using [MkDocs](https://www.mkdocs.org/)
+with the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme.
+
+---
+
+## Prerequisites
+
+### Python
+
+Make sure `Python 3.10` or higher is installed:
+
+```bash
+python3 --version
+```
+
+### Python Dependencies
+
+Install the Python packages required to build the documentation:
+
+```bash
+pip install -r tools/mkdocs/requirements.txt
+```
+
+### Docker
+
+If you want to build and serve the documentation using Docker, install docker following the [official instructions](https://docs.docker.com/engine/install/).
+
+---
+
+
+## MkDocs Files
+
+Here’s a brief overview of the files related to MkDocs:
+
+| Folder / File                               | Description                                             |
+| --------------------------------------------------- | ------------------------------------------------------- |
+| `mkdocs.yml`                    | Main MkDocs configuration file                           |
+| `tools/mkdocs/requirements.txt`         | Python dependencies required to build the documentation |
+| `doc/`                                  | Main folder containing markdown documentation files    |
+| `doc/overrides/`             | Custom theme templates or overrides for Material theme |
+| `doc/assets/images/`         | Logo and favicon images                                 |
+| `doc/assets/stylesheets/extra.css` | Extra custom CSS for styling                            |
+| `tools/mkdocs/main.py` | Script to generate the navigation in `mkdocs.yml` and pre-process the markdown files |
+| `tools/mkdocs/Dockerfile` | Build and run MkDocs using Docker |
+
+---
+
+
+## Building the Documentation
+
+### Native MkDocs
+
+#### Generate the navigation and preprocess Markdown
+
+
+```bash
+python3 tools/mkdocs/main.py
+```
+
+#### Build the static site
+
+To generate the static site:
+
+```bash
+mkdocs build 2>&1 | tee mkdocs_build.log
+```
+
+The output will be in the `site/` directory.
+
+
+#### Serve locally to preview
+
+To preview the documentation locally, run the below command and open your browser at [http://127.0.0.1:8000](http://127.0.0.1:8000).
+
+```bash
+mkdocs serve
+```
+
+---
+
+### Using Docker
+
+#### Build the Docker image
+
+```bash
+docker build --no-cache -f tools/mkdocs/Dockerfile -t oai-mkdocs:latest .
+```
+
+- This installs dependencies from `tools/mkdocs/requirements.txt`.
+- Runs `main.py` to generate the MkDocs navigation and preprocess Markdown so it renders correctly.
+- Builds the MkDocs static site.
+
+#### Serve the documentation using Docker
+
+```bash
+docker run -d   --name oai-mkdocs   -p 8000:8000   oai-mkdocs:latest
+```
+
+To preview the documentation, open your browser at [http://127.0.0.1:8000](http://127.0.0.1:8000).
+
+#### View Docker logs
+
+```bash
+docker logs oai-mkdocs > mkdocs-docker.log 2>&1
+```
+
+To stop and remove the container, you can run below commands:
+
+```bash
+docker stop oai-mkdocs
+docker rm oai-mkdocs
+```
+---
+
+## Versioned Documentation with Mike
+
+[Mike](https://github.com/jimporter/mike/blob/master/README.md) allows to maintain multiple versions of the documentation.
+
+**1. Deploy a New Version**
+
+```bash
+# Deploy documentation as version 1.0 and assign it the alias 'latest'
+mike deploy 1.0 latest
+```
+
+This command generates a versioned snapshot of your documentation for `1.0` and links the alias latest to it for easy access.
+
+**2. Set the default version**
+
+```bash
+mike set-default latest
+```
+
+This version will be served as the default when users visit the documentation.
+
+**3. List All Deployed Versions**
+
+```bash
+mike list
+```
+
+Displays all deployed versions along with their aliases.
+
+**4. Preview versioned documentation**
+
+```bash
+mike serve
+```
+
+You can view the site on [http://localhost:8000/](http://localhost:8000/).
+
+---

tools/mkdocs/main.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+
+# * Licensed to the OpenAirInterface (OAI) Software Alliance under one or more
+# * contributor license agreements.  See the NOTICE file distributed with
+# * this work for additional information regarding copyright ownership.
+# * The OpenAirInterface Software Alliance licenses this file to You under
+# * the OAI Public License, Version 1.1  (the "License"); you may not use this file
+# * except in compliance with the License.
+# *
+# *      http://www.openairinterface.org/?page_id=698
+# *
+# * Unless required by applicable law or agreed to in writing, software
+# * distributed under the License is distributed on an "AS IS" BASIS,
+# * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# * See the License for the specific language governing permissions and
+# * limitations under the License.
+# */
+#---------------------------------------------------------------------
+# Python for MkDocs
+#
+#   Required Python Version
+#     Python 3.x
+# *-------------------------------------------------------------------------------
+
+from pathlib import Path
+import logging
+import argparse
+from preprocess_md import (
+    process_file,
+    rewrite_doc_links,
+    rewrite_readme_links,
+    remove_toc_markers
+)
+from mkdocs_nav_generator import (
+    configure_logging,
+    get_repo_root,
+    MarkdownParser,
+    MkDocsNavBuilder,
+    MkDocsInjector
+)
+
+logger = logging.getLogger(__name__)
+
+def generate_and_inject_nav(debug: bool = False) -> None:
+    """Generate MkDocs navigation from README.md and inject into mkdocs.yml."""
+    configure_logging(debug)
+    logger.info("Starting navigation generation + injection")
+
+    repo_root = get_repo_root()
+    input_md = repo_root / "doc" / "README.md"
+    mkdocs_yaml = repo_root / "mkdocs.yml"
+
+    parsed_tree = MarkdownParser(input_md).parse()
+    nav_yaml = MkDocsNavBuilder(parsed_tree).build()
+
+    injector = MkDocsInjector(mkdocs_yaml)
+    injector.inject(nav_yaml)
+
+    logger.info("MkDocs navigation generation completed.")
+
+def rewrite_markdown_links() -> None:
+    """Rewrite Markdown links and remove TOC markers in all .md files."""
+    logger.info("Starting Markdown link rewrite.")
+
+    root = Path(".")
+    for md_file in root.rglob("*.md"):
+        process_file(md_file, rewrite_doc_links)
+        process_file(md_file, remove_toc_markers)
+
+    # Special handling for doc/README.md
+    readme_file = root / "doc" / "README.md"
+    process_file(readme_file, rewrite_readme_links)
+
+    logger.info("Markdown link rewrite completed.")
+
+def main() -> None:
+    # -----------------------------
+    # CLI argument parsing
+    # -----------------------------
+    parser = argparse.ArgumentParser(description="Process Markdown and generate MkDocs navigation.")
+    parser.add_argument("--debug", action="store_true", help="Enable debug logging")
+    args = parser.parse_args()
+
+    # Setup basic logging
+    logging.basicConfig(level=logging.DEBUG if args.debug else logging.INFO,
+                        format="%(levelname)s | %(message)s")
+
+    # -----------------------------
+    # Step 1: Generate navigation
+    # -----------------------------
+    generate_and_inject_nav(debug=args.debug)
+
+    # -----------------------------
+    # Step 2: Rewrite Markdown links
+    # -----------------------------
+    rewrite_markdown_links()
+
+if __name__ == "__main__":
+    main()

tools/mkdocs/mkdocs_nav_generator.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+
+# * Licensed to the OpenAirInterface (OAI) Software Alliance under one or more
+# * contributor license agreements.  See the NOTICE file distributed with
+# * this work for additional information regarding copyright ownership.
+# * The OpenAirInterface Software Alliance licenses this file to You under
+# * the OAI Public License, Version 1.1  (the "License"); you may not use this file
+# * except in compliance with the License.
+# * You may obtain a copy of the License at
+# *
+# *      http://www.openairinterface.org/?page_id=698
+# *
+# * Unless required by applicable law or agreed to in writing, software
+# * distributed under the License is distributed on an "AS IS" BASIS,
+# * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# * See the License for the specific language governing permissions and
+# * limitations under the License.
+# *-------------------------------------------------------------------------------
+# * For more information about the OpenAirInterface (OAI) Software Alliance:
+# *      contact@openairinterface.org
+# */
+#---------------------------------------------------------------------
+# Python for MkDocs
+#
+#   Required Python Version
+#     Python 3.x
+#---------------------------------------------------------------------
+
+import re
+import yaml
+import logging
+import argparse
+from pathlib import Path
+from typing import (
+    List,
+    Dict,
+    Any,
+)
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+
+def configure_logging(debug: bool = False):
+    level = logging.DEBUG if debug else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+
+logger = logging.getLogger("mkdocs-nav-generator")
+
+# -----------------------------------------------------------------------------
+# Repository Root Detection
+# -----------------------------------------------------------------------------
+
+def get_repo_root() -> Path:
+    """
+    Detect repository root dynamically.
+    """
+    return Path(__file__).resolve().parents[2]
+
+# -----------------------------------------------------------------------------
+# Utilities
+# -----------------------------------------------------------------------------
+
+def clean_path(path: str) -> str:
+    """
+    Normalize Markdown link paths for MkDocs usage.
+    mkdocs-simple-plugin resolves paths relative to docs_dir.
+    """
+    return path.replace("../", "").replace("./", "")
+
+# -----------------------------------------------------------------------------
+# Markdown Parser
+# -----------------------------------------------------------------------------
+
+class MarkdownParser:
+    HEADING_RE = re.compile(r"^(#{2,6})\s+(.*)")
+    LINK_RE = re.compile(r"^- \[(.+?)\]\((.+?)\)")
+
+    def __init__(self, filepath: Path):
+        self.filepath = filepath
+
+    def parse(self) -> List[Dict[str, Any]]:
+        logger.info(f"Parsing markdown file: {self.filepath}")
+
+        if not self.filepath.exists():
+            raise FileNotFoundError(f"Markdown file not found: {self.filepath}")
+
+        # Root of navigation tree
+        root: List[Dict[str, Any]] = []
+        # Key = heading level, Value = list of children
+        current_nodes: Dict[int, List] = {1: root}
+
+        with self.filepath.open("r", encoding="utf-8") as f:
+            for raw_line in f:
+                line = raw_line.strip()
+
+                heading_match = self.HEADING_RE.match(line)
+                if heading_match:
+                    hashes, title = heading_match.groups()
+                    level = len(hashes)
+
+                    node = {title: []}
+
+                    parent_level = level - 1
+                    while parent_level > 1 and parent_level not in current_nodes:
+                        parent_level -= 1
+
+                    if parent_level in current_nodes:
+                        current_nodes[parent_level].append(node)
+                    else:
+                        root.append(node)
+
+                    current_nodes[level] = node[title]
+
+                    for deeper in list(current_nodes.keys()):
+                        if deeper > level:
+                            del current_nodes[deeper]
+
+                    continue
+
+                # Detect markdown bullet links
+                link_match = self.LINK_RE.match(line)
+                if link_match:
+                    title, path = link_match.groups()
+                    entry = {title: clean_path(path)}
+
+                    deepest_level = max(current_nodes.keys())
+                    current_nodes[deepest_level].append(entry)
+
+        logger.info("Markdown parsing complete.")
+        return root
+
+# -----------------------------------------------------------------------------
+# Nav Builder
+# -----------------------------------------------------------------------------
+
+class MkDocsNavBuilder:
+    """
+    Wraps parsed markdown tree into MkDocs-compatible structure
+    """
+    def __init__(self, markdown_tree: List[Dict[str, Any]]):
+        self.markdown_tree = markdown_tree
+
+    def build(self) -> str:
+        logger.info("Building mkdocs nav YAML block.")
+
+        nav_structure = {
+            "nav": [
+                {"Home": "README.md"},
+                {"RAN": self.markdown_tree},
+            ]
+        }
+
+        yaml_block = yaml.dump(
+            nav_structure,
+            sort_keys=False,
+            allow_unicode=True,
+            width=1000,
+        )
+
+        return yaml_block
+
+# -----------------------------------------------------------------------------
+# YAML Injection Logic
+# -----------------------------------------------------------------------------
+
+class MkDocsInjector:
+    """
+    Injects generated navigation into existing mkdocs.yml.
+    Only modifies content between defined navigation markers.
+    """
+
+    NAV_START = "## Navigation Entries Block Starts"
+    NAV_END = "## Navigation Entries Block Ends"
+
+    def __init__(self, mkdocs_path: Path):
+        self.mkdocs_path = mkdocs_path
+
+    def inject(self, nav_yaml: str):
+        """
+        Replace everything between NAV_START and NAV_END
+        with the newly generated nav_yaml block.
+        """
+        logger.info(f"Injecting nav into: {self.mkdocs_path}")
+
+        content = self.mkdocs_path.read_text(encoding="utf-8")
+
+        if self.NAV_START not in content or self.NAV_END not in content:
+            raise RuntimeError(
+                f"Markers '{self.NAV_START}' or '{self.NAV_END}' not found in mkdocs.yml"
+            )
+
+        # Regex to match everything between the two markers (including newlines)
+        pattern = re.compile(
+            rf"({re.escape(self.NAV_START)})(.*)({re.escape(self.NAV_END)})",
+            re.DOTALL,
+        )
+
+        def replacer(match):
+            return (
+                f"{match.group(1)}\n\n"
+                f"{nav_yaml.strip()}\n\n"
+                f"{match.group(3)}"
+            )
+
+        updated_content = re.sub(pattern, replacer, content)
+
+        self.mkdocs_path.write_text(updated_content, encoding="utf-8")
+
+        logger.info("Navigation successfully injected.")

tools/mkdocs/preprocess_md.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+
+#/*
+# * Licensed to the OpenAirInterface (OAI) Software Alliance under one or more
+# * contributor license agreements.  See the NOTICE file distributed with
+# * this work for additional information regarding copyright ownership.
+# * The OpenAirInterface Software Alliance licenses this file to You under
+# * the OAI Public License, Version 1.1  (the "License"); you may not use this file
+# * except in compliance with the License.
+# * You may obtain a copy of the License at
+# *
+# *      http://www.openairinterface.org/?page_id=698
+# *
+# * Unless required by applicable law or agreed to in writing, software
+# * distributed under the License is distributed on an "AS IS" BASIS,
+# * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# * See the License for the specific language governing permissions and
+# * limitations under the License.
+# *-------------------------------------------------------------------------------
+# * For more information about the OpenAirInterface (OAI) Software Alliance:
+# *      contact@openairinterface.org
+# */
+#---------------------------------------------------------------------
+# Python for MkDocs
+#
+#   Required Python Version
+#     Python 3.x
+# *-------------------------------------------------------------------------------
+
+# Preprocess Markdown files for MkDocs HTML build:
+# 1. Rewrite links in all Markdown files to correct relative URLs.
+# 2. Remove [[_TOC_]] markers from all Markdown files.
+# 3. In doc/README.md, remove '../' from links so they work at the folder root.
+
+
+import pathlib
+import logging
+
+# -----------------------------
+# Logging Setup
+# -----------------------------
+logging.basicConfig(level=logging.INFO, format="%(levelname)s | %(message)s")
+logger = logging.getLogger(__name__)
+
+# -----------------------------
+# Link Rewrite Functions
+# -----------------------------
+def rewrite_doc_links(content: str) -> str:
+    """Rewrite doc links in general markdown files."""
+    content = content.replace("](doc/", "](")
+    content = content.replace("../doc/", "../")
+    return content
+
+def rewrite_readme_links(content: str) -> str:
+    """Rewrite '../' links in README.md only."""
+    return content.replace("../", "")
+
+def remove_toc_markers(content: str) -> str:
+    """Remove the [[_TOC_]] Markers from the markdown files."""
+    return content.replace("[[_TOC_]]", "")
+
+# -----------------------------
+# File Processing
+# -----------------------------
+def process_file(path: pathlib.Path, rewrite_func) -> None:
+    """Read, rewrite, and save file if modified."""
+    if not path.exists():
+        logger.warning(f"File not found: {path}")
+        return
+
+    original = path.read_text(encoding="utf-8")
+    updated = rewrite_func(original)
+
+    if updated != original:
+        path.write_text(updated, encoding="utf-8")
+        logger.info(f"Updated: {path}")

tools/mkdocs/requirements.txt

@@ -0,0 +1,7 @@
+mkdocs==1.6.1
+mkdocs-material==9.6.18
+mike==2.1.3
+mkdocs-mermaid2-plugin==1.2.2
+pymdown-extensions==10.16.1
+requests==2.32.3
+mkdocs-simple-plugin==3.2.4