From c57268ca1179dedc3448ad9b4e27f69a588df44c Mon Sep 17 00:00:00 2001 From: Stone Date: Wed, 10 Mar 2021 16:13:30 -0500 Subject: [PATCH] api-ref html builds rST fixes to index and api docs. Commented out release notes job in zuul. There don't appear to be any and it is causing failures. Added a doc job to tox and created content pointing to api-ref. Moved api-ref/doc/requirements.txt up one level Added templates section to .zuul.yaml Added api-refs env to tox.ini Added pip requirements for sphinx builds Signed-off-by: Stone Change-Id: Ic20dfe02d40d193ce443240170f967d72899a58b Signed-off-by: Ron Stone Signed-off-by: Stone --- .gitignore | 4 +- .zuul.yaml | 4 + .../api_ptp_notifications_definition_v1.rst | 12 +- api-ref/source/index.rst | 3 +- doc/requirements.txt | 4 + doc/source/conf.py | 146 ++++++++++++++++++ doc/source/index.rst | 28 ++++ tox.ini | 18 +++ 8 files changed, 211 insertions(+), 8 deletions(-) create mode 100644 doc/requirements.txt create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst diff --git a/.gitignore b/.gitignore index 84d28ed..4b7777a 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ -.tox \ No newline at end of file +.tox +api-ref/build +doc/build diff --git a/.zuul.yaml b/.zuul.yaml index aa15bb3..a12498c 100644 --- a/.zuul.yaml +++ b/.zuul.yaml @@ -1,5 +1,9 @@ --- - project: + templates: + - publish-stx-docs + - stx-api-ref-jobs + # - stx-release-notes-jobs check: jobs: - openstack-tox-linters diff --git a/api-ref/source/api_ptp_notifications_definition_v1.rst b/api-ref/source/api_ptp_notifications_definition_v1.rst index a7af3e9..5d40b01 100644 --- a/api-ref/source/api_ptp_notifications_definition_v1.rst +++ b/api-ref/source/api_ptp_notifications_definition_v1.rst @@ -91,7 +91,7 @@ Manange Subscriptions Query subscription resources ****************************** -.. rest_method:: rest_method:: GET /ocloudNotifications/v1/subscriptions +.. rest_method:: GET /ocloudNotifications/v1/subscriptions **Normal response codes** @@ -141,7 +141,7 @@ This operation does not accept a request body. Query individual subscription resource **************************************** -.. rest_method:: rest_method:: GET /ocloudNotifications/v1/{SubscriptionId} +.. rest_method:: GET /ocloudNotifications/v1/{SubscriptionId} **Normal response codes** @@ -189,7 +189,7 @@ This operation does not accept a request body Delete individual subscription resource **************************************** -.. rest_method:: rest_method:: DELETE /ocloudNotifications/v1/{SubscriptionId} +.. rest_method:: DELETE /ocloudNotifications/v1/{SubscriptionId} **Normal response codes** @@ -217,7 +217,7 @@ Pull Status Notifications Pull PTP status notifications ****************************** -.. rest_method:: rest_method:: GET /ocloudNotifications/{ResourceType}/CurrentState +.. rest_method:: GET /ocloudNotifications/{ResourceType}/CurrentState **Normal response codes** @@ -242,7 +242,7 @@ This operation does not accept a request body. :header: "Parameter", "Style", "Type", "Description" :widths: 20, 20, 20, 60 - "EventData", "plain", ""xsd:string, "Describes the synchronization state for PTP, State: ``Freerun``, ``Locked``, ``Holdover``." + "EventData", "plain", "xsd:string", "Describes the synchronization state for PTP, State: ``Freerun``, ``Locked``, ``Holdover``." "EventTimestamp", "plain", "xsd:float", "This is the time that the event was detected (elapsed seconds since epoch time)." "ResourceQualifier", "plain", "xsd:string", "The node name where PTP resides, ``NodeName``: ``*`` for all worker nodes, ``.`` for worker node where the application resides, ``node name`` specified by the downward API" "ResourceType", "plain", "xsd:string", "The resource to subscribe to, currently only ``PTP`` is supported." @@ -296,7 +296,7 @@ badRequest (400), itemNotFound (404), tiemout(408) :header: "Parameter", "Style", "Type", "Description" :widths: 20, 20, 20, 60 - "EventData", "plain", ""xsd:string, "Describes the synchronization state for PTP, State: ``Freerun``, ``Locked``, ``Holdover``." + "EventData", "plain", "xsd:string", "Describes the synchronization state for PTP, State: ``Freerun``, ``Locked``, ``Holdover``." "EventTimestamp", "plain", "xsd:float", "This is the time that the event was detected (elapsed seconds since epoch time)." "ResourceQualifier", "plain", "xsd:string", "The node name where PTP resides, ``NodeName``: ``*`` for all worker nodes, ``.`` for worker node where the application resides, ``node name`` specified by the downward API" "ResourceType", "plain", "xsd:string", "The resource to subscribe to, currently only ``PTP`` is supported." diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 01f9d83..9d6d977 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -4,6 +4,7 @@ API Definition for PTP Status Notifications API Reference for integrating StarlingX with an application that needs to receive PTP status notifications. Search PTP Notifications API content using the :ref:`search page `. + -------------- API definition -------------- @@ -11,4 +12,4 @@ API definition .. toctree:: :maxdepth: 2 - api_definition_v1_ptp_notifications + api_ptp_notifications_definition_v1 diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..9136f4f --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,4 @@ +openstackdocstheme>=2.2.1 # Apache-2.0 +os-api-ref>=1.4.0 # Apache-2.0 +reno>=3.1.0 # Apache-2.0 +sphinx>=2.0.0,!=2.1.0 # BSD \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..3c5e255 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,146 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# 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. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = u'PTP Status Notifications' +copyright = u'2018, StarlingX' +author = u'StarlingX' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'openstackdocstheme', +] + +# 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 master toctree document. +master_doc = 'index' + +# openstackdocstheme options +openstackdocs_repo_name = 'starlingx/ptp-notification-armada-app' +openstackdocs_use_storyboard = True +openstackdocs_auto_name = False + +# 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 + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'native' + + +# -- 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 = 'starlingxdocs' + +# 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 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'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'stx-configdoc' + + +# -- 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 = [ + ('index', 'stx-ptpnotifications-main.tex', u'stx-ptpnotifications Documentation', + u'StarlingX', 'manual'), +] + + +# -- 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, 'stx-config', u'stx-config Documentation', + [author], 1) +] diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..b9358b3 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,28 @@ +============================================= +StarlingX PTP Notification Armada App Project +============================================= + +The starlingx/ptp-notification-armada-app project provides a subscription +service for hosted applications to receive PTP status notifications from +the StarlingX platform. + +------------- +API reference +------------- + +.. toctree:: + :maxdepth: 1 + + API reference + +----- +Links +----- + +* Source: `starlingx/ptp-notification-armada-app`_ +* Code review: `Gerrit`_ +* Project tracking: `Storyboard`_ + +.. _starlingx/ptp-notification-armada-app: https://opendev.org/starlingx/ptp-notification-armada-app/ +.. _Gerrit: https://review.opendev.org/#/q/project:starlingx/ptp-notification-armada-app +.. _Storyboard: https://storyboard.openstack.org/#!/project/starlingx/ptp-notification-armada-app diff --git a/tox.ini b/tox.ini index cede375..02684f6 100644 --- a/tox.ini +++ b/tox.ini @@ -33,3 +33,21 @@ commands = [testenv:linters] commands = {[testenv:bashate]commands} + +[testenv:docs] +basepython = python3 +install_command = pip install -U {opts} {packages} +deps = -r{toxinidir}/doc/requirements.txt +commands = + rm -rf doc/build + sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html +whitelist_externals = rm + +[testenv:api-ref] +basepython = python3 +install_command = pip install -U {opts} {packages} +deps = -r{toxinidir}/doc/requirements.txt +commands = + rm -rf api-ref/build + sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html +whitelist_externals = rm