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 includes specifics you will need to follow the process 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 file your-repo/.readthedocs
Create a file in the root of your repository called .readthedocs.yaml (yes there's a leading dot) with the following content:
No Format |
---|
---
version: 2
formats:
- htmlzip
build:
image: latest
python:
version: 3.7
install:
- requirements: docs/requirements-docs.txt
sphinx:
configuration: docs/conf.py |
Step 2: Configure your-repo/docs area
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"
No Format |
---|
cd docs
mkdir _static |
2.2 Create file conf.py with exactly the following content:
No Format |
---|
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":
No Format |
---|
---
project_cfg: oran
project: your-repo |
2.4 Create file requirements-docs.txt with exactly the following content:
No Format |
---|
sphinx
sphinx-rtd-theme
sphinxcontrib-httpdomain
recommonmark
lfdocs-conf |
Step 3: Add a link to your-repo documentation
3.1 Clone the doc area:
No Format |
---|
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:
No Format |
---|
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:
No Format |
---|
* :doc:`Your Project <your-repo:index> |
Step 4: Test
...
Page moved to the DOC space: Configure Repo for Documentation