Page History

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 https://o-ran-sc.readthedocs.io/en/latest/ upon change of any file within your docs/ directory.

Please use the automated setup process that is documented at https://docs.releng.linuxfoundation.org/projects/global-jjb/en/latest/jjb/lf-rtdv3-jobs.html

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

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

Step 1: Add files to your-repo root

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

# documentation
.tox
docs/_build/

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

formats:
  - htmlzip

build:
  image: latest

python:
  version: 3.7
  install:
    - requirements: docs/requirements-docs.txt

sphinx:
  configuration: docs/conf.py

1.2 Create file tox.ini

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

# documentation only
[tox]
minversion = 2.0
envlist =
    docs,
    docs-linkcheck,
skipsdist = true

[testenv:docs]
basepython = python3
deps = 
    sphinx
    sphinx-rtd-theme
    sphinxcontrib-httpdomain
    recommonmark
    lfdocs-conf
    
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

[testenv:docs-linkcheck]
basepython = python3
deps = sphinx
       sphinx-rtd-theme
       sphinxcontrib-httpdomain
       recommonmark
       lfdocs-conf
commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck

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.

2.1 Make an empty directory "_static"

cd docs
mkdir _static

2.2 Create an image file logo.png in the new _static/ directory.  Here's a good source for the image:

https://gerrit.o-ran-sc.org/r/gitweb?p=doc.git;a=blob;f=docs/_static/logo.png;h=c3b6ce56468d87a3d9463ee75297b3895fc9a414;hb=refs/heads/master

2.3 Now go back to the docs/ directory and create file conf.py with exactly the following content:

from docs_conf.conf import *
linkcheck_ignore = [
    'http://localhost.*',
    'http://127.0.0.1.*',
    'https://gerrit.o-ran-sc.org.*'
]

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

---
project_cfg: oran
project: your-repo

2.5 Create an image file favicon.ico in the docs/ directory. Here's a good source for the icon:

https://gerrit.o-ran-sc.org/r/gitweb?p=doc.git;a=blob;f=docs/favicon.ico;h=00b0fd0ef0b4e78fbb8cdb413ce84561dfeb404f;hb=refs/heads/master

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

sphinx
sphinx-rtd-theme
sphinxcontrib-httpdomain
recommonmark
lfdocs-conf

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. 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.

tox -e docs,docs-linkcheck


### 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)

Step 4: Add a link to your-repo documentation

4.1 Clone the doc area:

git clone "https://gerrit.o-ran-sc.org/r/doc"

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

intersphinx_mapping['your-repo'] = ('https://o-ran-sc-doc.readthedocs.io/projects/o-ran-sc-your-repo/en/%s' % branch, None a

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

...

Page moved to the DOC space: Configure Repo for Documentation