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://docs.o-ran-sc.readthedocs.io/en/latest/ upon org/ upon change of any file within your docs/ directory.
...
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:
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.
Manual Step 1: Add files to your-repo root
...
| No Format |
|---|
--- version: 2 formats: - htmlzip build: imageos: latest python: version: "ubuntu-22.04" tools: python: "3.7" python install: - requirements: docs/requirements-docs.txt sphinx: configuration: docs/conf.py |
...
Step 2.4 Create file docs/conf.yaml with the following content, but be sure to use your project repo name, not "your-repo":
| No Format |
|---|
--- project_cfg: oran project: your-repo |
...
| No Format |
|---|
### 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 : https://readthedocs.org/projects/o-ran-sc-doc/. 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 "https://gerrit.o-ran-sc.org/r/admin/repos/doc"
I think your strange cloning is why you are having problems pushing reviews. are you not using git-review?
| No Format |
|---|
git clone "ssh://"lfid"@gerrit.o-ran-sc.org:29418/doc" |
4.2 Add a mapping from key to URL in the conf.py file, for example:
I think the Docs PTL should take care of the intersphinx mapping. Also each project should have at least one anchor in their docs/index.rst at a minimum. https://www.sphinx-doc.org/en/1.5/markup/inline.html#cross-referencing-arbitrary-locations
This probably explains how to set up the intersphinx mapping for subprojects the best, however. Once we move to the docs.o-ran-sc.org CNAME this will change, so personally I would just ask teams to focus on their own docs and worry about linking them to the index later.
I think the doc ptl should organize the main index page in any case.
$ grep -r portal-ric-dashboard .
./index.rst:* :doc:`RIC Dashboard <portal-ric-dashboard:index>`
./conf.py:intersphinx_mapping['portal-ric-dashboard'] = ('https://docs.o-ran-sc-doc.readthedocs.ioorg/projects/o-ran-sc-portal-ric-dashboard/en/%s' % branch, None)
| No Format |
|---|
intersphinx_mapping['your-repo'] = ('https://docs.o-ran-sc-doc.readthedocs.ioorg/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:
...