diff options
| author |   Rich Bennett <rb2745@att.com> | 2017-10-10 07:39:06 -0400 |
|---|---|---|
| committer | Rich Bennett <rb2745@att.com> | 2017-10-10 07:44:50 -0400 |
| commit | 7134cba7aa509a5ee7628244c52979e02807d252 (patch) | |
| tree | 01d4f737b6c3b27515bd8f116850f838b7cc6830 | |
| parent | 2f3328219820a4be426981282350034b21e2e3f3 (diff) | |
Improve templates and add references in guides
See description of DOC-101
Added multipple conf.py files to test themes and multiple versions
Created initial structure for references in developer architecture guide and release notes
Change-Id: I7affcd1cb0258bef7cebe357a938080abe419693
Issue-ID: DOC-101
Signed-off-by: Rich Bennett <rb2745@att.com>
55 files changed, 2921 insertions, 308 deletions
diff --git a/.gitmodules b/.gitmodules index c2d7a96cf..c0afb1c03 100644 --- a/.gitmodules +++ b/.gitmodules @@ -303,11 +303,6 @@ url = ../sdc/sdc-workflow-designer branch = . ignore = dirty -[submodule "docs/submodules/sdc/sdc_common.git"] - path = docs/submodules/sdc/sdc_common.git - url = ../sdc/sdc_common - branch = . - ignore = dirty [submodule "docs/submodules/vid.git"] path = docs/submodules/vid.git url = ../vid diff --git a/docs/conf2.py b/docs/conf2.py new file mode 100644 index 000000000..7baa04038 --- /dev/null +++ b/docs/conf2.py @@ -0,0 +1,377 @@ +# -*- coding: utf-8 -*- +# +# ONAP documentation build configuration file, created by +# sphinx-quickstart on Wed Jul 19 16:25:31 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import shlex + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +needs_sphinx = '1.5.3' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.graphviz', + 'sphinx.ext.todo', + 'sphinx.ext.imgmath', + 'sphinx.ext.viewcode', + 'sphinxcontrib.blockdiag', + 'sphinxcontrib.seqdiag', + 'sphinx.ext.ifconfig', + 'sphinx.ext.todo', + 'sphinxcontrib.httpdomain', + 'sphinxcontrib.plantuml', + 'sphinxcontrib.swaggerdoc' +] + +# Font path for seqdiag +seqdiag_fontpath= '/usr/share/fonts/truetype/dejavu/DejaVuSansCondensed.ttf' + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'ONAP' +copyright = u'2017, ONAP Contributors' +author = u'ONAP Contributors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = 'pre-release alpha' +# The full version, including alpha/beta/rc tags. +release = 'Amsterdam 0.1 alpha' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [ + '_build' + ] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = '_static/logo_onap_2017.png' + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +html_favicon = '_static/favicon.ico' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'ONAPdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'ONAP.tex', u'ONAP Documentation', + u'ONAP Contributors', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'onap', u'ONAP Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'ONAP', u'ONAP Documentation', + author, 'ONAP', 'Open Network Automation Platform', + 'Platform'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The basename for the epub file. It defaults to the project name. +#epub_basename = project + +# The HTML theme for the epub output. Since the default themes are not optimized +# for small screen space, using the same theme for HTML and epub output is +# usually not wise. This defaults to 'epub', a theme designed to save visual +# space. +#epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or 'en' if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +#epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +#epub_tocscope = 'default' + +# Fix unsupported image types using the Pillow. +#epub_fix_images = False + +# Scale large images. +#epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#epub_show_urls = 'inline' + +# If false, no index is generated. +#epub_use_index = True + +# Patterns to ignore in linkcheck builder +linkcheck_ignore = [r'http://localhost:\d+/'] + diff --git a/docs/conftr.py b/docs/conftr.py new file mode 100644 index 000000000..34956e8c1 --- /dev/null +++ b/docs/conftr.py @@ -0,0 +1,380 @@ +# -*- coding: utf-8 -*- +# +# ONAP documentation build configuration file, created by +# sphinx-quickstart on Wed Jul 19 16:25:31 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import shlex +import sphinx_rtd_theme + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +needs_sphinx = '1.5.3' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.graphviz', + 'sphinx.ext.todo', + 'sphinx.ext.imgmath', + 'sphinx.ext.viewcode', + 'sphinxcontrib.blockdiag', + 'sphinxcontrib.seqdiag', + 'sphinx.ext.ifconfig', + 'sphinx.ext.todo', + 'sphinxcontrib.httpdomain', + 'sphinxcontrib.plantuml', + 'sphinxcontrib.swaggerdoc' +] + +# Font path for seqdiag +seqdiag_fontpath= '/usr/share/fonts/truetype/dejavu/DejaVuSansCondensed.ttf' + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'ONAP' +copyright = u'2017, ONAP Contributors' +author = u'ONAP Contributors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = 'pre-release alpha' +# The full version, including alpha/beta/rc tags. +release = 'Amsterdam 0.1 alpha' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [ + '_build' + ] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +#html_theme = 'classic' +html_theme = 'sphinx_rtd_theme' +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = '_static/logo_onap_2017.png' + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +html_favicon = '_static/favicon.ico' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'ONAPdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'ONAP.tex', u'ONAP Documentation', + u'ONAP Contributors', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'onap', u'ONAP Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'ONAP', u'ONAP Documentation', + author, 'ONAP', 'Open Network Automation Platform', + 'Platform'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The basename for the epub file. It defaults to the project name. +#epub_basename = project + +# The HTML theme for the epub output. Since the default themes are not optimized +# for small screen space, using the same theme for HTML and epub output is +# usually not wise. This defaults to 'epub', a theme designed to save visual +# space. +#epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or 'en' if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +#epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +#epub_tocscope = 'default' + +# Fix unsupported image types using the Pillow. +#epub_fix_images = False + +# Scale large images. +#epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#epub_show_urls = 'inline' + +# If false, no index is generated. +#epub_use_index = True + +# Patterns to ignore in linkcheck builder +linkcheck_ignore = [r'http://localhost:\d+/'] + diff --git a/docs/guides/onap-developer/architecture/index.rst b/docs/guides/onap-developer/architecture/index.rst index 4c7aad10f..f7cae3858 100644 --- a/docs/guides/onap-developer/architecture/index.rst +++ b/docs/guides/onap-developer/architecture/index.rst @@ -3,15 +3,122 @@ Architecture ============ +.. note:: + Some high level groupings are introduced below with references to project/repo index. + As more information is provided by each project these references will shift lower to + to include only certain sections from each project. For example, the project architecture section. + +Models +------ + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + ../../../submodules/modeling/modelspec.git/docs/index + +User Interfaces +--------------- + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + ../../../submodules/clamp.git/docs/index + ../../../submodules/cli.git/docs/index + ../../../submodules/sdc/jtosca.git/docs/index + ../../../submodules/sdc/sdc-distribution-client.git/docs/index + ../../../submodules/sdc/sdc-docker-base.git/docs/index + ../../../submodules/sdc/sdc-titan-cassandra.git/docs/index + ../../../submodules/sdc/sdc-tosca.git/docs/index + ../../../submodules/sdc/sdc-workflow-designer.git/docs/index + ../../../submodules/sdc.git/docs/index + ../../../submodules/usecase-ui.git/docs/index + ../../../submodules/vid/asdcclient.git/docs/index + ../../../submodules/vid.git/docs/index + Platform Components ------------------- +.. toctree:: + :maxdepth: 1 + :titlesonly: + + ../../../submodules/appc/deployment.git/docs/index + ../../../submodules/appc.git/docs/index + ../../../submodules/dcaegen2.git/docs/index + ../../../submodules/holmes/engine-management.git/docs/index + ../../../submodules/holmes/rule-management.git/docs/index + ../../../submodules/policy/engine.git/docs/index + ../../../submodules/sdnc/adaptors.git/docs/index + ../../../submodules/sdnc/architecture.git/docs/index + ../../../submodules/sdnc/core.git/docs/index + ../../../submodules/sdnc/features.git/docs/index + ../../../submodules/sdnc/northbound.git/docs/index + ../../../submodules/sdnc/oam.git/docs/index + ../../../submodules/sdnc/parent.git/docs/index + ../../../submodules/sdnc/plugins.git/docs/index + ../../../submodules/so/libs.git/docs/index + ../../../submodules/so.git/docs/index + ../../../submodules/vfc/lcm.git/docs/index + ../../../submodules/vfc/nfvo/lcm.git/docs/index + +Platform Common Services +------------------------ + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + ../../../submodules/aaf/authz.git/docs/index + ../../../submodules/aai/aai-common.git/docs/index + ../../../submodules/aai/data-router.git/docs/index + ../../../submodules/aai/esr-gui.git/docs/index + ../../../submodules/aai/esr-server.git/docs/index + ../../../submodules/aai/resources.git/docs/index + ../../../submodules/aai/search-data-service.git/docs/index + ../../../submodules/aai/sparky-be.git/docs/index + ../../../submodules/aai/sparky-fe.git/docs/index + ../../../submodules/aai/traversal.git/docs/index + ../../../submodules/dmaap/messagerouter/messageservice.git/docs/index + ../../../submodules/msb/apigateway.git/docs/index + ../../../submodules/msb/discovery.git/docs/index + ../../../submodules/msb/java-sdk.git/docs/index + ../../../submodules/msb/swagger-sdk.git/docs/index + ../../../submodules/multicloud/framework.git/docs/index + ../../../submodules/oom.git/docs/index + SDKs ---- -Data Models ------------ +.. toctree:: + :maxdepth: 1 + :titlesonly: + + ../../../submodules/ccsdk/dashboard.git/docs/index + ../../../submodules/ccsdk/distribution.git/docs/index + ../../../submodules/ccsdk/parent.git/docs/index + ../../../submodules/ccsdk/platform/blueprints.git/docs/index + ../../../submodules/ccsdk/platform/nbapi.git/docs/index + ../../../submodules/ccsdk/platform/plugins.git/docs/index + ../../../submodules/ccsdk/sli/adaptors.git/docs/index + ../../../submodules/ccsdk/sli/core.git/docs/index + ../../../submodules/ccsdk/sli/northbound.git/docs/index + ../../../submodules/ccsdk/sli/plugins.git/docs/index + ../../../submodules/ccsdk/storage/esaas.git/docs/index + ../../../submodules/ccsdk/storage/pgaas.git/docs/index + ../../../submodules/ccsdk/utils.git/docs/index + ../../../submodules/portal.git/docs/index + ../../../submodules/vnfsdk/model.git/docs/index + +Other +----- -Dependencies ------------- +.. toctree:: + :maxdepth: 1 + :titlesonly: + ../../../submodules/integration.git/docs/index + ../../../submodules/optf/has.git/docs/index + ../../../submodules/vnfrqts/guidelines.git/docs/index + ../../../submodules/vnfrqts/requirements.git/docs/index diff --git a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst index 6d970123f..aa2def9d7 100644 --- a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst +++ b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst @@ -202,19 +202,48 @@ Creating Restructured Text Templates and Examples ---------------------- -Some templates are available that capture the kinds of information -useful for different types of projects and provide simple examples of -restructured text. -You can: browse the templates below; show source to look at the Restructured -Text and Sphinx directives used; and then copy the source either from a browser window +Templates are available that capture the kinds of information +useful for different types of projects and provide some examples of +restructured text. We organize templates in the following way to: help authors +understand relationships between documents; keep the user audience context in mind when writing; +and tailor sections for different kinds of projects. + +**Sections** Represent a certain type of content. A section is **provided** in a repository, to +to describe something about the characteristics, use, capability, etc. of things in that repository. +A section may also be **referenced** from other sections and in other repositories. +The notes in the beginning of each section template provide +additional detail about what is typically covered and where there may be references to the section. + +**Collections** Are a set of sections that are typically provided for a particular type +of project, repository, guide, reference manual, etc. + +You can: browse the template *collections* and *sections* below; show source to look at the Restructured +Text and Sphinx directives used; copy the source either from a browser window or by downloading the file in raw form from -the `gerrit doc repository <https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree;f=docs/templates;/>`_. +the `gerrit doc repository <https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree;f=docs/templates;/>`_ and +then add them to your repository docs folder and index.rst. + + +Sections +++++++++ .. toctree:: :maxdepth: 1 :glob: - ../../../templates/**/index + ../../../templates/sections/* + + +Collections ++++++++++++ + +.. toctree:: + :maxdepth: 1 + :glob: + + ../../../templates/collections/* + + In addition to these simple templates and examples there are many open source projects (e.g. Open Daylight, Open Stack) diff --git a/docs/release/index.rst b/docs/release/index.rst index eabde3a24..9ff201ddb 100644 --- a/docs/release/index.rst +++ b/docs/release/index.rst @@ -6,7 +6,7 @@ Releases ONAP is developed and released around 6 month cycles. After an initial major release, additional stable point releases may be created. -Major Releases +Named Releases -------------- .. csv-table:: @@ -16,17 +16,16 @@ Major Releases :widths: 15, 10, 10, 15, 10 "Amsterdam", "Under Development", "TBD", "", "" - "R1.0.0 Seed Code", "EOL", "2017-04-XX", "", "" + "OpenECOMP R1.0.0 Seed Code", "EOL", "2017-04-XX", "", "" +Amsterdam Projects +------------------ +The following projects repositories have been approved by the TSC to be part of +the Amsterdam Release and provide detailed release notes at the links below. -.. include:: repolist.rst - +.. include:: releaserepos.rst -Cryptographic Signatures ------------------------- -References ----------- - +.. include:: repolist.rst diff --git a/docs/release/releaserepos.rst b/docs/release/releaserepos.rst new file mode 100644 index 000000000..972d2cb74 --- /dev/null +++ b/docs/release/releaserepos.rst @@ -0,0 +1,76 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Project Specific Release Notes +------------------------------ + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + ../submodules/aaf/authz.git/docs/release-notes.rst + ../submodules/aai/aai-common.git/docs/release-notes.rst + ../submodules/aai/data-router.git/docs/release-notes.rst + ../submodules/aai/esr-gui.git/docs/release-notes.rst + ../submodules/aai/esr-server.git/docs/release-notes.rst + ../submodules/aai/resources.git/docs/release-notes.rst + ../submodules/aai/search-data-service.git/docs/release-notes.rst + ../submodules/aai/sparky-be.git/docs/release-notes.rst + ../submodules/aai/sparky-fe.git/docs/release-notes.rst + ../submodules/aai/traversal.git/docs/release-notes.rst + ../submodules/appc/deployment.git/docs/release-notes.rst + ../submodules/appc.git/docs/release-notes.rst + ../submodules/ccsdk/dashboard.git/docs/release-notes.rst + ../submodules/ccsdk/distribution.git/docs/release-notes.rst + ../submodules/ccsdk/parent.git/docs/release-notes.rst + ../submodules/ccsdk/platform/blueprints.git/docs/release-notes.rst + ../submodules/ccsdk/platform/nbapi.git/docs/release-notes.rst + ../submodules/ccsdk/platform/plugins.git/docs/release-notes.rst + ../submodules/ccsdk/sli/adaptors.git/docs/release-notes.rst + ../submodules/ccsdk/sli/core.git/docs/release-notes.rst + ../submodules/ccsdk/sli/northbound.git/docs/release-notes.rst + ../submodules/ccsdk/sli/plugins.git/docs/release-notes.rst + ../submodules/ccsdk/storage/esaas.git/docs/release-notes.rst + ../submodules/ccsdk/storage/pgaas.git/docs/release-notes.rst + ../submodules/ccsdk/utils.git/docs/release-notes.rst + ../submodules/clamp.git/docs/release-notes.rst + ../submodules/cli.git/docs/release-notes.rst + ../submodules/dcaegen2.git/docs/release-notes.rst + ../submodules/dmaap/messagerouter/messageservice.git/docs/release-notes.rst + ../submodules/holmes/engine-management.git/docs/release-notes.rst + ../submodules/holmes/rule-management.git/docs/release-notes.rst + ../submodules/integration.git/docs/release-notes.rst + ../submodules/modeling/modelspec.git/docs/release-notes.rst + ../submodules/msb/apigateway.git/docs/release-notes.rst + ../submodules/msb/discovery.git/docs/release-notes.rst + ../submodules/msb/java-sdk.git/docs/release-notes.rst + ../submodules/msb/swagger-sdk.git/docs/release-notes.rst + ../submodules/multicloud/framework.git/docs/release-notes.rst + ../submodules/oom.git/docs/release-notes.rst + ../submodules/optf/has.git/docs/release-notes.rst + ../submodules/policy/engine.git/docs/release-notes.rst + ../submodules/portal.git/docs/release-notes.rst + ../submodules/sdc.git/docs/release-notes.rst + ../submodules/sdc/jtosca.git/docs/release-notes.rst + ../submodules/sdc/sdc-distribution-client.git/docs/release-notes.rst + ../submodules/sdc/sdc-docker-base.git/docs/release-notes.rst + ../submodules/sdc/sdc-titan-cassandra.git/docs/release-notes.rst + ../submodules/sdc/sdc-tosca.git/docs/release-notes.rst + ../submodules/sdc/sdc-workflow-designer.git/docs/release-notes.rst + ../submodules/sdnc/adaptors.git/docs/release-notes.rst + ../submodules/sdnc/architecture.git/docs/release-notes.rst + ../submodules/sdnc/core.git/docs/release-notes.rst + ../submodules/sdnc/features.git/docs/release-notes.rst + ../submodules/sdnc/northbound.git/docs/release-notes.rst + ../submodules/sdnc/oam.git/docs/release-notes.rst + ../submodules/sdnc/parent.git/docs/release-notes.rst + ../submodules/sdnc/plugins.git/docs/release-notes.rst + ../submodules/so.git/docs/release-notes.rst + ../submodules/so/libs.git/docs/release-notes.rst + ../submodules/usecase-ui.git/docs/release-notes.rst + ../submodules/vfc/lcm.git/docs/release-notes.rst + ../submodules/vfc/nfvo/lcm.git/docs/release-notes.rst + ../submodules/vid/asdcclient.git/docs/release-notes.rst + ../submodules/vid.git/docs/release-notes.rst + ../submodules/vnfrqts/guidelines.git/docs/release-notes.rst + ../submodules/vnfrqts/requirements.git/docs/release-notes.rst + ../submodules/vnfsdk/model.git/docs/release-notes.rst diff --git a/docs/release/repolist.rst b/docs/release/repolist.rst index 378167b93..d23e56b1d 100644 --- a/docs/release/repolist.rst +++ b/docs/release/repolist.rst @@ -1,12 +1,15 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. -Projects --------- +Projects Providing Documentation +-------------------------------- Documentation organized by the project delivering them. .. note:: - When available these references should be changed to release artifacts. + The list below is the initial reference to project information created + when integrating as a submodule. For the release notes document, + these references will be changed to release notes and artifacts + Other project information will referenced in developer and user guides. .. toctree:: @@ -56,7 +59,6 @@ Documentation organized by the project delivering them. policy/engine <../submodules/policy/engine.git/docs/index> portal <../submodules/portal.git/docs/index> sdc/jtosca <../submodules/sdc/jtosca.git/docs/index> - sdc/sdc_common <../submodules/sdc/sdc_common.git/docs/index> sdc/sdc-distribution-client <../submodules/sdc/sdc-distribution-client.git/docs/index> sdc/sdc-docker-base <../submodules/sdc/sdc-docker-base.git/docs/index> sdc/sdc-titan-cassandra <../submodules/sdc/sdc-titan-cassandra.git/docs/index> diff --git a/docs/requirements.txt b/docs/requirements.txt index 35f9168f4..fa752e6aa 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -4,6 +4,7 @@ doc8 docutils setuptools six +sphinx_rtd_theme sphinxcontrib-httpdomain sphinxcontrib-blockdiag sphinxcontrib-seqdiag diff --git a/docs/submodules/sdc/sdc_common.git b/docs/submodules/sdc/sdc_common.git deleted file mode 160000 -Subproject 37027f7e99b86036b2654bcb427afab39229474 diff --git a/docs/templates/collections/platform-component.rst b/docs/templates/collections/platform-component.rst new file mode 100644 index 000000000..7e7849a04 --- /dev/null +++ b/docs/templates/collections/platform-component.rst @@ -0,0 +1,22 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + +Platform Component Name +======================= + +.. Add or remove sections below as appropriate for the platform component. + +.. toctree:: + :maxdepth: 1 + + ../sections/architecture.rst + ../sections/offeredapis.rst + ../sections/consumedapis.rst + ../sections/delivery.rst + ../sections/logging.rst + ../sections/installation.rst + ../sections/configuration.rst + ../sections/administration.rst + ../sections/humaninterfaces.rst + ../sections/release-notes.rst diff --git a/docs/templates/collections/sdk.rst b/docs/templates/collections/sdk.rst new file mode 100644 index 000000000..f86c33f5c --- /dev/null +++ b/docs/templates/collections/sdk.rst @@ -0,0 +1,17 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +SDK Name +======== + +.. Add or remove sections below as appropriate for the SDK + +.. toctree:: + :maxdepth: 1 + + ../sections/architecture.rst + ../sections/offeredapis.rst + ../sections/deliveries + ../sections/logging.rst + ../sections/build.rst + ../sections/release-notes.rst diff --git a/docs/templates/platform-component/administration.rst b/docs/templates/platform-component/administration.rst deleted file mode 100644 index 1d512cf02..000000000 --- a/docs/templates/platform-component/administration.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - - -Administration --------------- -Describe expected changes and the processes and actions taken for each. - - -Processes -+++++++++ -* Process 1 -* Process 2 - -Actions -+++++++ -* Action X -* Action Y - diff --git a/docs/templates/platform-component/architecture.rst b/docs/templates/platform-component/architecture.rst deleted file mode 100644 index fd46637fd..000000000 --- a/docs/templates/platform-component/architecture.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - - -Architecture ------------- -Describe the architecture and design of the platform component. diff --git a/docs/templates/platform-component/configuration.rst b/docs/templates/platform-component/configuration.rst deleted file mode 100644 index c0c969f85..000000000 --- a/docs/templates/platform-component/configuration.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -Configuration -------------- -Describe configurations how to provide parameters and value - -Basic Setup -+++++++++++ - -You can provide the following in ``basic.conf`` - -``host=ADDRESS`` - The address of the host - -``port=PORT`` - The port used for signaling - - Optional. Default: ``8080`` diff --git a/docs/templates/platform-component/consumedapis.rst b/docs/templates/platform-component/consumedapis.rst deleted file mode 100644 index c4309cdb1..000000000 --- a/docs/templates/platform-component/consumedapis.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -Consumed APIs -============= -References to APIs offered by other components - - diff --git a/docs/templates/platform-component/delivery.rst b/docs/templates/platform-component/delivery.rst deleted file mode 100644 index cfcab0449..000000000 --- a/docs/templates/platform-component/delivery.rst +++ /dev/null @@ -1,31 +0,0 @@ -Delivery --------- -Describe how functions are packaged into run-time components. -For some components a block diagram may be useful. - -.. blockdiag:: - - - blockdiag layers { - orientation = portrait - a -> m; - b -> n; - c -> x; - m -> y; - m -> z; - group l1 { - color = blue; - x; y; z; - } - group l2 { - color = yellow; - m; n; - } - group l3 { - color = orange; - a; b; c; - } - - } - - diff --git a/docs/templates/platform-component/humaninterfaces.rst b/docs/templates/platform-component/humaninterfaces.rst deleted file mode 100644 index 03cc875ed..000000000 --- a/docs/templates/platform-component/humaninterfaces.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -Human Interfaces ----------------- -Provide info on the targeted user, interface types, ports/protocols to access, etc. - -Target Users -++++++++++++ - -Interface Type -++++++++++++++ - -Access -++++++ - - - - diff --git a/docs/templates/platform-component/index.rst b/docs/templates/platform-component/index.rst deleted file mode 100644 index d5db511f1..000000000 --- a/docs/templates/platform-component/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -Platform Component -================== -Provide an overview of the ONAP Platform component capabilities here. -Add or remove sections below as appropriate for the platform component. - -.. toctree:: - :maxdepth: 1 - - architecture.rst - offeredapis.rst - consumedapis.rst - delivery.rst - logging.rst - installation.rst - configuration.rst - administration.rst - humaninterfaces.rst diff --git a/docs/templates/platform-component/installation.rst b/docs/templates/platform-component/installation.rst deleted file mode 100644 index 3238236c4..000000000 --- a/docs/templates/platform-component/installation.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -Installation ------------- -Describe the environment and steps to install. - - -Environment -+++++++++++ - - -Steps -+++++ diff --git a/docs/templates/platform-component/logging.rst b/docs/templates/platform-component/logging.rst deleted file mode 100644 index 8d480e283..000000000 --- a/docs/templates/platform-component/logging.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -Logging & Diagnostic Information --------------------------------- -Description of how to interact with and diagnose problems with the components -as delivered. - -Where to Access Information -+++++++++++++++++++++++++++ - - -Error / Warning Messages -++++++++++++++++++++++++ diff --git a/docs/templates/platform-component/offeredapis.rst b/docs/templates/platform-component/offeredapis.rst deleted file mode 100644 index 55e58bd9b..000000000 --- a/docs/templates/platform-component/offeredapis.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - - -Offered APIs -============ -List APIs offered. One or more of the following examples may be appropriate. - -Example Swagger Displayed with swaggerv2doc directive ------------------------------------------------------ - -.. swaggerv2doc:: https://gerrit.onap.org/r/gitweb?p=vfc/nfvo/lcm.git;a=blob_plain;f=lcm/swagger/vfc.nslcm.swagger.json - - -Example documenting a REST interface with Sphinx httpdomain directive ---------------------------------------------------------------------- - -.. http:get:: path - - For more information see `<https://pythonhosted.org/sphinxcontrib-httpdomain>`_ - - -Word Document Converted to RST using Pandocs --------------------------------------------- - -.. toctree:: - :maxdepth: 1 - - ../../submodules/appc.git/docs/APPC API Guide/APPC API Guide diff --git a/docs/templates/release-notes/bug-fixes.rst b/docs/templates/release-notes/bug-fixes.rst deleted file mode 100644 index ee4ff9faf..000000000 --- a/docs/templates/release-notes/bug-fixes.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -Bug Fixes ---------- - diff --git a/docs/templates/release-notes/deprecation-notes.rst b/docs/templates/release-notes/deprecation-notes.rst deleted file mode 100644 index e954e8764..000000000 --- a/docs/templates/release-notes/deprecation-notes.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -Deprecation Notes ------------------ - diff --git a/docs/templates/release-notes/index.rst b/docs/templates/release-notes/index.rst deleted file mode 100644 index adc76f935..000000000 --- a/docs/templates/release-notes/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -Release Notes -============= - -.. toctree:: - :maxdepth: 2 - - new-features.rst - bug-fixes.rst - known-issues.rst - security-issues.rst - upgrade-notes.rst - deprecation-notes.rst - other.rst diff --git a/docs/templates/release-notes/known-issues.rst b/docs/templates/release-notes/known-issues.rst deleted file mode 100644 index 01c93d124..000000000 --- a/docs/templates/release-notes/known-issues.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -Known Issues ------------- - diff --git a/docs/templates/release-notes/new-features.rst b/docs/templates/release-notes/new-features.rst deleted file mode 100644 index ab86bb949..000000000 --- a/docs/templates/release-notes/new-features.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -New Features ------------- - diff --git a/docs/templates/release-notes/other.rst b/docs/templates/release-notes/other.rst deleted file mode 100644 index 2ce683b5b..000000000 --- a/docs/templates/release-notes/other.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -Other ------ - diff --git a/docs/templates/release-notes/security-issues.rst b/docs/templates/release-notes/security-issues.rst deleted file mode 100644 index 96e1fe95e..000000000 --- a/docs/templates/release-notes/security-issues.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -Security Issues ---------------- - diff --git a/docs/templates/release-notes/upgrade-notes.rst b/docs/templates/release-notes/upgrade-notes.rst deleted file mode 100644 index f31c74a69..000000000 --- a/docs/templates/release-notes/upgrade-notes.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -Upgrade Notes -------------- - diff --git a/docs/templates/sdk/architecture.rst b/docs/templates/sdk/architecture.rst deleted file mode 100644 index 4dede8e5a..000000000 --- a/docs/templates/sdk/architecture.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - - -Architecture ------------- -Describe the architecture and design of the SDK. diff --git a/docs/templates/sdk/build.rst b/docs/templates/sdk/build.rst deleted file mode 100644 index e8af74eb9..000000000 --- a/docs/templates/sdk/build.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - - -Building a Component using the SDK -================================== diff --git a/docs/templates/sdk/index.rst b/docs/templates/sdk/index.rst deleted file mode 100644 index 0cc744197..000000000 --- a/docs/templates/sdk/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -Software Development Kit -======================== -Provide an overview of SDK capabilities here. - -.. toctree:: - :maxdepth: 1 - - architecture.rst - offeredapis.rst - libraries.rst - logging.rst - build.rst diff --git a/docs/templates/sdk/libraries.rst b/docs/templates/sdk/libraries.rst deleted file mode 100644 index 618c04428..000000000 --- a/docs/templates/sdk/libraries.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -Libraries ---------- -Provide library package and Nexus groupID names - diff --git a/docs/templates/sdk/logging.rst b/docs/templates/sdk/logging.rst deleted file mode 100644 index 4b272ad76..000000000 --- a/docs/templates/sdk/logging.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -Logging & Diagnostic Information --------------------------------- - -Error / Warning Messages -++++++++++++++++++++++++ diff --git a/docs/templates/sdk/offeredapis.rst b/docs/templates/sdk/offeredapis.rst deleted file mode 100644 index 4e72427d9..000000000 --- a/docs/templates/sdk/offeredapis.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - - -Offered APIs ------------- diff --git a/docs/templates/sections/adminstration.rst b/docs/templates/sections/adminstration.rst new file mode 100644 index 000000000..94a740718 --- /dev/null +++ b/docs/templates/sections/adminstration.rst @@ -0,0 +1,24 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Administration +============== + + +.. note:: + * This section is used to describe a software component from the perspective of on-going + operation including regular processes and actions that are taken to configure and manage + the component. + + * This section is typically: provided for platform-component or applications; and + referenced in user guides + + * This note must be removed after content has been added. + + +Processes +--------- + + +Actions +------- diff --git a/docs/templates/sections/apiexample/dcaecdap.rst b/docs/templates/sections/apiexample/dcaecdap.rst new file mode 100644 index 000000000..bc7f7bf35 --- /dev/null +++ b/docs/templates/sections/apiexample/dcaecdap.rst @@ -0,0 +1,757 @@ +=============== +CDAP Broker API +=============== + +:Date: 2017-10-09 + +.. contents:: + :depth: 3 +.. + +Overview +======== + +Version information +------------------- + +*Version* : 4.0.10 + +Paths +===== + +GET / +----- + +Description +~~~~~~~~~~~ + +shows some information about this service + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | successful response | `info <#_info> | +| | | `__ | ++---------+----------------------------------------------------+----------------+ + +GET /application +---------------- + +Description +~~~~~~~~~~~ + +get all applications registered with this broker + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | successful response | < | +| | | `appname <#_ap | +| | | pname>`__ | +| | | > array | ++---------+----------------------------------------------------+----------------+ + +PUT /application\*/{appname} +---------------------------- + +Description +~~~~~~~~~~~ + +(This is a hacky way of supporting "oneOf" because Swagger does not +support oneOf https://github.com/OAI/OpenAPI-Specification/issues/333. +This is the same endpoint as PUT /application/appname, except the PUT +body is different.) + +Register a hydrator app for service and configuration discovery. This +will light up a metrics and health endpoint for this app. ``appname`` is +assumed to also be the key in consul. + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **appname | Name of the application. | string (text) | +| * | ** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Body* | | **putbody | required put body | `hydratorappput | +| * | ** | | <#_hydratorapppu | +| | | *required | | t>`__ | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | Successful response | `Application < | +| | | #_application> | +| | | `__ | ++---------+----------------------------------------------------+----------------+ +| **400** | put was performed but the appname was already | No Content | +| | registered with the broker, or Invalid PUT body | | ++---------+----------------------------------------------------+----------------+ + +Consumes +~~~~~~~~ + +- ``application/json`` + +Produces +~~~~~~~~ + +- ``application/json`` + +POST /application/delete +------------------------ + +Description +~~~~~~~~~~~ + +endpoint to delete multiple applications at once. Returns an array of +status codes, where statuscode[i] = response returned from +DELETE(application/i) + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Body* | | **postbod | required post body | `multideleteput | +| * | y** | | <#_multideletepu | +| | | *required | | t>`__ | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | successful response | < | +| | | `returncode <# | +| | | _returncode>`_ | +| | | _ | +| | | > array | ++---------+----------------------------------------------------+----------------+ + +GET /application/{appname} +-------------------------- + +Description +~~~~~~~~~~~ + +Returns the representation of the application resource, including the +links for healthcheck and metrics. + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **appname | Name of the application. | string (text) | +| * | ** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | Successful response | `Application < | +| | | #_application> | +| | | `__ | ++---------+----------------------------------------------------+----------------+ +| **404** | no app with name 'appname' registered with this | No Content | +| | broker. | | ++---------+----------------------------------------------------+----------------+ + +PUT /application/{appname} +-------------------------- + +Description +~~~~~~~~~~~ + +Register an app for service and configuration discovery. This will light +up a metrics and health endpoint for this app. ``appname`` is assumed to +also be the key in consul. + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **appname | Name of the application. | string (text) | +| * | ** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Body* | | **putbody | required put body | `appput <#_apppu | +| * | ** | | t>`__ | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | Successful response | `Application < | +| | | #_application> | +| | | `__ | ++---------+----------------------------------------------------+----------------+ +| **400** | put was performed but the appname was already | No Content | +| | registered with the broker, or Invalid PUT body | | ++---------+----------------------------------------------------+----------------+ + +Consumes +~~~~~~~~ + +- ``application/json`` + +Produces +~~~~~~~~ + +- ``application/json`` + +DELETE /application/{appname} +----------------------------- + +Description +~~~~~~~~~~~ + +Remove an app for service and configuration discovery. This will remove +the metrics and health endpoints for this app. + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **appname | Name of the application. | string (text) | +| * | ** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | Successful response | No Content | ++---------+----------------------------------------------------+----------------+ +| **404** | no app with name 'appname' registered with this | No Content | +| | broker. | | ++---------+----------------------------------------------------+----------------+ + +GET /application/{appname}/healthcheck +-------------------------------------- + +Description +~~~~~~~~~~~ + +Perform a healthcheck on the running app appname. + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **appname | Name of the application to get the | string (test) | +| * | ** | healthcheck for. | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | Successful response, healthcheck pass | No Content | ++---------+----------------------------------------------------+----------------+ +| **404** | no app with name 'appname' registered with this | No Content | +| | broker, or the healthcheck has failed (though I | | +| | would like to disambiguiate from the first case, | | +| | CDAP returns a 404 for this). | | ++---------+----------------------------------------------------+----------------+ + +GET /application/{appname}/metrics +---------------------------------- + +Description +~~~~~~~~~~~ + +Get live (real-time) app specific metrics for the running app appname. +Metrics are customized per each app by the component developer + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **appname | Name of the application to get | string (test) | +| * | ** | metrics for. | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | Successful response | `MetricsObject | +| | | <#_metricsobj | +| | | ect>`__ | ++---------+----------------------------------------------------+----------------+ +| **404** | no app with name 'appname' registered with this | No Content | +| | broker. | | ++---------+----------------------------------------------------+----------------+ + +PUT /application/{appname}/reconfigure +-------------------------------------- + +Description +~~~~~~~~~~~ + +Reconfigures the application. + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **appname | Name of the application. | string (text) | +| * | ** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Body* | | **putbody | required put body | `reconfigput <#_ | +| * | ** | | reconfigput>`__ | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | Successful response | No Content | ++---------+----------------------------------------------------+----------------+ +| **400** | Bad request. Can happen with 1) {appname} is not | No Content | +| | registered with the broker, 2) the required PUT | | +| | body is wrong, or 3) the smart interface was | | +| | chosen and none of the config keys match anything | | +| | in app\_config or app\_preferences | | ++---------+----------------------------------------------------+----------------+ + +Definitions +=========== + +Application +----------- + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **appname | application name | string | +| ** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **connect | input URL that you can POST data into (URL | string | +| ionurl** | of the CDAP stream) | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **healthc | fully qualified url to perform healthcheck | string | +| heckurl** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **metrics | fully qualified url to get metrics from | string | +| url** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **service | a list of HTTP services exposed by this | < | +| endpoints** | CDAP application | `service\_method | +| | *optional | | <#_service_meth | +| * | | od>`__ | +| | | > array | ++-------------+---------------------------------------------+------------------+ +| | **url** | fully qualified url of the resource | string | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +MetricsObject +------------- + +key,value object where the key is 'appmetrics' and the value is an app +dependent json and specified by the component developer + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **appmetrics** | object | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +appname +------- + +an application name + +*Type* : string + +appput +------ + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **app\_co | the application config JSON | object | +| nfig** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **app\_pr | the application preferences JSON | object | +| eferences** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **artifac | the name of the CDAP artifact to be added | string | +| t\_name** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **cdap\_a | denotes whether this is a program-flowlet | enum | +| pplication\ | style application or a hydrator pipeline. | (program-flowlet | +| _type** | For program-flowlet style apps, this value | ) | +| | *optional | must be "program-flowlet" | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **jar\_ur | the URL that the JAR you’re deploying | string | +| l** | resides | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **namespa | the cdap namespace this is deployed into | string | +| ce** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **program | | < | +| \_preferenc | | `programpref <#_ | +| es** | | programpref>`__ | +| | *optional | | > array | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **program | | < | +| s** | | `programs <#_pro | +| | *optional | | grams>`__ | +| * | | > array | ++-------------+---------------------------------------------+------------------+ +| | **service | | < | +| s** | | `service\_endpoi | +| | *optional | | nt <#_service_en | +| * | | dpoint>`__ | +| | | > array | ++-------------+---------------------------------------------+------------------+ +| | **streamn | name of the CDAP stream to ingest data into | string | +| ame** | this app. Should come from the developer | | +| | *optional | and Tosca model. | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +hydratorappput +-------------- + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **cdap\_a | denotes whether this is a program-flowlet | enum | +| pplication\ | style application or a hydrator pipeline. | (hydrator-pipeli | +| _type** | For hydrator, this value must be | ne) | +| | *required | "hydrator-pipeline" | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **depende | represents a list of dependencies to be | < | +| ncies** | loaded for this pipeline. Not required. | `hydratordep <#_ | +| | *optional | | hydratordep>`__ | +| * | | > array | ++-------------+---------------------------------------------+------------------+ +| | **namespa | the cdap namespace this is deployed into | string | +| ce** | | | +| | *required | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **pipelin | the URL of the config.json for this | string | +| e\_config\_ | pipeline | | +| json\_url** | | | +| | *required | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **streamn | name of the CDAP stream to ingest data into | string | +| ame** | this app. Should come from the developer | | +| | *required | and Tosca model. | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +hydratordep +----------- + +represents a hydrator pipeline dependency. An equivelent to the +following CURLs are formed with the below four params shown in CAPS +"curl -v -w"\\n" -X POST +http://cdapurl:11015/v3/namespaces/setelsewhere/artifacts/ARTIFACT_NAME +-H "Artifact-Extends:ARTIFACT\_EXTENDS\_HEADER" -H +“Artifact-Version:ARTIFACT\_VERSION\_HEADER” –data-binary @(DOWNLOADED +FROM ARTIFACT\_URL)","curl -v -w"\\n" -X PUT +http://cdapurl:11015/v3/namespaces/setelsewhere/artifacts/ARTIFACT_NAME/versions/ARTIFACT_VERSION_HEADER/properties +-d (DOWNLOADED FROM UI\_PROPERTIES\_URL)" + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **artifac | the value of the header that gets passed in | string | +| t\_extends\ | for artifact-extends, e.g., | | +| _header** | "Artifact-Extends:system:cdap-data-pipeline | | +| | *required | [4.0.1,5.0.0)" | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **artifac | the name of the artifact | string | +| t\_name** | | | +| | *required | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **artifac | the URL of the artifact JAR | string | +| t\_url** | | | +| | *required | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **artifac | the value of the header that gets passed in | string | +| t\_version\ | for artifact-version, e.g., | | +| _header** | "Artifact-Version:1.0.0-SNAPSHOT" | | +| | *required | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **ui\_pro | the URL of the properties.json if the | string | +| perties\_ur | custom artifact has UI properties. This is | | +| l** | optional. | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +info +---- + +some broker information + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **broker | the API version of this running broker | string | +| API | | | +| version** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **cdap | The GUI port of the CDAP cluster this | integer | +| GUI | broker is managing. Mostly to help users of | | +| port** | this API check their application in cdap. | | +| | *optional | Note, will return UNKNOWN\_CDAP\_VERSION if | | +| * | it cannot be determined. | | ++-------------+---------------------------------------------+------------------+ +| | **cdap | the version of the CDAP cluster this broker | string | +| cluster | is managing. Note, will return | | +| version** | UKNOWN\_CDAP\_VERSION if it cannot be | | +| | *optional | determined. | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **managed | the url of the CDAP cluster API this broker | string | +| cdap | is managing | | +| url** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **number | | integer | +| of | | | +| applicati | | | +| ons | | | +| registere | | | +| d** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **uptime | | integer | +| (s)** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +multideleteput +-------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **appnames** | < `appname <#_appname>`__ > array | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +programpref +----------- + +the list of programs in this CDAP app + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **program | the name of the program | string | +| \_id** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **program | the preference JSON to set for this program | object | +| \_pref** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **program | must be one of flows, mapreduce, schedules, | string | +| \_type** | spark, workflows, workers, or services | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +programs +-------- + +the list of programs in this CDAP app + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **program | the name of the program | string | +| \_id** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **program | must be one of flows, mapreduce, schedules, | string | +| \_type** | spark, workflows, workers, or services | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +reconfigput +----------- + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **config* | the config JSON | object | +| * | | | +| | *required | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **reconfi | the type of reconfiguration | enum | +| guration\_t | | (program-flowlet | +| ype** | | -app-config, | +| | *required | | program-flowlet- | +| * | | app-preferences, | +| | | program-flowlet- | +| | | smart) | ++-------------+---------------------------------------------+------------------+ + +returncode +---------- + +an httpreturncode + +*Type* : integer + +service\_endpoint +----------------- + +descirbes a service endpoint, including the service name, the method +name, and the method type (GET, PUT, etc, most of the time will be GET) + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **endpoin | GET, POST, PUT, etc | string | +| t\_method** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **service | the name of the endpoint on the service | string | +| \_endpoint* | | | +| * | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **service | the name of the service | string | +| \_name** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +service\_method +--------------- + +a URL and HTTP method exposed via a CDAP service + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **method* | HTTP method you can perform on the URL, | string | +| * | e.g., GET, PUT, etc | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **url** | the fully qualified URL in CDAP for this | string | +| | *optional | service | | +| * | | | ++-------------+---------------------------------------------+------------------+ diff --git a/docs/templates/sections/apiexample/httpdomain.rst b/docs/templates/sections/apiexample/httpdomain.rst new file mode 100644 index 000000000..f06d0067a --- /dev/null +++ b/docs/templates/sections/apiexample/httpdomain.rst @@ -0,0 +1,10 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Sphinx httpdomain directive +=========================== + +.. http:get:: path + + For more information see `<https://pythonhosted.org/sphinxcontrib-httpdomain>`_ + diff --git a/docs/templates/sections/apiexample/swagger2markup.rst b/docs/templates/sections/apiexample/swagger2markup.rst new file mode 100644 index 000000000..b83bd4d96 --- /dev/null +++ b/docs/templates/sections/apiexample/swagger2markup.rst @@ -0,0 +1,24 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + + +Swagger2Markup(asciidoc) to Asciidoctor(docbook) to Pandoc(RST) +=============================================================== + +vfc-nfvo-lcm +------------ + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + vfcexample.rst + + +DCAE and YAML intput +-------------------- + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + dcaecdap.rst diff --git a/docs/templates/sections/apiexample/swaggerv2doc.rst b/docs/templates/sections/apiexample/swaggerv2doc.rst new file mode 100644 index 000000000..a0f13e061 --- /dev/null +++ b/docs/templates/sections/apiexample/swaggerv2doc.rst @@ -0,0 +1,11 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + + + +Sphinx swaggerv2doc directive +----------------------------- +Here is an example of vfc-nfvo-lcm API. + +.. swaggerv2doc:: https://gerrit.onap.org/r/gitweb?p=vfc/nfvo/lcm.git;a=blob_plain;f=lcm/swagger/vfc.nslcm.swagger.json + + diff --git a/docs/templates/sections/apiexample/vfcexample.rst b/docs/templates/sections/apiexample/vfcexample.rst new file mode 100644 index 000000000..71d3b7814 --- /dev/null +++ b/docs/templates/sections/apiexample/vfcexample.rst @@ -0,0 +1,768 @@ +================================================= +ONAP VFC Network Service Lifecycle Management API +================================================= + +:Date: 2017-10-09 + +.. contents:: + :depth: 3 +.. + +Overview +======== + +VFC Network Service Lifecycle Management Rest API. + +Version information +------------------- + +*Version* : 1.0.0 + +Contact information +------------------- + +| *Contact* : ONAP VFC team +| *Contact Email* : onap-discuss@lists.onap.org + +URI scheme +---------- + +| *BasePath* : /api/nslcm/v1 +| *Schemes* : HTTP, HTTPS + +Consumes +-------- + +- ``application/json`` + +Produces +-------- + +- ``application/json`` + +Paths +===== + +jobstatus +--------- + +:: + + GET /jobs/{jobId} + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **jobId** | job Id | string | +| * | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Query | | **respons | job response message id | string | +| ** | eId** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++-------------------------+--------------------------------------------------+ +| HTTP Code | Schema | ++=========================+==================================================+ +| **202** | `JobDetailInfo <#_jobdetailinfo>`__ | ++-------------------------+--------------------------------------------------+ + +Tags +~~~~ + +- job + +ns create +--------- + +:: + + POST /ns + +Description +~~~~~~~~~~~ + +ns create + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Body* | | **NSCreat | NS Instance Create Request | `NsCreateRequest | +| * | eRequest** | | <#_nscreaterequ | +| | | *required | | est>`__ | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | successful operation | `NsCreateRespo | +| | | nse <#_nscreat | +| | | eresponse>`__ | ++---------+----------------------------------------------------+----------------+ +| **404** | URL not found | No Content | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +ns get +------ + +:: + + GET /ns + +Description +~~~~~~~~~~~ + +ns get + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Query | | **csarId* | job response message id | string | +| ** | * | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | successful operation | `NsInstancesIn | +| | | fo <#_nsinstan | +| | | cesinfo>`__ | ++---------+----------------------------------------------------+----------------+ +| **404** | URL not found | No Content | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +ns Instantiate +-------------- + +:: + + POST /ns/{nsInstanceId}/Instantiate + +Description +~~~~~~~~~~~ + +ns Instantiate + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **nsInsta | | string | +| * | nceId** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Body* | | **NSInsta | NS Instantiate Request Body | `NsInstantiateRe | +| * | ntiateReque | | quest <#_nsinsta | +| | st** | | ntiaterequest>`_ | +| | | *required | | _ | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | | `JobInfo <#_jo | +| | | binfo>`__ | ++---------+----------------------------------------------------+----------------+ +| **201** | Invalid Request | No Content | ++---------+----------------------------------------------------+----------------+ +| **404** | URL not found | No Content | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +ns scale +-------- + +:: + + POST /ns/{nsInstanceId}/scale + +Description +~~~~~~~~~~~ + +ns scale + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **nsInsta | | string | +| * | nceId** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Body* | | **ScaleNS | Scale NS Request Body | `NsScaleRequest | +| * | Request** | | <#_nsscalereques | +| | | *required | | t>`__ | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | | `JobInfo <#_jo | +| | | binfo>`__ | ++---------+----------------------------------------------------+----------------+ +| **201** | Invalid Request | No Content | ++---------+----------------------------------------------------+----------------+ +| **404** | URL not found | No Content | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +ns get +------ + +:: + + GET /ns/{ns_instance_id} + +Description +~~~~~~~~~~~ + +ns get + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | successful operation | `NsInstanceInf | +| | | o <#_nsinstanc | +| | | einfo>`__ | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +ns delete +--------- + +:: + + DELETE /ns/{ns_instance_id} + +Description +~~~~~~~~~~~ + +ns delete + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **ns\_ins | Identifier of the NS instance. | string | +| * | tance\_id** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **204** | The NS instance resource and the associated NS | No Content | +| | identifier were deleted successfully. | | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +ns heal +------- + +:: + + POST /ns/{ns_instance_id}/heal + +Description +~~~~~~~~~~~ + +ns heal + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **ns\_ins | Identifier of the NS instance. | string | +| * | tance\_id** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Body* | | **healVnf | healVnfData | `NsHealRequest < | +| * | Data** | | #_nshealrequest> | +| | | *required | | `__ | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **202** | | `JobInfo <#_jo | +| | | binfo>`__ | ++---------+----------------------------------------------------+----------------+ +| **404** | URL not found | No Content | ++---------+----------------------------------------------------+----------------+ +| **500** | the url is invalid | No Content | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +ns terminate +------------ + +:: + + POST /ns/{ns_instance_id}/terminate + +Description +~~~~~~~~~~~ + +ns terminate + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **ns\_ins | Identifier of the NS instance. | string | +| * | tance\_id** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Body* | | **NsTermi | NsTerminateRequest | `NsTerminateRequ | +| * | nateRequest | | est <#_nstermina | +| | ** | | terequest>`__ | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **202** | | `JobInfo <#_jo | +| | | binfo>`__ | ++---------+----------------------------------------------------+----------------+ +| **500** | the url is invalid | No Content | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +Definitions +=========== + +JobDetailInfo +------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **jobId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **responseDescriptor** | `responseDescriptor <#_jobdetailinfo_resp | +| | *optional* | onsedescriptor>`__ | ++--------------------------------+-------------------------------------------+ + +**responseDescriptor** + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **errorCode** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **progress** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **responseHistoryList** | < `jobResponseInfo <#_jobresponseinfo>`__ | +| | *optional* | > array | ++--------------------------------+-------------------------------------------+ +| | **responseId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **status** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **statusDescription** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +JobInfo +------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **jobId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +LocationConstraint +------------------ + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **locationConstraints** | `locationConstraints <#_locationconstrain | +| | *optional* | t_locationconstraints>`__ | ++--------------------------------+-------------------------------------------+ +| | **vnfProfileId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +**locationConstraints** + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **vimid** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +NsCreateRequest +--------------- + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **csarId* | the NS package ID | string | +| * | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **descrip | | string | +| tion** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **nsName* | | string | +| * | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +NsCreateResponse +---------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **nsInstanceId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +NsHealRequest +------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **additionalParams** | `additionalParams <#_nshealrequest_additi | +| | *optional* | onalparams>`__ | ++--------------------------------+-------------------------------------------+ +| | **cause** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vnfInstanceId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +**additionalParams** + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **action** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **actionvminfo** | `actionvminfo <#_nshealrequest_actionvmin | +| | *optional* | fo>`__ | ++--------------------------------+-------------------------------------------+ + +**actionvminfo** + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **vmid** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vmname** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +NsInstanceInfo +-------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **description** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **nsInstanceId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **nsName** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **nsState** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **nsdId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vlInfo** | < `vlInfo <#_vlinfo>`__ > array | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vnfInfo** | < `vnfInfo <#_vnfinfo>`__ > array | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vnffgInfo** | < `vnffgInfo <#_vnffginfo>`__ > array | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +NsInstancesInfo +--------------- + +*Type* : < `NsInstanceInfo <#_nsinstanceinfo>`__ > array + +NsInstantiateRequest +-------------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **LocationConstraints** | < | +| | *optional* | `LocationConstraint <#_locationconstraint | +| | >`__ | +| | > array | ++--------------------------------+-------------------------------------------+ +| | **additionalParamForNs** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +NsScaleByStepsData +------------------ + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **aspectId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **numberOfSteps** | integer | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **scalingDirection** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +NsScaleRequest +-------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **scaleNsByStepsData** | `NsScaleByStepsData <#_nsscalebystepsdata | +| | *optional* | >`__ | ++--------------------------------+-------------------------------------------+ +| | **scaleType** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +NsTerminateRequest +------------------ + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **gracefulTerminationTimeout | string | +| ** | | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **terminationType** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +cpInfo +------ + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **cpInstanceId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **cpInstanceName** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **cpdId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +jobResponseInfo +--------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **errorCode** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **progress** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **responseId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **status** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **statusDescription** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +vlInfo +------ + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **relatedCpInstanceId** | < `cpInfo <#_cpinfo>`__ > array | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vlInstanceId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vlInstanceName** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vldId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +vnfInfo +------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **vnfInstanceId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vnfInstanceName** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vnfdId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +vnffgInfo +--------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **cpId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **nfp** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **pnfId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **virtualLinkId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vnfId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vnffgInstanceId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ diff --git a/docs/templates/sections/apiexample/worddoc2rst.rst b/docs/templates/sections/apiexample/worddoc2rst.rst new file mode 100644 index 000000000..2e1f8148c --- /dev/null +++ b/docs/templates/sections/apiexample/worddoc2rst.rst @@ -0,0 +1,11 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Word Document Converted to RST +------------------------------ +This is an example of an APPC API Guide. + +.. toctree:: + :maxdepth: 1 + + ../../../submodules/appc.git/docs/APPC API Guide/APPC API Guide diff --git a/docs/templates/sections/architecture.rst b/docs/templates/sections/architecture.rst new file mode 100644 index 000000000..8daa0d3bc --- /dev/null +++ b/docs/templates/sections/architecture.rst @@ -0,0 +1,27 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Architecture +============ + +.. note:: + * This section is used to describe a software component from a high level + view of capability, common usage scenarios, and interactions with other + components required in the usage scenarios. + + * The architecture section is typically: provided in a platform-component + and sdk collections; and referenced from developer and user guides. + + * This note must be removed after content has been added. + + +Capabilities +------------ + + +Usage Scenarios +--------------- + + +Interactions +------------ diff --git a/docs/templates/sections/build.rst b/docs/templates/sections/build.rst new file mode 100644 index 000000000..99a061c24 --- /dev/null +++ b/docs/templates/sections/build.rst @@ -0,0 +1,23 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Build +===== + +.. note:: + * This section is used to describe how a software component is built from source + into something ready for use either in a run-time environment or to build other + components. + + * This section is typically provided for a platform-component, application, and sdk; and + referenced in developer guides. + + * This note must be removed after content has been added. + + +Environment +----------- + + +Steps +----- diff --git a/docs/templates/sections/configuration.rst b/docs/templates/sections/configuration.rst new file mode 100644 index 000000000..085f9c667 --- /dev/null +++ b/docs/templates/sections/configuration.rst @@ -0,0 +1,27 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Configuration +============= + +.. note:: + * This section is used to describe the options a software component offers for configuration. + + * Configuration is typically: provided for platform-component and sdk projects; + and referenced in developer and user guides. + + * This note must be removed after content has been added. + + + +Example ... + +You can provide the following in ``basic.conf`` + +``host=ADDRESS`` + The address of the host + +``port=PORT`` + The port used for signaling + + Optional. Default: ``8080`` diff --git a/docs/templates/sections/consumedapis.rst b/docs/templates/sections/consumedapis.rst new file mode 100644 index 000000000..c2af4c20e --- /dev/null +++ b/docs/templates/sections/consumedapis.rst @@ -0,0 +1,16 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Consumed APIs +============= + +.. note:: + * This section is used to reference APIs that a software component depends on + and uses from other sources. + + * Consumed APIs should be a specific link to the offered APIs from another component + or external source. + + * This note must be removed after content has been added. + + diff --git a/docs/templates/sections/delivery.rst b/docs/templates/sections/delivery.rst new file mode 100644 index 000000000..f3f083a73 --- /dev/null +++ b/docs/templates/sections/delivery.rst @@ -0,0 +1,44 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Delivery +======== + +.. note:: + * This section is used to describe a software component packaging. + For a run-time component this might be executable images, containers, etc. + For an SDK this might be libraries. + + * This section is typically provided for a platform-component and sdk; + and referenced in developer and user guides + + * This note must be removed after content has been added. + +Example use of a block diagram. + +.. blockdiag:: + + + blockdiag layers { + orientation = portrait + a -> m; + b -> n; + c -> x; + m -> y; + m -> z; + group l1 { + color = blue; + x; y; z; + } + group l2 { + color = yellow; + m; n; + } + group l3 { + color = orange; + a; b; c; + } + + } + + diff --git a/docs/templates/sections/design.rst b/docs/templates/sections/design.rst new file mode 100644 index 000000000..f173a2fb5 --- /dev/null +++ b/docs/templates/sections/design.rst @@ -0,0 +1,13 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Design +====== + +.. note:: + * This section is used to describe the internal design structure of a software component. + + * This section is typically provided: for a platform-component and sdk; and + referenced in developer guides. + + * This note must be removed after content has been added. diff --git a/docs/templates/sections/humaninsterfaces.rst b/docs/templates/sections/humaninsterfaces.rst new file mode 100644 index 000000000..429284608 --- /dev/null +++ b/docs/templates/sections/humaninsterfaces.rst @@ -0,0 +1,17 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Human Interfaces +================ + +.. note:: + * This section is used to describe a software component's command line and graphical + user interfaces. + + * This section is typically: provided for a platform-component and application; and + referenced from user guides. + + * This note must be removed after content has been added. + + + diff --git a/docs/templates/sections/installation.rst b/docs/templates/sections/installation.rst new file mode 100644 index 000000000..be64a63bb --- /dev/null +++ b/docs/templates/sections/installation.rst @@ -0,0 +1,20 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Installation +============ + +.. note:: + * This section is used to describe how a software component is acquired and installed. + + * This section is typically: provided for a platform-component and application; and + referenced in user guides. + + * This note must be removed after content has been added. + +Environment +----------- + + +Steps +----- diff --git a/docs/templates/sections/logging.rst b/docs/templates/sections/logging.rst new file mode 100644 index 000000000..39eabfba7 --- /dev/null +++ b/docs/templates/sections/logging.rst @@ -0,0 +1,22 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Logging +======= + +.. note:: + * This section is used to describe the informational or diagnostic messages emitted from + a software component and the methods or collecting them. + + * This section is typically: provided for a platform-component and sdk; and + referenced in developer and user guides + + * This note must be removed after content has been added. + + +Where to Access Information +--------------------------- + + +Error / Warning Messages +------------------------ diff --git a/docs/templates/sections/offeredapis.rst b/docs/templates/sections/offeredapis.rst new file mode 100644 index 000000000..b1b8f41e8 --- /dev/null +++ b/docs/templates/sections/offeredapis.rst @@ -0,0 +1,26 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Offered APIs +============ + +.. note:: + * This section is used to describe the external interfaces offered by a software component + + * This section is typically: provided for a platform-component and sdk; and + referenced in developer guides and api reference manuals. + + * This note must be removed after content has been added. + + + +Here are several examples: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + apiexample/swaggerv2doc.rst + apiexample/swagger2markup.rst + apiexample/worddoc2rst.rst + apiexample/httpdomain.rst diff --git a/docs/templates/sections/release-notes.rst b/docs/templates/sections/release-notes.rst new file mode 100644 index 000000000..ca257314e --- /dev/null +++ b/docs/templates/sections/release-notes.rst @@ -0,0 +1,46 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Release Notes +============= + +.. note:: + * This Release Notes must be updated each time the team decides to Release new artifacts. + * The scope of this Release Notes is for this particular component. In other words, each ONAP component has its Release Notes. + * This Release Notes is cumulative, the most recently Released artifact is made visible in the top of this Release Notes. + * Except the date and the version number, all the other sections are optional but there must be at least one section describing the purpose of this new release. + * This note must be removed after content has been added. + + +Version: x.y.z +-------------- + + +:Release Date: yyyy-mm-dd + + + +**New Features** + +One or two sentences explaining the purpose of this Release. + +**Bug Fixes** + - `CIMAN-65 <https://jira.onap.org/browse/CIMAN-65>`_ and a sentence explaining what this defect is addressing. +**Known Issues** + - `CIMAN-65 <https://jira.onap.org/browse/CIMAN-65>`_ and two, three sentences. + One sentences explaining what is the issue. + + Another sentence explaining the impact of the issue. + + And an optional sentence providing a workaround. + +**Security Issues** + You may want to include a reference to CVE (Common Vulnerabilities and Exposures) `CVE <https://cve.mitre.org>`_ + + +**Upgrade Notes** + +**Deprecation Notes** + +**Other** + +=========== diff --git a/etc/requirements.txt b/etc/requirements.txt index 35f9168f4..fa752e6aa 100644 --- a/etc/requirements.txt +++ b/etc/requirements.txt @@ -4,6 +4,7 @@ doc8 docutils setuptools six +sphinx_rtd_theme sphinxcontrib-httpdomain sphinxcontrib-blockdiag sphinxcontrib-seqdiag |