add doc config files and update doc-templates
Signed-off-by: weichen <niweichen@chinamobile.com>
Change-Id: I418ec4daba04f8e09fe4cb4605fd78c37b2faee2
diff --git a/doc-templates/REAMDME.txt b/doc-templates/REAMDME.txt
new file mode 100644
index 0000000..bfcf6b9
--- /dev/null
+++ b/doc-templates/REAMDME.txt
@@ -0,0 +1,120 @@
+This README.txt file is a tutorial of how to create repo documentation.
+This is a copy&paste solution of documentation, and there is a step-by-step tutorial of creating documentation on https://wiki.o-ran-sc.org/display/DOC. Both solution work, your can choose a way you prefer.
+
+
+Tutorial starts here.
+
+Assuming you already git clone doc repo in your local system.
+
+Step 1:
+
+Copy all files in doc/doc-templates/ to your local directory, your_repo/docs/,
+
+Note: replace your_repo with the repo name you are working on.
+
+
+Step 2:
+Move 'tox.ini' & '.readthedocs.yaml' in doc/docs/repo-root-dir-files/ to your_repo/
+
+Note: 1. replace your_repo with the repo name you are working on.
+ 2. '.readthedocs.yaml' is not visible by 'ls' or 'll' command, please double check after moving. Better try 'vi .readthedocs.yaml' to check
+
+
+Step 3:
+
+Choose templates you will have from [api-docs.rst,developer-guide.rst,installation-guide.rst,release-notes.rst,user-guide.rst] for documentation, and finish editing them.
+
+Note: 1. If your don't need any of them, just simply delete the one you do not need.
+ 2. Teamplates just provide a guideline for documentation. If you have any specific request, please feel free do it yourself.
+
+
+Step 4:
+Editing index.rst. There is a scetion including what rst files your will have in your repo documentaion, something like following:
+
+#############
+example start
+#############
+
+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
+
+
+.. toctree::
+ :maxdepth: 2
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+
+############
+example ends
+############
+
+Overview.rst is required for each repo while others are optional. Please delete the line (rst files line) you do not need.
+For example if you donot need api-docs:
+
+
+#############
+example start
+#############
+
+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
+
+
+.. toctree::
+ :maxdepth: 2
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+
+############
+example ends
+############
+
+
+Step 5
+Editing overview.rst, there is instruction in the file.
+
+
+Step 6:
+Testing your documentation by running 'tox -e docs,docs-linkcheck' command.
+If everything correct, you can open your_repo/docs/_build/html/index.html to see it locally.
+
+Step 7:
+upload your documentaion patch
+
+
+
+
+
+
+
+
+
diff --git a/doc-templates/_static/logo.png b/doc-templates/_static/logo.png
new file mode 100644
index 0000000..c3b6ce5
--- /dev/null
+++ b/doc-templates/_static/logo.png
Binary files differ
diff --git a/doc-templates/api-docs.rst b/doc-templates/api-docs.rst
index ca058f3..6ccc6e4 100644
--- a/doc-templates/api-docs.rst
+++ b/doc-templates/api-docs.rst
@@ -6,7 +6,7 @@
:local:
API-docs
-============
+========
.. note
@@ -16,10 +16,10 @@
API Introduction
----------------
+-----------------
.. Please add what API a component have exposed.
API Functions
----------------
+-------------
.. Please states the API functions.
diff --git a/doc-templates/conf.py b/doc-templates/conf.py
new file mode 100644
index 0000000..89033cf
--- /dev/null
+++ b/doc-templates/conf.py
@@ -0,0 +1,7 @@
+from docs_conf.conf import *
+linkcheck_ignore = [
+ 'http://localhost.*',
+ 'http://127.0.0.1.*',
+ 'https://gerrit.o-ran-sc.org.*'
+]
+
diff --git a/doc-templates/conf.yaml b/doc-templates/conf.yaml
new file mode 100644
index 0000000..e8c5e92
--- /dev/null
+++ b/doc-templates/conf.yaml
@@ -0,0 +1,6 @@
+---
+project_cfg: oran
+project: your_repo
+
+
+
diff --git a/doc-templates/developer-guides.rst b/doc-templates/developer-guide.rst
similarity index 95%
rename from doc-templates/developer-guides.rst
rename to doc-templates/developer-guide.rst
index 3084821..4707804 100644
--- a/doc-templates/developer-guides.rst
+++ b/doc-templates/developer-guide.rst
@@ -5,8 +5,8 @@
:depth: 3
:local:
-Developer-Guides
-==============
+Developer-Guide
+===============
.. note:
diff --git a/doc-templates/favicon.ico b/doc-templates/favicon.ico
new file mode 100644
index 0000000..00b0fd0
--- /dev/null
+++ b/doc-templates/favicon.ico
Binary files differ
diff --git a/doc-templates/index.rst b/doc-templates/index.rst
new file mode 100644
index 0000000..e3901b3
--- /dev/null
+++ b/doc-templates/index.rst
@@ -0,0 +1,26 @@
+.. 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
+
+
+.. toctree::
+ :maxdepth: 2
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/doc-templates/installation-guides.rst b/doc-templates/installation-guide.rst
similarity index 95%
rename from doc-templates/installation-guides.rst
rename to doc-templates/installation-guide.rst
index 92c0f2d..fd961e8 100755
--- a/doc-templates/installation-guides.rst
+++ b/doc-templates/installation-guide.rst
@@ -5,18 +5,16 @@
:depth: 3
:local:
-========
+Installation guide
+==================
+
Abstract
-========
+--------
This document describes how to install <Component>, it's dependencies and required system resources.
-.. contents::
- :depth: 3
- :local:
Version history
----------------------
+--------------------+--------------------+--------------------+--------------------+
| **Date** | **Ver.** | **Author** | **Comment** |
@@ -35,7 +33,8 @@
Introduction
-============
+------------
+
.. <INTRODUCTION TO THE SCOPE AND INTENTION OF THIS DOCUMENT AS WELL AS TO THE SYSTEM TO BE INSTALLED>
.<EXAMPLE>:
@@ -46,7 +45,7 @@
Preface
-=======
+-------
.. <DESCRIBE NEEDED PREREQUISITES, PLANNING, ETC.>
<EXAMPLE>:
@@ -57,7 +56,7 @@
Hardware requirements
-=====================
+---------------------
.. <PROVIDE A LIST OF MINIMUM HARDWARE REQUIREMENTS NEEDED FOR THE INSTALL>
<EXAMPLE>:
@@ -89,10 +88,8 @@
-
-
Software installation and deployment
-==========================================
+------------------------------------
.. <DESCRIBE THE FULL PROCEDURES FOR THE INSTALLATION OF THE O-RAN COMPONENT INSTALLATION AND DEPLOYMENT>
<EXAMPLE>:
@@ -102,12 +99,9 @@
References
-==========
+----------
.. <PROVIDE NEEDED/USEFUL REFERENCES>
-<EXAMPLES>:
-OpenStack
-^^^^^^^^^^^
diff --git a/doc-templates/overview.rst b/doc-templates/overview.rst
new file mode 100644
index 0000000..f29301e
--- /dev/null
+++ b/doc-templates/overview.rst
@@ -0,0 +1,6 @@
+..please write your project overview
+..please delete this content after editing
+
+
+your_repo Overview
+======================
diff --git a/doc-templates/release-notes.rst b/doc-templates/release-notes.rst
index b0d6530..ceb4bf8 100644
--- a/doc-templates/release-notes.rst
+++ b/doc-templates/release-notes.rst
@@ -2,6 +2,10 @@
.. http://creativecommons.org/licenses/by/4.0
+Release-notes
+=============
+
+
This document provides the release notes for <RELEASE> of <COMPONENT>.
.. contents::
@@ -28,7 +32,7 @@
Summary
-=======
+-------
<SUMMARIZE THE RELEASE - THE CONTENT - AND OTHER IMPORTANT HIGH LEVEL PROPERTIES>
@@ -36,13 +40,13 @@
Release Data
-============
+------------
<STATE RELEVANT RELEASE DATA/RECORDS>
<EXAMPLE>:
+--------------------------------------+--------------------------------------+
-| **Project** | E.g. Arno/genesis/fuel@opnfv |
+| **Project** | E.g. project |
| | |
+--------------------------------------+--------------------------------------+
| **Repo/commit-ID** | E.g. genesis/adf634a0d4..... |
@@ -54,7 +58,7 @@
| **Release date** | E.g. 2015-04-16 |
| | |
+--------------------------------------+--------------------------------------+
-| **Purpose of the delivery** | E.g. OPNFV Internal quality assurance|
+| **Purpose of the delivery** | |
| | |
+--------------------------------------+--------------------------------------+
@@ -62,7 +66,7 @@
Feature additions
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
<STATE ADDED FEATURES BY REFERENCE TO JIRA>
<EXAMPLE>:
@@ -83,7 +87,7 @@
+--------------------------------------+--------------------------------------+
Bug corrections
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
**JIRA TICKETS:**
@@ -101,34 +105,34 @@
+--------------------------------------+--------------------------------------+
Deliverables
-----------------
+^^^^^^^^^^^^
Software deliverables
-^^^^^^^^^^^^^^^^^^^^^^^
++++++++++++++++++++++
<STATE WHAT SOFTWARE DELIVERABLES THAT ARE RELATED TO THIS VERSION, AND WHERE THOSE CAN BE RETRIEVED>
-<EXAMPLE>:
+
Documentation deliverables
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+++++++++++++++++++++++++++
<STATE WHAT DOCUMENTATION DELIVERABLES THAT ARE RELATED TO THIS VERSION, AND WHERE THOSE CAN BE RETRIEVED>
-<EXAMPLE>:
+
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>:
@@ -149,7 +153,7 @@
+--------------------------------------+--------------------------------------+
Workarounds
-^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^
<STATE ALL KNOWN WORKAROUNDS TO THE ISSUES STATED ABOVE, IF THERE IS ANY>
@@ -157,7 +161,7 @@
References
-==========
+----------
<STATE RELEVANT REFERENCES FOR THIS RELEASE/VERSION>
diff --git a/doc-templates/repo-root-dir-files/.readthedocs.yaml b/doc-templates/repo-root-dir-files/.readthedocs.yaml
new file mode 100644
index 0000000..3797dc8
--- /dev/null
+++ b/doc-templates/repo-root-dir-files/.readthedocs.yaml
@@ -0,0 +1,20 @@
+---
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# Required
+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/doc-templates/repo-root-dir-files/tox.ini b/doc-templates/repo-root-dir-files/tox.ini
new file mode 100644
index 0000000..db50ddf
--- /dev/null
+++ b/doc-templates/repo-root-dir-files/tox.ini
@@ -0,0 +1,32 @@
+[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
diff --git a/doc-templates/requirements-docs.txt b/doc-templates/requirements-docs.txt
new file mode 100644
index 0000000..09a0c1c
--- /dev/null
+++ b/doc-templates/requirements-docs.txt
@@ -0,0 +1,5 @@
+sphinx
+sphinx-rtd-theme
+sphinxcontrib-httpdomain
+recommonmark
+lfdocs-conf
diff --git a/doc-templates/user-guides.rst b/doc-templates/user-guide.rst
similarity index 94%
rename from doc-templates/user-guides.rst
rename to doc-templates/user-guide.rst
index fe3faab..ed4d58b 100755
--- a/doc-templates/user-guides.rst
+++ b/doc-templates/user-guide.rst
@@ -2,6 +2,10 @@
.. http://creativecommons.org/licenses/by/4.0
.. (c) <optionally add copywriters name>
+
+user guide
+==========
+
.. contents::
:depth: 3
:local:
@@ -11,13 +15,13 @@
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.
