From: wrider Date: Sun, 3 Nov 2019 19:35:07 +0000 (-0500) Subject: Add documentation skeleton X-Git-Tag: 0.0.2~4^2 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=refs%2Fchanges%2F37%2F1337%2F3;p=it%2Fdep.git Add documentation skeleton Change-Id: I3d9438da7fdbb21f72ac6f2d5a5178b53711a27f Signed-off-by: wrider --- diff --git a/.gitignore b/.gitignore index 2fd1c281..7de0f2d6 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,5 @@ *.tgz *.swp *.lock +.tox +docs/_build/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..095222ac --- /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 index 00000000..c3b6ce56 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 index 00000000..1e8bc3d9 --- /dev/null +++ b/docs/api-docs.rst @@ -0,0 +1,39 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. ===============LICENSE_START======================================================= +.. Copyright (C) 2019 AT&T Intellectual Property +.. =================================================================================== +.. This documentation file is distributed under the Creative Commons Attribution +.. 4.0 International License (the "License"); you may not use this file except in +.. compliance with the License. You may obtain a copy of the License at +.. +.. http://creativecommons.org/licenses/by/4.0 +.. +.. This file is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ===============LICENSE_END========================================================= + +.. contents:: + :depth: 3 + :local: + +API Documentation +================= + +.. 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 index 00000000..8f290477 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,21 @@ +################################################################################ +# Copyright (c) 2019 AT&T Intellectual Property. # +# # +# Licensed under the Apache License, Version 2.0 (the "License"); # +# you may not use this file except in compliance with the License. # +# You may obtain a copy of the License at # +# # +# http://www.apache.org/licenses/LICENSE-2.0 # +# # +# Unless required by applicable law or agreed to in writing, software # +# distributed under the License is distributed on an "AS IS" BASIS, # +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # +# See the License for the specific language governing permissions and # +# limitations under the License. # +################################################################################ +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 index 00000000..c24e0a71 --- /dev/null +++ b/docs/conf.yaml @@ -0,0 +1,18 @@ +################################################################################ +# Copyright (c) 2019 AT&T Intellectual Property. # +# # +# Licensed under the Apache License, Version 2.0 (the "License"); # +# you may not use this file except in compliance with the License. # +# You may obtain a copy of the License at # +# # +# http://www.apache.org/licenses/LICENSE-2.0 # +# # +# Unless required by applicable law or agreed to in writing, software # +# distributed under the License is distributed on an "AS IS" BASIS, # +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # +# See the License for the specific language governing permissions and # +# limitations under the License. # +################################################################################ +--- +project_cfg: oran +project: it-dep diff --git a/docs/developer-guides.rst b/docs/developer-guides.rst new file mode 100644 index 00000000..e3d579d9 --- /dev/null +++ b/docs/developer-guides.rst @@ -0,0 +1,47 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. ===============LICENSE_START======================================================= +.. Copyright (C) 2019 AT&T Intellectual Property +.. =================================================================================== +.. This documentation file is distributed under the Creative Commons Attribution +.. 4.0 International License (the "License"); you may not use this file except in +.. compliance with the License. You may obtain a copy of the License at +.. +.. http://creativecommons.org/licenses/by/4.0 +.. +.. This file is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ===============LICENSE_END========================================================= + +.. contents:: + :depth: 3 + :local: + +Developer-Guides +================ + + +.. 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 index 00000000..00b0fd0e Binary files /dev/null and b/docs/favicon.ico differ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..c1fed9b7 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,33 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. ===============LICENSE_START======================================================= +.. Copyright (C) 2019 AT&T Intellectual Property +.. =================================================================================== +.. This documentation file is distributed under the Creative Commons Attribution +.. 4.0 International License (the "License"); you may not use this file except in +.. compliance with the License. You may obtain a copy of the License at +.. +.. http://creativecommons.org/licenses/by/4.0 +.. +.. This file is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ===============LICENSE_END========================================================= + + +.. Integration and Testing Documentation + +Integration and Testing +=========================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + release-notes + installation-guides + user-guides + api-docs + developer-guides + diff --git a/docs/installation-guides.rst b/docs/installation-guides.rst new file mode 100755 index 00000000..05231f54 --- /dev/null +++ b/docs/installation-guides.rst @@ -0,0 +1,127 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. ===============LICENSE_START======================================================= +.. Copyright (C) 2019 AT&T Intellectual Property +.. =================================================================================== +.. This documentation file is distributed under the Creative Commons Attribution +.. 4.0 International License (the "License"); you may not use this file except in +.. compliance with the License. You may obtain a copy of the License at +.. +.. http://creativecommons.org/licenses/by/4.0 +.. +.. This file is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ===============LICENSE_END========================================================= + +.. contents:: + :depth: 3 + :local: + +======== +Abstract +======== + +This document describes how to install , it's dependencies and required system resources. + +.. contents:: + :depth: 3 + :local: + +Version history +--------------------- + ++--------------------+--------------------+--------------------+--------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| 20XX-XX-XX | 0.1.0 | | First draft | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| | 0.1.1 | | | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| | 1.0 | | | +| | | | | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ + + +Introduction +============ +.. + +.: + +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 +======= +.. + +: + +Before starting the installation of , some planning must preceed. + +.. note:any preperation you need before setting up sotfware and hardware + + +Hardware requirements +===================== +.. + +: + +Following minimum hardware requirements must be met for installation of : + ++--------------------+----------------------------------------------------+ +| **HW Aspect** | **Requirement** | +| | | ++--------------------+----------------------------------------------------+ +| **# of servers** | | ++--------------------+----------------------------------------------------+ +| **CPU** | | +| | | ++--------------------+----------------------------------------------------+ +| **RAM** | | +| | | ++--------------------+----------------------------------------------------+ +| **Disk** | | +| | | ++--------------------+----------------------------------------------------+ +| **NICs** | | +| | | +| | | +| | | +| | | +| | | ++--------------------+----------------------------------------------------+ + + + + + +Software installation and deployment +========================================== +.. + +: + +This section describes the installation of the installation on the reference hardware. + + + +References +========== +.. + +: + +OpenStack +^^^^^^^^^^^ + + diff --git a/docs/release-notes.rst b/docs/release-notes.rst new file mode 100644 index 00000000..db17b4fc --- /dev/null +++ b/docs/release-notes.rst @@ -0,0 +1,182 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. ===============LICENSE_START======================================================= +.. Copyright (C) 2019 AT&T Intellectual Property +.. =================================================================================== +.. This documentation file is distributed under the Creative Commons Attribution +.. 4.0 International License (the "License"); you may not use this file except in +.. compliance with the License. You may obtain a copy of the License at +.. +.. http://creativecommons.org/licenses/by/4.0 +.. +.. This file is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ===============LICENSE_END========================================================= + + +This document provides the release notes for of . + +.. contents:: + :depth: 3 + :local: + + +Version history +--------------- + ++--------------------+--------------------+--------------------+--------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| 20XX-XX-XX | 0.1.0 | | First draft | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| | 0.1.1 | | | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| | 1.0 | | | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ + + +Summary +======= + + + + + + +Release Data +============ + + +: + ++--------------------------------------+--------------------------------------+ +| **Project** | E.g. Arno/genesis/fuel@opnfv | +| | | ++--------------------------------------+--------------------------------------+ +| **Repo/commit-ID** | E.g. genesis/adf634a0d4..... | +| | | ++--------------------------------------+--------------------------------------+ +| **Release designation** | E.g. Arno RC2 | +| | | ++--------------------------------------+--------------------------------------+ +| **Release date** | E.g. 2015-04-16 | +| | | ++--------------------------------------+--------------------------------------+ +| **Purpose of the delivery** | E.g. OPNFV Internal quality assurance| +| | | ++--------------------------------------+--------------------------------------+ + + + + +Feature additions +------------------- + + +: + +**JIRA BACK-LOG:** + ++--------------------------------------+--------------------------------------+ +| **JIRA REFERENCE** | **SLOGAN** | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ + +Bug corrections +---------------- + +**JIRA TICKETS:** + ++--------------------------------------+--------------------------------------+ +| **JIRA REFERENCE** | **SLOGAN** | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ + +Deliverables +============ + + + + +Software deliverables +--------------------- + + + +: + +Documentation deliverables +--------------------------- + + + +: + + +Known Limitations, Issues and Workarounds +========================================= + +System Limitations +------------------ + + + + +Known issues +------------------ + + +: + +**JIRA TICKETS:** + ++--------------------------------------+--------------------------------------+ +| **JIRA REFERENCE** | **SLOGAN** | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ + +Workarounds +------------------ + + + + + + +References +========== + + + + + diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt new file mode 100644 index 00000000..09a0c1cb --- /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-guides.rst b/docs/user-guides.rst new file mode 100755 index 00000000..2697e643 --- /dev/null +++ b/docs/user-guides.rst @@ -0,0 +1,39 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. ===============LICENSE_START======================================================= +.. Copyright (C) 2019 AT&T Intellectual Property +.. =================================================================================== +.. This documentation file is distributed under the Creative Commons Attribution +.. 4.0 International License (the "License"); you may not use this file except in +.. compliance with the License. You may obtain a copy of the License at +.. +.. http://creativecommons.org/licenses/by/4.0 +.. +.. This file is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ===============LICENSE_END========================================================= + +.. 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 index 00000000..c86cfdf3 --- /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