Skip to end of metadata
Go to start of metadata

This page provides instructions for configuring your component's documentation area so the O-RAN-SC Jenkins will automatically build and deploy the material to upon change of any file within your docs/ directory.

If you have questions about this process or need help, please contact the O-RAN-SC Documentation Project Technical Lead, weichen ni (

Note: please add weichen ni as a reviewer on all Gerrit doc changesets if you have any questions.

Configuration needed for your _repo/

Please use the automated setup process that is documented here:

If that process fails or you need to trouble-shoot problems, this page gives step by step details.

Manual Step 1: Add files to your-repo root

Step 1.1: Create or extend file .gitignore in the root of your repository with the following content:

# documentation

Step 1.2: Create RTD config file

Create a file in the root of your repository called .readthedocs.yaml (yes there's a leading dot) with the following content:

version: 2

  - htmlzip

  os: "ubuntu-22.04"
      python: "3.7"

    - requirements: docs/requirements-docs.txt

  configuration: docs/

Step 1.3: Create file tox.ini

Create or extend a file in the root of your repostory called tox.ini with the following content.

Please note that Python projects must not use all entries shown here. The entry "skipsdist = true" is only appropriate if the project has no file that defines how to build distributions.

# documentation only
minversion = 2.0
envlist =
skipsdist = true

basepython = python3
deps = 
commands =
    sphinx-build -W -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
    echo "Generated docs available in {toxinidir}/docs/_build/html"
whitelist_externals = echo

basepython = python3
deps = sphinx
commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck

Manual Step 2: Add files to your-repo/docs

In these steps you will create files in the "docs" subfolder of your repository. Please note that "docs" is a magic string, the directory name must be exactly that. Please use templates from the DOC area to create basic documentation files like "index.rst" and so on.

Step 2.1: Make a new directory "docs/_static"

mkdir docs/_static

Step 2.2: Create an image file logo.png in the new docs/_static/ directory.  Here's a good source for the image:;a=blob;f=docs/_static/logo.png;h=c3b6ce56468d87a3d9463ee75297b3895fc9a414;hb=refs/heads/master

Step 2.3: Create file docs/ with exactly the following content:

from docs_conf.conf import *
linkcheck_ignore = [

Step 2.4 Create file docs/conf.yaml with the following content, but be sure to use your repo name, not "your-repo":

project_cfg: oran
project: your-repo

Step 2.5: Create a new image file docs/favicon.ico here's a good source for the icon:;a=blob;f=docs/favicon.ico;h=00b0fd0ef0b4e78fbb8cdb413ce84561dfeb404f;hb=refs/heads/master

Step 2.6: Create file docs/requirements-docs.txt with exactly the following content:


Step 3: Test locally

Working in the root of the repository, issue the following command to generate documentation. This assumes you have Python and Tox installed on the machine where you are working.

tox -e docs,docs-linkcheck

Note a common error message (see below) comes from RST formatting warning (warnings treated as errors). Fix the underlying RST (in the example that's installation-guides.rst) and try again.

### Possible/typical error message in the output // fix by fixing the underlying RST document Warning, treated as error: /home/fedora/tmp/doci/aaa/docs/index.rst:23:toctree contains reference to document 'installation-guides' that doesn't have a title: no link will be generated ERROR: InvocationError for command '/home/fedora/tmp/doci/aaa/.tox/docs-linkcheck/bin/sphinx-build -W -b linkcheck -d /home/...(exited with code 2)

If everything correct, you will see a succeed or successful output after running 'tox -e docs,docs-linkcheck'.  

It is the time to upload your change to gerrit. When you merged your change, you project docs will show on the page : If you can scroll down, and you project name will display on the right.

Please let DOC teamweichen niknow when you complete Step 3, as the configuration work in your_repo is finished, DOC team will handle Step 4 and make your docs work.

DOC team will do the Step 4 in DOC repo! If you are not from OSC DOC project, please do not do this step.  

Step 4: Add a link to your-repo documentation 

4.1 Clone the doc area via ssh. (best to just go here and select the ssh option ""

git clone "ssh://"lfid""

4.2 Add a mapping from key to URL in the file, for example:

$ grep -r portal-ric-dashboard .
./index.rst:* :doc:`RIC Dashboard <portal-ric-dashboard:index>`
./['portal-ric-dashboard'] = ('' % branch, None)

intersphinx_mapping['your-repo'] = ('' % branch, None)

4.3 Add a link to your mapping key in an appropriate file such as index.rst, for example:

* :doc:`Your Project <your-repo:index>

Step 5: Test publication

Edit a file in your docs/ area, commit the file to git and push your commit to Gerrit for review.  You should see a documentation build job start.

  • No labels


  1. the flag "skipsdist"=True is dangerous to existing python projects. It may or will break their unit tests. Please consider removing this from your instructions. 

    "If you do this, your local software package will not be installed into the virtualenv."

    1. Projects with a in the root of their repo are free to remove this.

  2. 2.6 Create file requirements-docs.txt with exactly the following content:

    in what directory?

  3. Please see the Step #2 where it says "your-repo/docs".  You asked about item 2.6.  You want me to repeat the directory name every single time?  Fine, I will do that.

    1. what you have now is more clear and not ambiguous.

  4. To note, `basepython:3.7:` is good for people whose dependencies can all use 37, but someone may have a dependency that says the max supported python is 36 (just as an example), so this isn't an ironclad solution. The above works for A1, but may not work for others. Maybe use "YOUR_NEEDED_PYTHON_VERSION" or something.

    My suggestion would be to not re-use the filename tox.ini, have people create a tox-docs.ini, then invoke the job with tox -c tox-docs.ini. This way, you can add back the sdist flag, and moreover, you have no change of clobbering anyone's tox.ini. I understand this is a larger change, but it gives the docs tox full power without concern over affecting the python project.

    1. This would require modifying the global tox job, which is possible, but beyond the scope of our current efforts.

      If the contents of this tox.ini cannot be integrated with a project they can open a ticket and we will work with them.

  5. skipsdist = true is lurking still
  6. Yes Aric Gardner  I agree your setup is faster, which is why I linked to your instructions in the second sentence on this page. (smile)

    1. Missed that, due to my brain content filtering. Made it bold and clear for people like me

  7. BTW, Aric, my git review works now. The problem is git package version was 1.8.X, reported missing changID  error. I updated to 2.X.X, problem solved.

  8. user-d3360

    Weichen,  I am confused by instructions step 4.2.  Do we use what's on this wiki page:

    or what's in the repo doc (docs/
      please go with the line above.
      Teh URL was recently changed.
      Thanks Lusheng for the reminder
  9. Weichen will you update that step 4.2 on this page, or would you like me to do that?

    1. I updated 4.2 based on Lusheng's confusion. Are there any other issue?