...
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.
2.1 Make an empty a new directory "docs/_static"
| No Format |
|---|
cdmkdir docs mkdir /_static |
2.2 Create an image file logo.png in the new docs/_static/ directory. Here's a good source for the image:
2.3 Now go back to the Create file docs/ directory and create file conf.py with exactly the following content:
...
| No Format |
|---|
--- project_cfg: oran project: your-repo |
2.5 Create an a new image file docs/favicon.ico here's a good source for the icon:
...
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.
| No Format |
|---|
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.
| No Format |
|---|
tox -e docs,docs-linkcheck ### 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) |
Step 4: Add a link to your-repo documentation (this section output error, please do not do this at the moment)
...