Context

The current Google result for srsRAN_docs looks like:

From Use meta tags:

Using a meta description allows you to customize how your pages look in search engine result pages.

Typically search engines will use the first few sentences of a page if no meta description is provided. In Sphinx, you can customize your meta description using the following RestructuredText:

.. meta::
    :description lang=en:
        Adding additional CSS or JavaScript files to your Sphinx documentation
        can let you customize the look and feel of your docs or add additional functionality.

Proposal

Add a custom meta description for the docs landing page in index.rst. For example:

Documenation for the srsRAN project. Browse the latest developer documentation to build complete end-to-end mobile wireless networks.

Context

Sphinx docs depend on other tools and dependencies to build.

The repository defines the dependencies in the requirements.txt file, but it does not specify which version of the packages should be installed. Therefore, when a third party dependency receives an update, there is the risk to break the local or production build if the latest update is not compatible.

Proposal

1. For each dependency, find the exact version number used in production.
2. List all the dependencies in the requirements.txt file. The file must list the exact version number for each dependency to make sure updates from third-party packages do not break the docs. For example:

# File: docs/requirements.txt

# Defining the exact version will make sure things don't break

sphinx==4.1.2
sphinx_rtd_theme==0.5.2
sphinxcontrib-seqdiag==2.0.0
sphinxcontrib-blockdiag==2.0.0

3. Install the dependencies in a clean environment, and check the build does not break.
4. Test the changes on ReadTheDocs.

Context

index.rst harcodes the documentation version:

srsRAN 21.04 Documentation
==========================

Proposal

Instead, use the directive |version| to update the documentation version number only on in one place (conf.py > version setting) when this changes. For example:

srsRAN |version| Documentation
==============================

Context

The repository contains several Sphinx subprojects.

Each subproject defines a Makefile. If someone changes one Makefile, this could not be ported to the other Makefiles, leading to having projects with a different set of commands.

Instead, adapt the main Makefile to support building subprojects.

Proposal

1. Adapt the main Makefile to support “sourcePath” as an argument. If the parameter is not provided, the command should build the docs for the main project by default.
2. Delete all Makefile from subprojects.

In the manual are described the following metrics as coming from the "trace" of srsenb
------DL------------------------------UL----------------------------------
rnti cqi ri mcs brate bler snr phr mcs brate bler bsr

However, in the last version, I seem to see the following one
------DL-------------------------------UL--------------------------------------------
rnti cqi ri mcs brate ok nok (%) pusch pucch phr mcs brate ok nok (%) bsr

The repository contains several Sphinx subprojects. However, all of them are published as a single site.

ReadTheDocs provides a feature to work with multiple projects more effectively:

Projects can be configured in a nested manner by configuring a project as a subproject of another project. This allows for documentation projects to share a search index and a namespace or custom domain, but still be maintained independently.

For example, a parent project, Foo is set up with a subproject, Bar. The documentation for Foo will be available at:
https://foo.readthedocs.io/en/latest/
The documentation for Bar will be available under this same path:
https://foo.readthedocs.io/projects/bar/en/latest/

RTD Subprojects feature would let you:

• Build separate PDF builds per project (e.g., one for each user manual).
• Version each subproject differently.
• Have faster builds since the whole project does not have to be rebuilt every time, only the subproject that received an update.

Limitations

⚠️If you decide to support RTD Subprojects, building a single PDF / HTML site locally that includes all the subprojects documentation will not be possible. Instead, you will have to build each site independently.

Proposal

For every subproject:

1. Create a new project on ReadTheDocs.
2. Enable PDF builds (optional).
3. Look for cross-references to other projects, and fix them.

In the main project:

1. Remove the subprojects from the toctree.
2. Add links to the subproject documentation.
3. Create 404 redirections for every page moved from the main project.

In the theme:

• Customize the theme to link to the parent documentation from subprojects. This feature not provided by the theme you are using yet (readthedocs/sphinx_rtd_theme#1000)

ℹ️ This proposal affects substantially the current navigation structure . Therefore, before implementing this solution in production I would share with you a Proof of Concept on a staging site moving one subproject to show you how the resulting documentation site would look like.

I would like to have some question :

1. How to fix MCU error with limesdr ?
2. what kind of phone did you use for connecting to the lte network using limeSDR?
3. Is it possible to have more explication why limeSDR shouldn't use one same machine the core and enodeB? or is it possible to have the ressource needed for the limeSDR with enodeB on rpi4?
4. Did you use power bank or just adapter 220v to 5v for the rpi?

Chears,

Context

The table of contents on the PDF version does not render correctly. It shows the following headings:

Where it should render:

To render the left sidenav toctree instead, the index page should only have a single H1 title, some content, and the table of contents (without any other subheading).

Proposal

There are two alternatives:

A) Reorganize the index page (recommended)

Edit the index.rst file:

1. Move the context from Index -> First Steps under a new page General > First Steps.
2. Remove the heading Links.
3. In the toctree directive, set the option max_depth to 2. For example:

.. toctree::
   :maxdepth: 2

B) Create a custom index page for PDF builds

1. Create a second index page for PDF builds (e.g. index_pdf.rst, without any subheading). This index page should only have one H1 title, some content, and the table of contents (without any other subheading).

2. In conf.py, change latex_documents option from:

latex_documents = [
    (master_doc_pdf, 'srsRAN.tex', u'srsRAN Documentation',
     [author], 'manual'),
]

to:

latex_documents = [
    ('index_pdf', 'srsRAN.tex', u'srsRAN Documentation',
     [author], 'manual'),
]

Context

You are using ReadTheDocs web interface to configure the Sphinx project. However, you could lose the configuration if you change it over time.

Instead, it's recommended to store a configuration file for RTD within the repository.

Proposal

1. Create a configuration file to deploy to RTD. For example:

# File: .readthedocs.yaml

version: 2

# Build from the docs/ directory with Sphinx
sphinx:
  configuration: srsran_user_manuals/source/conf.py

# Explicitly set the version of Python and its requirements
python:
  version: 3.7
  install:
    - requirements: requirements.txt

2. Remove the current configuration from the RTD panel and make sure the docs build without errors.

Context

The README explains how to install the Sphinx dependencies, but it does not specify which version.

Proposal

Edit the README to guide the contributor on how to install the dependencies form the requirements.txt file. For example:

On Ubuntu, they can be installed with:

sudo apt install python-pip
pip install -r requirements.txt

Context

The repository contains several Sphinx subprojects.

Each subproject defines its own conf.py, but most settings are shared with the parent project. Instead, subprojects could inherit from the main project conf.py, and only overwrite the unique settings for the subproject.

By doing so, if you were to install new extensions or change a setting, you can make sure that the modification will be applied to all subprojects instead of having to update each conf.py file individually.

Proposal

For every subproject:

1. In conf.py, extend from the main conf.py:

import os
import sys
sys.path.insert(0, os.path.abspath('../../../..'))
 
from srsran_user_manuals.source.conf import *

2. Keep only the settings that are unique for the project, for example:

project = u'srsRAN Application Notes'

Context

Merging pull request into master could break ReadTheDocs build.

There are two solutions to prevent this from happening:

Option A: Build and publish a preview site for pull-requests (recommended)

RTD offers a feature to ensure the documentation build does not break before you merge a pull-request into the master branch. They also generate a preview site for each pull request.

⚠️This feature is available with ReadTheDocs for Business Basic Plan.

To enable this feature:

1. Go to your project dashboard

2. Go to Admin > Advanced settings

3. Enable the Build pull requests for this project option

4. Click on Save.

Option B: Build the docs in a GitHub Actions workflow

Create a Github Actions workflow that builds the docs when:

• There is a new pull request targeting the master branch.
• The pull request receives a new commit.

If the build fails or a warning is raised, the pull requests checks warn the user they should have to edit the pull request before merging it:

Context

The file conf.py defines the copyright notice:

copyright = u'2019-2021, Software Radio Systems'

Once a year, you have to submit a new PR to change the year.

Proposal

Instead, update the copyright year automatically with the following code snippet:

from datetime import date
year = str(date.today().year)
copyright = '2019-' + year + ', Software Radio Systems.'

Context

The pages before and after the table of contents are left in blank.

Proposal

To remove the blank pages (optional), add the following options to the latex_elements setting in conf.py:

'classoptions': ',openany',

Context

Every time a contributor changes the documentation in their local environment, they must run sphinx-build -b html . _build and open the _build directory to preview the changes.

The documentation toolchain can provide a command that starts a server at http://127.0.0.1:8000 and watches for changes in the docs local repository. When a change is detected, the documentation is rebuilt, and any open browser windows are reloaded automatically with the latest documentation contents.

Proposal

Install the extension sphinx-autobuild.

In running through the initial install steps and compiling from source (srsRAN):
- when running the "make test" step, the process would get to a maximum 787 tests and then the server dropped all TCP/IP and the "make test".
- Running "top" showed "make test" chewing up CPU and then process drop followed by network
connections dropped.

My fix was simple, please see below - If anyone else sees this issue, lower the process priority on the CPU

test@test-NUC8i7BEH:~/srsRAN/srsRAN/build$ sudo nice -n 15 make test
Running tests...
Test project /home/test/srsRAN/srsRAN/build
Start 1: thread_pool_test
1/1426 Test #1: thread_pool_test ................................................ Passed 4.14 sec
Start 2: thread_test
2/1426 Test #2: thread_test ..................................................... Passed 0.00 sec
Start 3: band_helper_test
3/1426 Test #3: band_helper_test ................................................ Passed 0.01 sec
Start 4: pdu_test
4/1426 Test #4: pdu_test ........................................................ Passed 0.02 sec
Start 5: mac_pcap_test
5/1426 Test #5: mac_pcap_test ................................................... Passed 0.06 sec
Start 6: mac_pdu_nr_test
6/1426 Test #6: mac_pdu_nr_test ................................................. Passed 0.01 sec
Start 7: chest_test_dl_cellid0
7/1426 Test #7: chest_test_dl_cellid0 ........................................... Passed 0.02 sec
Start 8: chest_test_dl_cellid1
8/1426 Test #8: chest_test_dl_cellid1 ........................................... Passed 0.01 sec
Start 9: chest_test_dl_cellid2
9/1426 Test #9: chest_test_dl_cellid2 ........................................... Passed 0.01 sec
Start 10: chest_test_dl_cellid0_50prb
10/1426 Test #10: chest_test_dl_cellid0_50prb ..................................... Passed 0.02 sec
Start 11: chest_test_dl_cellid1_50prb
11/1426 Test #11: chest_test_dl_cellid1_50prb ..................................... Passed 0.02 sec
Start 12: chest_test_dl_cellid2_50prb
........
.....................................
1423/1426 Test #1423: fsm_test ........................................................ Passed 0.01 sec
Start 1424: optional_test
1424/1426 Test #1424: optional_test ................................................... Passed 0.00 sec
Start 1425: cached_alloc_test
1425/1426 Test #1425: cached_alloc_test ............................................... Passed 0.04 sec
Start 1426: optional_array_test
1426/1426 Test #1426: optional_array_test ............................................. Passed 0.01 sec

100% tests passed, 0 tests failed out of 1426

Label Time Summary:
chest = 21.23 secproc (22 tests)
fec = 0.48 secproc (11 tests)
ldpc = 0.01 secproc (1 test)
lib = 208.14 secproc (1007 tests)
lte = 176.26 secproc (931 tests)
nr = 131.48 secproc (294 tests)
pdcp = 0.56 secproc (3 tests)
phch = 41.51 secproc (485 tests)
phy = 176.03 secproc (991 tests)
polar = 0.00 secproc (1 test)
rlc = 31.55 secproc (13 tests)
turbo = 0.46 secproc (9 tests)

Total Test time (real) = 334.42 sec
test@test-NUC8i7BEH:~/srsRAN/srsRAN/build$

Context

The command make html raises the following warning(s):

WARNING: html_static_path '.static' does not exist

Proposal

Comment out the property html_static_path in conf.py, since the project does not have a .static folder.

The documentation have the following step to install the configuration sudo srslte_install_configs.sh user, however I believe this has changed to sudo srsran_install_configs.sh user. srsRAN works flawlessly (tried VoLTE calls)..Amazing work

Thanks a lot

Hello

I thought this question is relevant here, where are the accepted values for sib.conf specially for the field "intra_freq_reselection", to disallow reselection

thanks