--- /dev/null
+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
+
+
+
+
+
+
+
+
+
:local:
API-docs
-============
+========
.. note
API Introduction
----------------
+-----------------
.. Please add what API a component have exposed.
API Functions
----------------
+-------------
.. Please states the API functions.
--- /dev/null
+from docs_conf.conf import *
+linkcheck_ignore = [
+ 'http://localhost.*',
+ 'http://127.0.0.1.*',
+ 'https://gerrit.o-ran-sc.org.*'
+]
+
--- /dev/null
+---
+project_cfg: oran
+project: your_repo
+
+
+
:depth: 3
:local:
-Developer-Guides
-==============
+Developer-Guide
+===============
.. note:
--- /dev/null
+.. 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`
: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** |
Introduction
-============
+------------
+
.. <INTRODUCTION TO THE SCOPE AND INTENTION OF THIS DOCUMENT AS WELL AS TO THE SYSTEM TO BE INSTALLED>
.<EXAMPLE>:
Preface
-=======
+-------
.. <DESCRIBE NEEDED PREREQUISITES, PLANNING, ETC.>
<EXAMPLE>:
Hardware requirements
-=====================
+---------------------
.. <PROVIDE A LIST OF MINIMUM HARDWARE REQUIREMENTS NEEDED FOR THE INSTALL>
<EXAMPLE>:
-
-
Software installation and deployment
-==========================================
+------------------------------------
.. <DESCRIBE THE FULL PROCEDURES FOR THE INSTALLATION OF THE O-RAN COMPONENT INSTALLATION AND DEPLOYMENT>
<EXAMPLE>:
References
-==========
+----------
.. <PROVIDE NEEDED/USEFUL REFERENCES>
-<EXAMPLES>:
-OpenStack
-^^^^^^^^^^^
--- /dev/null
+..please write your project overview
+..please delete this content after editing
+
+
+your_repo Overview
+======================
.. http://creativecommons.org/licenses/by/4.0
+Release-notes
+=============
+
+
This document provides the release notes for <RELEASE> of <COMPONENT>.
.. contents::
Summary
-=======
+-------
<SUMMARIZE THE RELEASE - THE CONTENT - AND OTHER IMPORTANT HIGH LEVEL PROPERTIES>
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..... |
| **Release date** | E.g. 2015-04-16 |
| | |
+--------------------------------------+--------------------------------------+
-| **Purpose of the delivery** | E.g. OPNFV Internal quality assurance|
+| **Purpose of the delivery** | |
| | |
+--------------------------------------+--------------------------------------+
Feature additions
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
<STATE ADDED FEATURES BY REFERENCE TO JIRA>
<EXAMPLE>:
+--------------------------------------+--------------------------------------+
Bug corrections
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
**JIRA TICKETS:**
+--------------------------------------+--------------------------------------+
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>:
+--------------------------------------+--------------------------------------+
Workarounds
-^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^
<STATE ALL KNOWN WORKAROUNDS TO THE ISSUES STATED ABOVE, IF THERE IS ANY>
References
-==========
+----------
<STATE RELEVANT REFERENCES FOR THIS RELEASE/VERSION>
--- /dev/null
+---
+# .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
--- /dev/null
+[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
--- /dev/null
+sphinx
+sphinx-rtd-theme
+sphinxcontrib-httpdomain
+recommonmark
+lfdocs-conf
.. http://creativecommons.org/licenses/by/4.0
.. (c) <optionally add copywriters name>
+
+user guide
+==========
+
.. contents::
:depth: 3
:local:
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.
Code Review / doc.git / commitdiff
