From 075cab7dceb632b3d82786fa0212e7b5f852a0ea Mon Sep 17 00:00:00 2001 From: Rich Bennett Date: Wed, 15 May 2019 16:10:18 -0400 Subject: [PATCH] First commit to dublin branch Add default branch to .gitreview Switch sphinx theme to bootstrap with bootswatch lumen style Reuse OPENDAYLIGHT/OPNFV side navbar templates Remove unused options in conf.py and add the License text Begin to use the lfit/releng global doc project template Add TODO for guidelines on use of the new theme Update submodule references for contributing repositories that already have a dublin branch Change-Id: I60c26a25bd15b90ab4878b0635ebd9b9d8712a0d Issue-ID: DOC-467 Signed-off-by: Rich Bennett --- .gitreview | 1 + docs/_static/css/ribbon.css | 2 +- docs/_templates/navbar.html | 76 +++++++++++++ docs/_templates/relations.html | 16 +++ docs/conf.py | 120 ++++++--------------- docs/conf.yaml | 1 + .../onap-developer/how-to-use-docs/style-guide.rst | 2 + docs/submodules/appc.git | 2 +- docs/submodules/ccsdk/apps.git | 2 +- docs/submodules/ccsdk/distribution.git | 2 +- docs/submodules/ccsdk/features.git | 2 +- docs/submodules/ccsdk/parent.git | 2 +- docs/submodules/dmaap/datarouter.git | 2 +- docs/submodules/music.git | 2 +- docs/submodules/sdc.git | 2 +- docs/submodules/sdc/jtosca.git | 2 +- docs/submodules/sdc/sdc-tosca.git | 2 +- docs/submodules/sdnc/oam.git | 2 +- docs/submodules/so.git | 2 +- docs/submodules/so/libs.git | 2 +- docs/submodules/vid.git | 2 +- etc/requirements.txt | 3 +- 22 files changed, 144 insertions(+), 105 deletions(-) create mode 100644 docs/_templates/navbar.html create mode 100644 docs/_templates/relations.html create mode 100644 docs/conf.yaml diff --git a/.gitreview b/.gitreview index c088dd69b..c1e7543e4 100644 --- a/.gitreview +++ b/.gitreview @@ -2,3 +2,4 @@ host=gerrit.onap.org port=29418 project=doc.git +defaultbranch=dublin diff --git a/docs/_static/css/ribbon.css b/docs/_static/css/ribbon.css index 6008cb1a0..d5748c91a 100644 --- a/docs/_static/css/ribbon.css +++ b/docs/_static/css/ribbon.css @@ -4,7 +4,7 @@ overflow: hidden; white-space: nowrap; position: fixed; - top: 25px; + top: 70px; right: -50px; -webkit-transform: rotate(45deg); -moz-transform: rotate(45deg); diff --git a/docs/_templates/navbar.html b/docs/_templates/navbar.html new file mode 100644 index 000000000..41f5c8181 --- /dev/null +++ b/docs/_templates/navbar.html @@ -0,0 +1,76 @@ +
+ + {% if version_status == 'unsupported' %} +
+ This document is for a release of ONAP that is no longer supported. +
+ + {% elif version_status == 'deprecated' %} +
+ This document is for a deprecated release of ONAP and will receive only security updates. +
+ + {% else %} + + {% endif %} +
+
+ + + + {%- block sidebarlogo %} + {%- if logo %}{%- endif %} + {%- endblock %} + {% if theme_navbar_title -%}{{ theme_navbar_title|e }}{%- else -%}{{ project|e }}{%- endif -%} + + {{ version|e }} +
+ +
+
    + {% if theme_navbar_links %} + {%- for link in theme_navbar_links %} +
  • {{ link[0] }}
    • + {%- endfor %} + {% endif %} + {% block navbartoc %} + {% include "globaltoc.html" %} + {% if theme_navbar_pagenav %} + {% include "navbartoc.html" %} + {% endif %} + {% endblock %} + {% if theme_navbar_sidebarrel %} + {% block sidebarrel %} + {% include "relations.html" %} + {% endblock %} + {% endif %} + {% block navbarextra %} + {% endblock %} + {% if theme_source_link_position == "nav" %} + + {% endif %} +
+ + {% block navbarsearch %} + {% include "navbarsearchbox.html" %} + {% endblock %} +
+
+
+ diff --git a/docs/_templates/relations.html b/docs/_templates/relations.html new file mode 100644 index 000000000..c701ed0c0 --- /dev/null +++ b/docs/_templates/relations.html @@ -0,0 +1,16 @@ +
+
+ {% if prev %} + Prev Page + {% else %} + + {% endif %} + + {% if next %} + Next Page + {% else %} + + {% endif %} +
+
+ diff --git a/docs/conf.py b/docs/conf.py index 5cab846ce..79b64b202 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,35 +1,22 @@ -# -*- coding: utf-8 -*- +#Copyright (c) 2017 Open Network Automation Platform and contributors # -# ONAP documentation build configuration file, created by -# sphinx-quickstart on Wed Jul 19 16:25:31 2017. +#Licensed under the Apache License, Version 2.0 (the "License"); +#you may not use this file except in compliance with the License. +#You may obtain a copy of the License at # -# This file is execfile()d with the current directory set to its -# containing dir. +# http://www.apache.org/licenses/LICENSE-2.0 # -# 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_bootstrap_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('.')) +#Unless required by applicable law or agreed to in writing, +#software distributed under the License is distributed on an +#"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, +#either express or implied. See the License for the specific +#language governing permissions and limitations under the License. -# -- General configuration ------------------------------------------------ +import sphinx_bootstrap_theme +from docs_conf.conf import * -# 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. +#Sphinx Extensions extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', @@ -47,81 +34,42 @@ extensions = [ 'sphinxcontrib.swaggerdoc' ] -# Font path for seqdiag +# Extension Configuration seqdiag_fontpath = '/usr/share/fonts/truetype/dejavu/DejaVuSansCondensed.ttf' nwdiag_fontpath = '/usr/share/fonts/truetype/dejavu/DejaVuSansCondensed.ttf' -# Add any paths that contain templates here, relative to this directory. +# Template Paths 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'' copyright = u'2019 ONAP. Licensed under Creative Commons Attribution 4.0 International License' - - author = u'Open Network Automation Platform' -# 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 = 'master branch' -# The full version, including alpha/beta/rc tags. -release = 'master branch' +# Project version and release +version = 'dublin' +release = 'dublin' -# 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. +# The language for content autogenerated by Sphinx. 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 +keep_warnings = True # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True @@ -129,21 +77,13 @@ 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' - -# 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. +# The theme to use for HTML and HTML Help pages. +html_theme = 'bootstrap' html_theme_options = { - 'style_nav_header_background': 'white', - 'sticky_navigation': False + 'bootswatch_theme': "lumen", + 'navbar_sidebarrel': False } - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() +html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -155,10 +95,6 @@ html_theme_options = { # 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, @@ -380,6 +316,12 @@ epub_exclude_files = ['search.html'] # If false, no index is generated. #epub_use_index = True + +nitpicky = True +html_context = { + 'version_status': 'supported', + } + # Patterns to ignore in linkcheck builder linkcheck_ignore = [ r'http://$', diff --git a/docs/conf.yaml b/docs/conf.yaml new file mode 100644 index 000000000..754d842f7 --- /dev/null +++ b/docs/conf.yaml @@ -0,0 +1 @@ +project_cfg: ONAP diff --git a/docs/guides/onap-developer/how-to-use-docs/style-guide.rst b/docs/guides/onap-developer/how-to-use-docs/style-guide.rst index 324688551..ddc3d5b07 100644 --- a/docs/guides/onap-developer/how-to-use-docs/style-guide.rst +++ b/docs/guides/onap-developer/how-to-use-docs/style-guide.rst @@ -106,6 +106,8 @@ Headings (Titles) - Use descriptive titles for tables and figures titles. Do not number tables or figures. Do not (in general) add titles for screen shots. +- Guidelines for heading levels and toctree directive + Tasks ^^^^^ - Start task titles with an action word. Examples: Create, Add, diff --git a/docs/submodules/appc.git b/docs/submodules/appc.git index 25f856fae..dfc9d1aeb 160000 --- a/docs/submodules/appc.git +++ b/docs/submodules/appc.git @@ -1 +1 @@ -Subproject commit 25f856faedd92ba62e8348507f7baf8ef34f4540 +Subproject commit dfc9d1aebb3150074729b4f0c035e0308d3aa01c diff --git a/docs/submodules/ccsdk/apps.git b/docs/submodules/ccsdk/apps.git index 16a34aeee..441b7640a 160000 --- a/docs/submodules/ccsdk/apps.git +++ b/docs/submodules/ccsdk/apps.git @@ -1 +1 @@ -Subproject commit 16a34aeeebad1775ea4a6675c19f041b273dcdfb +Subproject commit 441b7640a1797f9e340bfa4a176df72ecdd9f5e3 diff --git a/docs/submodules/ccsdk/distribution.git b/docs/submodules/ccsdk/distribution.git index 8d4467847..bbff2fb82 160000 --- a/docs/submodules/ccsdk/distribution.git +++ b/docs/submodules/ccsdk/distribution.git @@ -1 +1 @@ -Subproject commit 8d4467847a7992c1525555a3f43599b195a0bf08 +Subproject commit bbff2fb829fd3c5b301c061db22119c7cb1743f7 diff --git a/docs/submodules/ccsdk/features.git b/docs/submodules/ccsdk/features.git index 63c4144c0..e9579499f 160000 --- a/docs/submodules/ccsdk/features.git +++ b/docs/submodules/ccsdk/features.git @@ -1 +1 @@ -Subproject commit 63c4144c0664db9ea526c0608a30b47de80eed86 +Subproject commit e9579499fa871c16ac729116714ece9b959acbcd diff --git a/docs/submodules/ccsdk/parent.git b/docs/submodules/ccsdk/parent.git index 29e82cfb8..c3819ef12 160000 --- a/docs/submodules/ccsdk/parent.git +++ b/docs/submodules/ccsdk/parent.git @@ -1 +1 @@ -Subproject commit 29e82cfb81e948500c99393fc09765af603730f8 +Subproject commit c3819ef1275b3785978b728dec2bf9941461dfad diff --git a/docs/submodules/dmaap/datarouter.git b/docs/submodules/dmaap/datarouter.git index 3ebd25341..bb01fecef 160000 --- a/docs/submodules/dmaap/datarouter.git +++ b/docs/submodules/dmaap/datarouter.git @@ -1 +1 @@ -Subproject commit 3ebd2534167e73426d2b19efb05eaf9892f6f9d6 +Subproject commit bb01feceff0527c8f63ad513d85975e5c4e2e52f diff --git a/docs/submodules/music.git b/docs/submodules/music.git index d6e7b63cc..0f4fd38d0 160000 --- a/docs/submodules/music.git +++ b/docs/submodules/music.git @@ -1 +1 @@ -Subproject commit d6e7b63cc580e7b3822be61fe92a493ad5e222a3 +Subproject commit 0f4fd38d0414058a088335189fc7a8cafbad4ccf diff --git a/docs/submodules/sdc.git b/docs/submodules/sdc.git index 02a3b49be..a04dc4d3b 160000 --- a/docs/submodules/sdc.git +++ b/docs/submodules/sdc.git @@ -1 +1 @@ -Subproject commit 02a3b49bec86eb0a434afb86e158ca2670cb718f +Subproject commit a04dc4d3bc12cdc77e04fad89fc369c869cdd61f diff --git a/docs/submodules/sdc/jtosca.git b/docs/submodules/sdc/jtosca.git index 6018fb047..a0244589b 160000 --- a/docs/submodules/sdc/jtosca.git +++ b/docs/submodules/sdc/jtosca.git @@ -1 +1 @@ -Subproject commit 6018fb047963d151d77bf03f6f84446866a30899 +Subproject commit a0244589b50f80bc510b5d8dd4df02bb5870056e diff --git a/docs/submodules/sdc/sdc-tosca.git b/docs/submodules/sdc/sdc-tosca.git index 45435cd68..c6bdb4e47 160000 --- a/docs/submodules/sdc/sdc-tosca.git +++ b/docs/submodules/sdc/sdc-tosca.git @@ -1 +1 @@ -Subproject commit 45435cd6812c1118b7751163b46618c6329a1ac1 +Subproject commit c6bdb4e477d0ad6b146ce811f32fc8356c12a226 diff --git a/docs/submodules/sdnc/oam.git b/docs/submodules/sdnc/oam.git index 186befdfa..b1df91894 160000 --- a/docs/submodules/sdnc/oam.git +++ b/docs/submodules/sdnc/oam.git @@ -1 +1 @@ -Subproject commit 186befdfa74d04794b27cbb3d73d8beb18d17c0d +Subproject commit b1df91894e7983ec1fc39c961d3a93e96fc236b5 diff --git a/docs/submodules/so.git b/docs/submodules/so.git index f9c309fb9..3d58f1942 160000 --- a/docs/submodules/so.git +++ b/docs/submodules/so.git @@ -1 +1 @@ -Subproject commit f9c309fb9e789225ccd6b02ec9ab4777bbd4021c +Subproject commit 3d58f194230268d439761e6062cca0481437ef77 diff --git a/docs/submodules/so/libs.git b/docs/submodules/so/libs.git index 9a2470a31..f31f8ce72 160000 --- a/docs/submodules/so/libs.git +++ b/docs/submodules/so/libs.git @@ -1 +1 @@ -Subproject commit 9a2470a315a0f31f79c49eeebc93a8e2bcb42c1e +Subproject commit f31f8ce722efcb2465d290cc3755c258ef2857af diff --git a/docs/submodules/vid.git b/docs/submodules/vid.git index 4dc2c4df2..445056740 160000 --- a/docs/submodules/vid.git +++ b/docs/submodules/vid.git @@ -1 +1 @@ -Subproject commit 4dc2c4df24d733db6176c738eb9a9ee35a112795 +Subproject commit 445056740d0f24e45d0c8f90cc024bbc090165b4 diff --git a/etc/requirements.txt b/etc/requirements.txt index fc22c1447..d1167b6e0 100644 --- a/etc/requirements.txt +++ b/etc/requirements.txt @@ -1,5 +1,5 @@ tox -Sphinx==1.8.4 +Sphinx==1.8.5 doc8 docutils setuptools @@ -12,3 +12,4 @@ sphinxcontrib-seqdiag sphinxcontrib-swaggerdoc sphinxcontrib-plantuml sphinx_bootstrap_theme>=0.4.11 +lfdocs-conf -- 2.16.6