From: weichen Date: Mon, 4 Nov 2019 15:13:57 +0000 (-0500) Subject: add doc config files and update doc-templates X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=300706ea7b62df16a8ea71c8cf849208fcc1307f;p=doc.git add doc config files and update doc-templates Signed-off-by: weichen 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 Binary files /dev/null and b/doc-templates/_static/logo.png 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-docs 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 96% 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 Binary files /dev/null and b/doc-templates/favicon.ico 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 , it's dependencies and required system resources. -.. contents:: - :depth: 3 - :local: Version history ---------------------- +--------------------+--------------------+--------------------+--------------------+ | **Date** | **Ver.** | **Author** | **Comment** | @@ -35,7 +33,8 @@ Version history Introduction -============ +------------ + .. .: @@ -46,7 +45,7 @@ The audience of this document is assumed to have good knowledge in RAN network n Preface -======= +------- .. : @@ -57,7 +56,7 @@ Before starting the installation of , some planning must preceed. Hardware requirements -===================== +--------------------- .. : @@ -89,10 +88,8 @@ Following minimum hardware requirements must be met for installation of : @@ -102,12 +99,9 @@ This section describes the installation of the installation on th References -========== +---------- .. -: -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 of . .. contents:: @@ -28,7 +32,7 @@ Version history Summary -======= +------- @@ -36,13 +40,13 @@ Summary Release Data -============ +------------ : +--------------------------------------+--------------------------------------+ -| **Project** | E.g. Arno/genesis/fuel@opnfv | +| **Project** | E.g. project | | | | +--------------------------------------+--------------------------------------+ | **Repo/commit-ID** | E.g. genesis/adf634a0d4..... | @@ -54,7 +58,7 @@ Release Data | **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 @@ Release Data Feature additions -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^ : @@ -83,7 +87,7 @@ Feature additions +--------------------------------------+--------------------------------------+ Bug corrections -~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^ **JIRA TICKETS:** @@ -101,34 +105,34 @@ Bug corrections +--------------------------------------+--------------------------------------+ Deliverables ----------------- +^^^^^^^^^^^^ Software deliverables -^^^^^^^^^^^^^^^^^^^^^^^ ++++++++++++++++++++++ -: + Documentation deliverables -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +++++++++++++++++++++++++++ -: + Known Limitations, Issues and Workarounds -========================================= +----------------------------------------- System Limitations -^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^ Known issues -^^^^^^^^^^^^^^^ +^^^^^^^^^^^^ : @@ -149,7 +153,7 @@ Known issues +--------------------------------------+--------------------------------------+ Workarounds -^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^ @@ -157,7 +161,7 @@ Workarounds References -========== +---------- 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) + +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.