You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 14 Next »

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-doc.readthedocs.io/en/latest/ upon change of any file within your docs/ directory.

This page gives step by step details. Alternately you can use an automated process as documented at https://docs.releng.linuxfoundation.org/projects/global-jjb/en/latest/jjb/lf-rtdv3-jobs.html

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

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

2.1 Make an empty directory "_static"

cd docs
mkdir _static

2.2 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.3 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.4 Create file requirements-docs.txt with exactly the following content:

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

Step 4: Add a link to your-repo documentation

3.1 Clone the doc area:

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

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

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

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