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
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:
No Format |
---|
--- 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:
No Format |
---|
# 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 Create files in the "docs" subfolder of your repository. Please note that "docs" is a magic string, the directory name must be exactly that.
...
No Format |
---|
sphinx sphinx-rtd-theme sphinxcontrib-httpdomain recommonmark lfdocs-conf |
Step
...
4: 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" |
...
No Format |
---|
* :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.