From c08628279b0949fca2d4038db71055870c100651 Mon Sep 17 00:00:00 2001 From: thmsdt Date: Tue, 24 Jan 2023 16:53:34 +0100 Subject: complete initial setup of new repo Issue-ID: DOC-811 Signed-off-by: thmsdt Change-Id: I9e8acbd7357c2125bc5422ce6c77d793147b521d --- .gitignore | 75 +++++++++++++++++++++++ .gitreview | 5 ++ .readthedocs.yaml | 21 +++++++ LICENSE | 13 ++++ docs/_static/css/ribbon.css | 63 +++++++++++++++++++ docs/_static/favicon.ico | Bin 0 -> 2102 bytes docs/_static/logo_onap_2017.png | Bin 0 -> 12278 bytes docs/conf.py | 56 +++++++++++++++++ docs/images/biohazard.png | Bin 0 -> 179 bytes docs/index.rst | 132 ++++++++++++++++++++++++++++++++++++++++ docs/requirements-docs.txt | 7 +++ docs/spelling_wordlist.txt | 10 +++ docs/tox.ini | 31 ++++++++++ 13 files changed, 413 insertions(+) create mode 100644 .gitignore create mode 100644 .gitreview create mode 100644 .readthedocs.yaml create mode 100644 LICENSE create mode 100644 docs/_static/css/ribbon.css create mode 100755 docs/_static/favicon.ico create mode 100644 docs/_static/logo_onap_2017.png create mode 100644 docs/conf.py create mode 100644 docs/images/biohazard.png create mode 100644 docs/index.rst create mode 100644 docs/requirements-docs.txt create mode 100644 docs/spelling_wordlist.txt create mode 100644 docs/tox.ini diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a878a5a --- /dev/null +++ b/.gitignore @@ -0,0 +1,75 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +_build +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# aspell +*.new +*.bak + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +.hypothesis/ + +# Django: +*.log +local_settings.py + +# Flask: +instance/ +.webassets-cache + +# Scrapy: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# pyenv +.python-version + +#MacOs +.DS_Store +.vscode/ diff --git a/.gitreview b/.gitreview new file mode 100644 index 0000000..b72d7a4 --- /dev/null +++ b/.gitreview @@ -0,0 +1,5 @@ +[gerrit] +host=gerrit.onap.org +port=29418 +project=doc/doc-best-practice +defaultbranch=master diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..7f740b7 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,21 @@ +--- +# .readthedocs.yml +# # Read the Docs configuration file +# # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +# # Required +# +version: 2 + +build: + image: latest + +python: + version: 3.7 + install: + - requirements: docs/requirements-docs.txt + +submodules: + include: all + +sphinx: + configuration: docs/conf.py diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..98bd56d --- /dev/null +++ b/LICENSE @@ -0,0 +1,13 @@ +Copyright (c) 2017 Open Network Automation Platform and contributors + + 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. diff --git a/docs/_static/css/ribbon.css b/docs/_static/css/ribbon.css new file mode 100644 index 0000000..afb9480 --- /dev/null +++ b/docs/_static/css/ribbon.css @@ -0,0 +1,63 @@ +.ribbon { + z-index: 1000; + background-color: #a00; + overflow: hidden; + white-space: nowrap; + position: fixed; + top: 25px; + right: -50px; + -webkit-transform: rotate(45deg); + -moz-transform: rotate(45deg); + -ms-transform: rotate(45deg); + -o-transform: rotate(45deg); + transform: rotate(45deg); + -webkit-box-shadow: 0 0 10px #888; + -moz-box-shadow: 0 0 10px #888; + box-shadow: 0 0 10px #888; + +} + +.ribbon a { + border: 1px solid #faa; + color: #fff; + display: block; + font: bold 81.25% 'Helvetica Neue', Helvetica, Arial, sans-serif; + margin: 1px 0; + padding: 10px 50px; + text-align: center; + text-decoration: none; + text-shadow: 0 0 5px #444; + transition: 0.5s; +} + +.ribbon a:hover { + background: #c11; + color: #fff; +} + + +/* override table width restrictions */ +@media screen and (min-width: 767px) { + + .wy-table-responsive table td, .wy-table-responsive table th { + /* !important prevents the common CSS stylesheets from overriding + this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-table-responsive { + overflow: visible !important; + } +} + +@media screen and (max-width: 767px) { + .wy-table-responsive table td { + white-space: nowrap; + } +} + +/* fix width of the screen */ + +.wy-nav-content { + max-width: 800px; +} diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100755 index 0000000..cb712eb Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/_static/logo_onap_2017.png b/docs/_static/logo_onap_2017.png new file mode 100644 index 0000000..5d064f4 Binary files /dev/null and b/docs/_static/logo_onap_2017.png differ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..a9c42b6 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,56 @@ +project = "onap" +release = "master" +version = "master" + +author = "Open Network Automation Platform" +# yamllint disable-line rule:line-length +copyright = "ONAP. Licensed under Creative Commons Attribution 4.0 International License" + +pygments_style = "sphinx" +html_theme = "sphinx_rtd_theme" +html_theme_options = { + "style_nav_header_background": "white", + "sticky_navigation": "False" } +html_logo = "_static/logo_onap_2017.png" +html_favicon = "_static/favicon.ico" +html_static_path = ["_static"] +html_show_sphinx = False + +extensions = [ + 'sphinx.ext.intersphinx', + 'sphinx.ext.graphviz', + 'sphinxcontrib.blockdiag', + 'sphinxcontrib.seqdiag', + 'sphinxcontrib.swaggerdoc', + 'sphinxcontrib.plantuml' +] + +# +# Map to 'latest' if this file is used in 'latest' (master) 'doc' branch. +# Change to {releasename} after you have created the new 'doc' branch. +# + +branch = 'latest' + +intersphinx_mapping = {} +doc_url = 'https://docs.onap.org/projects' +master_doc = 'index' + +exclude_patterns = ['.tox'] + +spelling_word_list_filename='spelling_wordlist.txt' +spelling_lang = "en_GB" + +# +# Example: +# intersphinx_mapping['onap-aai-aai-common'] = ('{}/onap-aai-aai-common/en/%s'.format(doc_url) % branch, None) +# + +html_last_updated_fmt = '%d-%b-%y %H:%M' + +def setup(app): + app.add_css_file("css/ribbon.css") + +linkcheck_ignore = [ + r'http://localhost:\d+/' +] diff --git a/docs/images/biohazard.png b/docs/images/biohazard.png new file mode 100644 index 0000000..ae4629d Binary files /dev/null and b/docs/images/biohazard.png differ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..c7685a5 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,132 @@ +===================================================== + The reStructuredText_ Cheat Sheet: Syntax Reminders +===================================================== +:Info: See for introductory docs. +:Author: David Goodger +:Date: $Date: 2021-03-05 22:14:40 +0100 (Fr, 05. Mär 2021) $ +:Revision: $Revision: 8631 $ +:Description: This is a "docinfo block", or bibliographic field list + +.. NOTE:: If you are reading this as HTML, please read + ``_ instead to see the input syntax examples! + +Section Structure +================= +Section titles are underlined or overlined & underlined. + +Body Elements +============= +Grid table: + ++--------------------------------+-----------------------------------+ +| Paragraphs are flush-left, | Literal block, preceded by "::":: | +| separated by blank lines. | | +| | Indented | +| Block quotes are indented. | | ++--------------------------------+ or:: | +| >>> print 'Doctest block' | | +| Doctest block | > Quoted | ++--------------------------------+-----------------------------------+ +| | Line blocks preserve line breaks & indents. [new in 0.3.6] | +| | Useful for addresses, verse, and adornment-free lists; long | +| lines can be wrapped with continuation lines. | ++--------------------------------------------------------------------+ + +Simple tables: + +================ ============================================================ +List Type Examples (syntax in the `text source `_) +================ ============================================================ +Bullet list * items begin with "-", "+", or "*" +Enumerated list 1. items use any variation of "1.", "A)", and "(i)" + #. also auto-enumerated +Definition list Term is flush-left : optional classifier + Definition is indented, no blank line between +Field list :field name: field body +Option list -o at least 2 spaces between option & description +================ ============================================================ + +================ ============================================================ +Explicit Markup Examples (visible in the `text source`_) +================ ============================================================ +Footnote .. [1] Manually numbered or [#] auto-numbered + (even [#labelled]) or [*] auto-symbol +Citation .. [CIT2002] A citation. +Hyperlink Target .. _reStructuredText: http://docutils.sf.net/rst.html + .. _indirect target: reStructuredText_ + .. _internal target: +Anonymous Target __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html +Directive ("::") .. image:: images/biohazard.png +Substitution Def .. |substitution| replace:: like an inline directive +Comment .. is anything else +Empty Comment (".." on a line by itself, with blank lines before & after, + used to separate indentation contexts) +================ ============================================================ + +Inline Markup +============= +*emphasis*; **strong emphasis**; `interpreted text`; `interpreted text +with role`:emphasis:; ``inline literal text``; standalone hyperlink, +http://docutils.sourceforge.net; named reference, reStructuredText_; +`anonymous reference`__; footnote reference, [1]_; citation reference, +[CIT2002]_; |substitution|; _`inline internal target`. + +Directive Quick Reference +========================= +See for full info. + +================ ============================================================ +Directive Name Description (Docutils version added to, in [brackets]) +================ ============================================================ +attention Specific admonition; also "caution", "danger", + "error", "hint", "important", "note", "tip", "warning" +admonition Generic titled admonition: ``.. admonition:: By The Way`` +image ``.. image:: picture.png``; many options possible +figure Like "image", but with optional caption and legend +topic ``.. topic:: Title``; like a mini section +sidebar ``.. sidebar:: Title``; like a mini parallel document +parsed-literal A literal block with parsed inline markup +rubric ``.. rubric:: Informal Heading`` +epigraph Block quote with class="epigraph" +highlights Block quote with class="highlights" +pull-quote Block quote with class="pull-quote" +compound Compound paragraphs [0.3.6] +container Generic block-level container element [0.3.10] +table Create a titled table [0.3.1] +list-table Create a table from a uniform two-level bullet list [0.3.8] +csv-table Create a table from CSV data [0.3.4] +contents Generate a table of contents +sectnum Automatically number sections, subsections, etc. +header, footer Create document decorations [0.3.8] +target-notes Create an explicit footnote for each external target +math Mathematical notation (input in LaTeX format) +meta Document metadata +include Read an external reST file as if it were inline +raw Non-reST data passed untouched to the Writer +replace Replacement text for substitution definitions +unicode Unicode character code conversion for substitution defs +date Generates today's date; for substitution defs +class Set a "class" attribute on the next element +role Create a custom interpreted text role [0.3.2] +default-role Set the default interpreted text role [0.3.10] +title Set the metadata document title [0.3.10] +================ ============================================================ + +Interpreted Text Role Quick Reference +===================================== +See for full info. + +================ ============================================================ +Role Name Description +================ ============================================================ +emphasis Equivalent to *emphasis* +literal Equivalent to ``literal`` but processes backslash escapes +math Mathematical notation (input in LaTeX format) +PEP Reference to a numbered Python Enhancement Proposal +RFC Reference to a numbered Internet Request For Comments +raw For non-reST data; cannot be used directly (see docs) [0.3.6] +strong Equivalent to **strong** +sub Subscript +sup Superscript +title Title reference (book, etc.); standard default role +================ ============================================================ diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt new file mode 100644 index 0000000..71df2ab --- /dev/null +++ b/docs/requirements-docs.txt @@ -0,0 +1,7 @@ +sphinx>=4.2.0 # BSD +sphinx-rtd-theme>=1.0.0 # MIT +sphinxcontrib-blockdiag # BSD +sphinxcontrib-seqdiag # BSD +sphinxcontrib-swaggerdoc +sphinxcontrib-spelling +sphinxcontrib-plantuml diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt new file mode 100644 index 0000000..35c0468 --- /dev/null +++ b/docs/spelling_wordlist.txt @@ -0,0 +1,10 @@ +Goodger +Mär +docinfo +overlined +Docutils +csv +sectnum +reST +unicode +defs diff --git a/docs/tox.ini b/docs/tox.ini new file mode 100644 index 0000000..b9d7eb4 --- /dev/null +++ b/docs/tox.ini @@ -0,0 +1,31 @@ +[tox] +minversion = 1.6 +envlist = docs,docs-linkcheck,docs-spellcheck +skipsdist = true + +[testenv:docs] +basepython = python3.8 +deps = + -r{toxinidir}/requirements-docs.txt + -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt + -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master +commands = + sphinx-build -W -q -b html -n -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/html + +[testenv:docs-linkcheck] +basepython = python3.8 +deps = + -r{toxinidir}/requirements-docs.txt + -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt + -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master +commands = + sphinx-build -W -q -b linkcheck -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/linkcheck + +[testenv:docs-spellcheck] +basepython = python3.8 +deps = + -r{toxinidir}/requirements-docs.txt + -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt + -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master +commands = + sphinx-build -W -q -b spelling -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/spellcheck -- cgit 1.2.3-korg