Add support for generating documentation for smo/o1

Issue-ID: SMO-34

Signed-off-by: mjethanandani <mjethanandani@gmail.com>
Change-Id: I6f3ffd69f362ea6ef9556d1f1440a6ae46d5c97c
Signed-off-by: mjethanandani <mjethanandani@gmail.com>

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644 (file)
index 0000000..095222a
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,16 @@
+---
+version: 2
+
+formats:
+  - htmlzip
+
+build:
+  image: latest
+
+python:
+  version: 3.7
+  install:
+    - requirements: docs/requirements-docs.txt
+
+sphinx:
+  configuration: docs/conf.py

diff --git a/docs/_static/logo.png b/docs/_static/logo.png
new file mode 100644 (file)
index 0000000..c3b6ce5
Binary files /dev/null and b/docs/_static/logo.png differ

diff --git a/docs/api-docs.rst b/docs/api-docs.rst
new file mode 100644 (file)
index 0000000..b7fde67
--- /dev/null
+++ b/docs/api-docs.rst
@@ -0,0 +1,29 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+
+
+API-Docs
+========
+
+This is the API-docs of <COMPONENT>
+
+.. contents::
+   :depth: 3
+   :local:
+
+.. note
+
+.. This section is used to describe a software API exposed from a O-RAN software component.  
+   
+.. This note must be removed after content has been added.
+
+
+API Introduction
+-----------------
+.. Please add what API a component have exposed.
+
+API Functions
+-------------
+.. Please states the API functions.
+

diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644 (file)
index 0000000..922e22f
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,6 @@
+from docs_conf.conf import *
+linkcheck_ignore = [
+    'http://localhost.*',
+    'http://127.0.0.1.*',
+    'https://gerrit.o-ran-sc.org.*'
+]

diff --git a/docs/conf.yaml b/docs/conf.yaml
new file mode 100644 (file)
index 0000000..faf0db2
--- /dev/null
+++ b/docs/conf.yaml
@@ -0,0 +1,3 @@
+---
+project_cfg: oran
+project: smo/o1

diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst
new file mode 100644 (file)
index 0000000..0d1f6e0
--- /dev/null
+++ b/docs/developer-guide.rst
@@ -0,0 +1,32 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Developer-Guide
+===============
+
+.. contents::
+   :depth: 3
+   :local:
+
+.. note:
+..   * This section is used to describe what a contributor needs to know in order to work on the componenta
+
+..   * this should be very technical, aimed at people who want to help develop the components
+
+..   * this should be how the component does what it does, not a requirements document of what the component should do
+
+..   * this should contain what language(s) and frameworks are used, with versions
+
+..   * this should contain how to obtain the code, where to look at work items (Jira tickets), how to get started developing
+   
+..   * This note must be removed after content has been added.
+
+
+Processes
+---------
+
+
+
+Actions
+-------
+

diff --git a/docs/favicon.ico b/docs/favicon.ico
new file mode 100644 (file)
index 0000000..00b0fd0
Binary files /dev/null and b/docs/favicon.ico differ

diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644 (file)
index 0000000..b209a29
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,23 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+
+
+Welcome to O-RAN SC your_repo Documentation
+===========================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   overview.rst
+   developer-guide.rst
+   release-notes.rst
+   installation-guide.rst
+   user-guide.rst
+   api-docs.rst
+
+
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

diff --git a/docs/installation-guide.rst b/docs/installation-guide.rst
new file mode 100644 (file)
index 0000000..2412acf
--- /dev/null
+++ b/docs/installation-guide.rst
@@ -0,0 +1,109 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+
+
+Installation Guide
+==================
+
+.. contents::
+   :depth: 3
+   :local:
+
+Abstract
+--------
+
+This document describes how to install <Component>, it's dependencies and required system resources.
+
+
+Version history
+
++--------------------+--------------------+--------------------+--------------------+
+| **Date**           | **Ver.**           | **Author**         | **Comment**        |
+|                    |                    |                    |                    |
++--------------------+--------------------+--------------------+--------------------+
+| 20XX-XX-XX         | 0.1.0              |                   | First draft        |
+|                    |                    |                    |                    |
++--------------------+--------------------+--------------------+--------------------+
+|                    | 0.1.1              |                    |                    |
+|                    |                    |                    |                    |
++--------------------+--------------------+--------------------+--------------------+
+|                    | 1.0                |                    |                    |
+|                    |                    |                    |                    |
+|                    |                    |                    |                    |
++--------------------+--------------------+--------------------+--------------------+
+
+
+Introduction
+------------
+
+.. <INTRODUCTION TO THE SCOPE AND INTENTION OF THIS DOCUMENT AS WELL AS TO THE SYSTEM TO BE INSTALLED>
+
+.<EXAMPLE>:
+
+This document describes the supported software and hardware configurations for the reference component as well as providing guidelines on how to install and configure such reference system.
+
+The audience of this document is assumed to have good knowledge in RAN network nd Linux system.
+
+
+Preface
+-------
+.. <DESCRIBE NEEDED PREREQUISITES, PLANNING, ETC.>
+
+<EXAMPLE>:
+
+Before starting the installation of <project name>, some planning must preceed.
+
+.. note:any preperation you need before setting up sotfware and hardware 
+
+
+Hardware Requirements
+---------------------
+.. <PROVIDE A LIST OF MINIMUM HARDWARE REQUIREMENTS NEEDED FOR THE INSTALL>
+
+<EXAMPLE>:
+
+Following minimum hardware requirements must be met for installation of <project name>:
+
++--------------------+----------------------------------------------------+
+| **HW Aspect**      | **Requirement**                                    |
+|                    |                                                    |
++--------------------+----------------------------------------------------+
+| **# of servers**   |                                                           |
++--------------------+----------------------------------------------------+
+| **CPU**            |                                                           |
+|                    |                                                    |
++--------------------+----------------------------------------------------+
+| **RAM**            |                                                           |
+|                    |                                                    |
++--------------------+----------------------------------------------------+
+| **Disk**           |                                                           |
+|                    |                                                    |
++--------------------+----------------------------------------------------+
+| **NICs**           |                                                           |
+|                    |                                                    |
+|                    |                                                           |
+|                    |                                                    |
+|                    |                                                   |
+|                    |                                                    |
++--------------------+----------------------------------------------------+
+
+
+
+Software Installation and Deployment
+------------------------------------
+.. <DESCRIBE THE FULL PROCEDURES FOR THE INSTALLATION OF THE O-RAN COMPONENT INSTALLATION AND DEPLOYMENT>
+
+<EXAMPLE>:
+
+This section describes the installation of the <project name> installation on the reference hardware.
+
+
+
+References
+----------
+.. <PROVIDE NEEDED/USEFUL REFERENCES>
+
+
+
+

diff --git a/docs/overview.rst b/docs/overview.rst
new file mode 100644 (file)
index 0000000..6d620a1
--- /dev/null
+++ b/docs/overview.rst
@@ -0,0 +1,10 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+
+
+..please write your project overview
+..please delete this content after editing
+
+
+your_repo Overview
+======================

diff --git a/docs/release-notes.rst b/docs/release-notes.rst
new file mode 100644 (file)
index 0000000..0359af4
--- /dev/null
+++ b/docs/release-notes.rst
@@ -0,0 +1,169 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+
+Release-Notes
+=============
+
+
+This document provides the release notes for <RELEASE> of <COMPONENT>.
+
+.. contents::
+   :depth: 3
+   :local:
+
+
+Version history
+---------------
+
++--------------------+--------------------+--------------------+--------------------+
+| **Date**           | **Ver.**           | **Author**         | **Comment**        |
+|                    |                    |                    |                    |
++--------------------+--------------------+--------------------+--------------------+
+| 20XX-XX-XX         | 0.1.0              |                    | First draft        |
+|                    |                    |                    |                    |
++--------------------+--------------------+--------------------+--------------------+
+|                    | 0.1.1              |                    |                    |
+|                    |                    |                    |                    |
++--------------------+--------------------+--------------------+--------------------+
+|                    | 1.0                |                    |                    |
+|                    |                    |                    |                    |
++--------------------+--------------------+--------------------+--------------------+
+
+
+Summary
+-------
+
+<SUMMARIZE THE RELEASE - THE CONTENT - AND OTHER IMPORTANT HIGH LEVEL PROPERTIES>
+
+
+
+
+Release Data
+------------
+<STATE RELEVANT RELEASE DATA/RECORDS>
+
+<EXAMPLE>:
+
++--------------------------------------+--------------------------------------+
+| **Project**                          | E.g. project                                |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+| **Repo/commit-ID**                   | E.g. genesis/adf634a0d4.....         |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+| **Release designation**              | E.g. Arno RC2                        |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+| **Release date**                     | E.g. 2015-04-16                      |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+| **Purpose of the delivery**          |                                     |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+
+
+
+
+Feature Additions
+^^^^^^^^^^^^^^^^^
+<STATE ADDED FEATURES BY REFERENCE TO JIRA>
+
+<EXAMPLE>:
+
+**JIRA BACK-LOG:**
+
++--------------------------------------+--------------------------------------+
+| **JIRA REFERENCE**                   | **SLOGAN**                           |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+|                                     |                                      |
+|                                      |                                     |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+|                                     |                                      |
+|                                      |                                     |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+
+Bug Corrections
+^^^^^^^^^^^^^^^
+
+**JIRA TICKETS:**
+
++--------------------------------------+--------------------------------------+
+| **JIRA REFERENCE**                   | **SLOGAN**                           |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+|                                     |                                      |
+|                                      |                                     |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+|                                     |                                      |
+|                                      |                                     |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+
+Deliverables
+^^^^^^^^^^^^
+
+Software Deliverables
++++++++++++++++++++++
+
+<STATE WHAT SOFTWARE DELIVERABLES THAT ARE RELATED TO THIS VERSION, AND WHERE THOSE CAN BE RETRIEVED>
+
+
+
+Documentation Deliverables
+++++++++++++++++++++++++++
+
+<STATE WHAT DOCUMENTATION DELIVERABLES THAT ARE RELATED TO THIS VERSION, AND WHERE THOSE CAN BE RETRIEVED>
+
+
+
+
+Known Limitations, Issues and Workarounds
+-----------------------------------------
+
+System Limitations
+^^^^^^^^^^^^^^^^^^
+<STATE ALL RELEVANT SYSTEM LIMITATIONS, IF THERE IS ANY>
+
+
+
+Known Issues
+^^^^^^^^^^^^
+<STATE ALL KNOWN ISSUES WITH JIRA REFERENCE>
+
+<EXAMPLE>:
+
+**JIRA TICKETS:**
+
++--------------------------------------+--------------------------------------+
+| **JIRA REFERENCE**                   | **SLOGAN**                           |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+|                                     |                                      |
+|                                      |                                     |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+|                                     |                                      |
+|                                      |                                     |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+
+Workarounds
+^^^^^^^^^^^
+
+<STATE ALL KNOWN WORKAROUNDS TO THE ISSUES STATED ABOVE, IF THERE IS ANY>
+
+
+
+
+References
+----------
+<STATE RELEVANT REFERENCES FOR THIS RELEASE/VERSION>
+
+
+
+

diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
new file mode 100644 (file)
index 0000000..09a0c1c
--- /dev/null
+++ b/docs/requirements-docs.txt
@@ -0,0 +1,5 @@
+sphinx
+sphinx-rtd-theme
+sphinxcontrib-httpdomain
+recommonmark
+lfdocs-conf

diff --git a/docs/user-guide.rst b/docs/user-guide.rst
new file mode 100644 (file)
index 0000000..989f319
--- /dev/null
+++ b/docs/user-guide.rst
@@ -0,0 +1,32 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) <optionally add copywriters name>
+
+
+User Guide
+==========
+
+This is the user guide of OSC <COMPONENT>.
+
+.. contents::
+   :depth: 3
+   :local:
+
+..  a user guide should be how to use the component or system; it should not be a requirements document
+..  delete this content after edittng it
+
+
+Description
+-----------
+.. Describe the traget users of the projcet, for example, modeler/data scientist, ORAN-OSC platform admin, marketplace user, design studio end user, etc
+.. Descirbe how the target users can get use of a O-RAN SC component.
+.. If the guide contains sections on third-party tools, is it clearly stated why the O-RAN-OSC platform is using those tools? Are there instructions on how to install and configure each tool/toolset?
+
+Feature Introduction
+--------------------
+.. Provide enough information that a user will be able to operate the feature on a deployed scenario. content can be added from administration, management, using, Troubleshooting sections perspectives.
+
+
+
+    
+

diff --git a/tox.ini b/tox.ini
new file mode 100644 (file)
index 0000000..72742cf
--- /dev/null
+++ b/tox.ini
@@ -0,0 +1,30 @@
+# 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