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.org/ 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 (niweichen@chinamobile.com)
Note: please add weichen ni as a reviewer on all Gerrit doc changesets if you have any questions.
Step 1.1: Create or extend file .gitignore in the root of your repository with the following content:
# documentation .tox docs/_build/ |
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 formats: - htmlzip build: image: latest python: version: 3.7 install: - requirements: docs/requirements-docs.txt sphinx: configuration: docs/conf.py |
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 setup.py file that defines how to build distributions.
# 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 |
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:
Step 2.3: Create file docs/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.*' ] |
Step 2.4 Create file docs/conf.yaml with the following content, but be sure to use your project 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:
Step 2.6: Create file docs/requirements-docs.txt with exactly the following content:
sphinx sphinx-rtd-theme sphinxcontrib-httpdomain recommonmark lfdocs-conf |
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) |
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?
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://o-ran-sc-doc.readthedocs.io/projects/o-ran-sc-portal-ric-dashboard/en/%s' % branch, None)
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> |
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.