Add starlingxdocs theme support

At the PTG the Docs team and dhellmann decided that openstackdocstheme
was the proper place to keep the modifications required to build
a theme for StarlingX and other OpenStack Foundation-related projects.

This is a minimal set of changes to support a second theme with a couple
of visual changes thrown in to make obvious that the correct theme
is being used. The remainder of the visual work will follow.
Both PNG and SVG versions of the logo are included.

Add an additional jobs to build the docs and PDF with the new theme.

Modify the wording in README.rst and the docs index page regarding
the distinction between openstackdocstheme the module and openstackdocs
and starlingxdocs the themes and their intended uses.

There are a number of hard-coded OpenStack-isms that will eventually
need to be addressed.

Change-Id: I594136a0ea66d61f60dafc6a853137470efc7d42
Signed-off-by: Dean Troyer <dtroyer@gmail.com>

.zuul.yaml

@@ -5,6 +5,17 @@
     vars:
       tox_envlist: buildpdf
 
+- job:
+    name: openstackdocsstheme-tox-manuals-buildpdf-starlingxpdf
+    parent: build-tox-manuals-base
+    vars:
+      tox_envlist: buildpdf-starlingxdocs
+
+- job:
+    name: openstack-tox-docs-starlingxdocs
+    parent: openstack-tox-docs
+    vars:
+      tox_envlist: docs-starlingxdocs
 
 - project:
     templates:
@@ -14,6 +25,7 @@
     check:
       jobs:
         - openstackdocsstheme-tox-manuals-buildpdf
+        - openstackdocsstheme-tox-manuals-buildpdf-starlingxpdf
         - openstack-tox-pep8
         - build-openstack-api-ref:
             # Override files section of the job so that this builds
@@ -25,9 +37,12 @@
               - ^openstackdocstheme/.*$
               - ^.*\.txt$
               - ^.*\.rst$
+        # Run the docs build using the starlingxdocs theme
+        - openstack-tox-docs-starlingxdocs
     gate:
       jobs:
         - openstackdocsstheme-tox-manuals-buildpdf
+        - openstackdocsstheme-tox-manuals-buildpdf-starlingxpdf
         - openstack-tox-pep8
         - build-openstack-api-ref:
             files:
@@ -37,6 +52,7 @@
               - ^openstackdocstheme/.*$
               - ^.*\.txt$
               - ^.*\.rst$
+        - openstack-tox-docs-starlingxdocs
     post:
       jobs:
         - publish-openstack-python-branch-tarball

README.rst

@@ -7,16 +7,35 @@ Team and repository tags
 
 .. Change things from this point on
 
-OpenStack docs.openstack.org Sphinx Theme
-=========================================
+OpenStack Foundation Sphinx Themes
+==================================
 
-Theme and extension support for Sphinx documentation that is published to
+Theme and extension support for Sphinx documentation that is published by
+OpenStack Foundation projects.
+
+OpenStack docs.openstack.org Sphinx Theme
+-----------------------------------------
+
+Theme support for Sphinx documentation that is published to
 docs.openstack.org and developer.openstack.org.
 
 Intended for use by OpenStack `projects governed by the Technical Committee`_.
 
 .. _`projects governed by the Technical Committee`: https://governance.openstack.org/tc/reference/projects/index.html
 
+StarlingX docs.starlingx.io Sphinx Theme
+-----------------------------------------
+
+Theme support for Sphinx documentation that is published to
+docs.starlingx.io.
+
+Intended for use by StarlingX `projects governed by the Technical Steering Committee`_.
+
+.. _`projects governed by the Technical Steering Committee`: https://docs.starlingx.io/governance/reference/projects/index.html
+
+References
+----------
+
 * Free software: Apache License, Version 2.0
 * Documentation: https://docs.openstack.org/openstackdocstheme/latest/
 * Release notes: https://docs.openstack.org/releasenotes/openstackdocstheme/

doc/source/index.rst

@@ -1,14 +1,20 @@
-===========================================
- OpenStack docs.openstack.org Sphinx theme
-===========================================
+=========================
+ OpenStack Sphinx themes
+=========================
 
-*openstackdocstheme* is a theme and extension support for Sphinx documentation
-that is published to docs.openstack.org and developer.openstack.org.
+*openstackdocstheme* is a Sphinx documentation extension that includes
+theme support for OpenStack Foundation projects.
 
-It is intended for use by OpenStack `projects governed by the Technical
-Committee`_.
+The *openstackdocs* theme is used for documentation that is published
+to docs.openstack.org and developer.openstack.org. It is intended for
+use by OpenStack `projects governed by the Technical Committee`_.
+
+The *starlingxdocs* theme is used for documentation that is published
+to docs.starlingx.io. It is intended for use by StarlingX
+`projects governed by the Technical Steering Committee`_.
 
 .. _`projects governed by the Technical Committee`: https://governance.openstack.org/reference/projects/index.html
+.. _`projects governed by the Technical Steering Committee`: https://docs.starlingx.io/governance/reference/projects/index.html
 
 Using the theme
 ---------------

openstackdocstheme/ext.py

@@ -277,7 +277,7 @@ def _builder_inited(app):
 
     # we only override configuration if the theme has been configured, meaning
     # users are using these features
-    if app.config.html_theme != 'openstackdocs':
+    if app.config.html_theme not in ['openstackdocs', 'starlingxdocs']:
         return
 
     # TODO(stephenfin): Once Sphinx 1.8 is released, we should move the below
@@ -302,8 +302,8 @@ def _builder_inited(app):
         app.config.version = version
         app.config.release = version
 
-    openstack_logo = paths.get_openstack_logo_path()
-    pdf_theme_path = paths.get_pdf_theme_path()
+    theme_logo = paths.get_theme_logo_path(app.config.html_theme)
+    pdf_theme_path = paths.get_pdf_theme_path(app.config.html_theme)
 
     app.config.latex_engine = 'xelatex'
     app.config.latex_elements = {
@@ -313,7 +313,7 @@ def _builder_inited(app):
         'classoptions': ',openany',
         'preamble': r"""
 \usepackage{""" + pdf_theme_path + """}
-\\newcommand{\openstacklogo}{""" + openstack_logo + """}
+\\newcommand{\openstacklogo}{""" + theme_logo + """}
 """}
 
 
@@ -330,6 +330,10 @@ def setup(app):
         'openstackdocs',
         os.path.abspath(os.path.dirname(__file__)) + '/theme/openstackdocs',
     )
+    app.add_html_theme(
+        'starlingxdocs',
+        os.path.abspath(os.path.dirname(__file__)) + '/theme/starlingxdocs',
+    )
     return {
         'parallel_read_safe': True,
     }

openstackdocstheme/paths.py

@@ -24,13 +24,13 @@ def get_html_theme_path():
     return os.path.join(get_pkg_path(), 'theme')
 
 
-def get_pdf_theme_path():
+def get_pdf_theme_path(theme):
     """Return the directory containing PDF theme for local builds."""
-    args = ['theme', 'openstackdocs_pdf', 'pdftheme']
+    args = ['theme', theme + '_pdf', 'pdftheme']
     return os.path.join(get_pkg_path(), *args)
 
 
-def get_openstack_logo_path():
-    """Return the directory containing openstack logo for local builds."""
-    args = ['theme', 'openstackdocs_pdf', 'openstack-logo-full.png']
+def get_theme_logo_path(theme):
+    """Return the directory containing theme logo for local builds."""
+    args = ['theme', theme + '_pdf', 'logo-full.png']
     return os.path.join(get_pkg_path(), *args)

openstackdocstheme/theme/openstackdocs/static/images/logo-full.png

@@ -0,0 +1 @@
+openstack-logo-full.png

openstackdocstheme/theme/openstackdocs/static/images/logo-vert.png

@@ -0,0 +1 @@
+openstack-logo-vert.png

openstackdocstheme/theme/starlingxdocs/static/images/StarlingX_Logo_RGB_Horizontal_2color.svg

@@ -0,0 +1 @@
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 168.39 36"><defs><style>.cls-1{fill:#685bc7;}.cls-2{fill:#330072;}</style></defs><title>StarlingX_Logo_RGB_Horizontal_2color</title><polygon class="cls-1" points="19.53 7.03 14.26 0 0 0 12.4 16.53 19.53 7.03"/><path class="cls-1" d="M78.17,78.48,86.8,90h14.26L88.6,73.38A16.76,16.76,0,0,1,78.17,78.48Z" transform="translate(-59.8 -54)"/><path class="cls-2" d="M91.71,54a9.23,9.23,0,0,0-7.24,3.11L73.71,71.46c6.4,0,7.69-1,11.6-6.1l.82-1.1a4.34,4.34,0,0,1,3.49-1.76l-2.9,3.93c-4.26,5.51-6,6.79-13.43,6.79H72.4L59.8,90h3.09a9.37,9.37,0,0,0,6.72-3.08l7.62-10.17h.11a14.79,14.79,0,0,0,11.08-5.89l7.8-10.41a15.94,15.94,0,0,1,4.84-4.07,26.77,26.77,0,0,0-5.29-1.32C94.53,54,91.71,54,91.71,54Z" transform="translate(-59.8 -54)"/><path class="cls-2" d="M110.88,70.86c-2-.52-2.51-.77-2.51-1.53v0c0-.57.51-1,1.49-1a5.49,5.49,0,0,1,3,1.15l1.33-1.93A6.75,6.75,0,0,0,109.9,66c-2.38,0-4.07,1.39-4.07,3.5v0c0,2.31,1.51,3,3.85,3.55,1.94.5,2.34.83,2.34,1.48v0c0,.68-.63,1.1-1.68,1.1a5.33,5.33,0,0,1-3.46-1.41l-1.51,1.8A7.35,7.35,0,0,0,110.29,78c2.51,0,4.27-1.29,4.27-3.6v0C114.56,72.32,113.23,71.47,110.88,70.86Z" transform="translate(-59.8 -54)"/><polygon class="cls-2" points="59.06 14.55 62.59 14.55 62.59 23.81 65.15 23.81 65.15 14.55 68.68 14.55 68.68 12.19 59.06 12.19 59.06 14.55"/><path class="cls-2" d="M136.09,66.11l-5,11.7h2.61l1.06-2.61h4.91l1.06,2.61h2.67l-5-11.7Zm-.4,6.84,1.55-3.77L138.78,73Z" transform="translate(-59.8 -54)"/><path class="cls-2" d="M158.06,70.06v0a3.64,3.64,0,0,0-1-2.66,4.65,4.65,0,0,0-3.39-1.18h-5.3V77.81h2.55V74.09h2l2.49,3.72h3l-2.83-4.15A3.61,3.61,0,0,0,158.06,70.06Zm-2.58.13c0,1-.72,1.64-2,1.64h-2.59V68.5h2.54c1.24,0,2,.56,2,1.66Z" transform="translate(-59.8 -54)"/><polygon class="cls-2" points="106.28 12.19 103.73 12.19 103.73 23.81 112.07 23.81 112.07 21.48 106.28 21.48 106.28 12.19"/><rect class="cls-2" x="117.27" y="12.19" width="2.55" height="11.61"/><polygon class="cls-2" points="133.68 19.34 128.24 12.19 125.89 12.19 125.89 23.81 128.41 23.81 128.41 16.42 134.03 23.81 136.21 23.81 136.21 12.19 133.68 12.19 133.68 19.34"/><path class="cls-2" d="M207.47,73.33H210V75a4.12,4.12,0,0,1-2.41.69A3.48,3.48,0,0,1,204.12,72v0a3.48,3.48,0,0,1,3.33-3.62,4.29,4.29,0,0,1,3,1.18l1.6-1.94a6.37,6.37,0,0,0-4.56-1.6,6,6,0,0,0-6.09,6v0a5.82,5.82,0,0,0,6.11,6,7.52,7.52,0,0,0,5-1.85v-5h-5Z" transform="translate(-59.8 -54)"/><polygon class="cls-2" points="164.34 17.87 168.22 12.19 165.32 12.19 162.85 15.96 160.43 12.19 157.44 12.19 161.32 17.9 157.28 23.81 160.18 23.81 162.8 19.83 165.41 23.81 168.39 23.81 164.34 17.87"/></svg>

openstackdocstheme/theme/starlingxdocs/static/images/StarlingX_Logo_RGB_Stacked_2color.svg

@@ -0,0 +1 @@
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 123.51 144"><defs><style>.cls-1{fill:#330072;}.cls-2{fill:#685bc7;}</style></defs><title>StarlingX_Logo_RGB_Stacked_2color</title><path class="cls-1" d="M87.79,208.81c-2-.52-2.52-.77-2.52-1.53v0c0-.56.51-1,1.5-1a5.44,5.44,0,0,1,3,1.15l1.34-1.94A6.78,6.78,0,0,0,86.8,204c-2.38,0-4.09,1.4-4.09,3.52v0c0,2.32,1.52,3,3.87,3.57,2,.5,2.36.83,2.36,1.48v0c0,.68-.64,1.1-1.69,1.1a5.34,5.34,0,0,1-3.48-1.42l-1.52,1.82a7.42,7.42,0,0,0,5,1.87c2.52,0,4.29-1.3,4.29-3.62v0C91.49,210.28,90.15,209.43,87.79,208.81Z" transform="translate(-82.25 -72)"/><polygon class="cls-1" points="13.57 134.49 17.12 134.49 17.12 143.8 19.69 143.8 19.69 134.49 23.25 134.49 23.25 132.12 13.57 132.12 13.57 134.49"/><path class="cls-1" d="M113.14,204l-5,11.76h2.61l1.07-2.62h4.94l1.07,2.62h2.68l-5-11.76Zm-.4,6.87,1.55-3.78,1.55,3.78Z" transform="translate(-82.25 -72)"/><path class="cls-1" d="M135.24,208v0a3.68,3.68,0,0,0-1-2.67,4.62,4.62,0,0,0-3.4-1.19h-5.34V215.8h2.57v-3.74h2l2.5,3.74h3l-2.86-4.17A3.63,3.63,0,0,0,135.24,208Zm-2.61.13c0,1-.71,1.66-2,1.66h-2.6v-3.36h2.55c1.26,0,2,.57,2,1.67Z" transform="translate(-82.25 -72)"/><polygon class="cls-1" points="61.05 132.12 58.49 132.12 58.49 143.8 66.88 143.8 66.88 141.47 61.05 141.47 61.05 132.12"/><rect class="cls-1" x="72.11" y="132.12" width="2.57" height="11.68"/><polygon class="cls-1" points="88.61 139.31 83.14 132.12 80.77 132.12 80.77 143.8 83.3 143.8 83.3 136.38 88.96 143.8 91.14 143.8 91.14 132.12 88.61 132.12 88.61 139.31"/><path class="cls-1" d="M184.91,211.3h2.59V213a4.09,4.09,0,0,1-2.42.71,3.5,3.5,0,0,1-3.54-3.71v0a3.5,3.5,0,0,1,3.35-3.64,4.31,4.31,0,0,1,3.06,1.19l1.61-2a6.4,6.4,0,0,0-4.58-1.6,6,6,0,0,0-6.13,6v0a5.85,5.85,0,0,0,6.14,6,7.56,7.56,0,0,0,5-1.85v-5.07h-5.07Z" transform="translate(-82.25 -72)"/><polygon class="cls-1" points="123.34 132.12 120.42 132.12 117.94 135.91 115.5 132.12 112.5 132.12 116.4 137.86 112.33 143.8 115.25 143.8 117.89 139.8 120.5 143.8 123.51 143.8 119.44 137.83 123.34 132.12"/><polygon class="cls-2" points="58.46 21.04 42.68 0 0 0 37.12 49.49 58.46 21.04"/><path class="cls-2" d="M137.22,145.3l25.85,34.47h42.68L168.44,130C160.24,138.61,148.31,144.52,137.22,145.3Z" transform="translate(-82.25 -72)"/><path class="cls-1" d="M111.59,170.56l22.84-30.45h.32c11.81,0,25.65-7.32,33.15-17.64l23.37-31.16a47.48,47.48,0,0,1,14.48-12.17c-6.28-2.61-15.84-4-15.84-4C186.21,72,177.76,72,177.76,72c-14.69,0-21.67,9.31-21.67,9.31l-32.21,43c19.16-.12,23-3.08,34.73-18.24l2.45-3.32a13,13,0,0,1,10.46-5.27l-8.71,11.77c-12.75,16.49-18,20.34-40.18,20.34-.93,0-1.82,0-2.69,0L82.25,179.77h9.24C98.54,179.77,107.14,176,111.59,170.56Z" transform="translate(-82.25 -72)"/></svg>

openstackdocstheme/theme/starlingxdocs/static/images/logo-full.png

@@ -0,0 +1 @@
+StarlingX_Logo_RGB_Horizontal_2color.png

openstackdocstheme/theme/starlingxdocs/static/images/logo-full.svg

@@ -0,0 +1 @@
+StarlingX_Logo_RGB_Horizontal_2color.svg

openstackdocstheme/theme/starlingxdocs/static/images/logo-vert.png

@@ -0,0 +1 @@
+StarlingX_Logo_RGB_Stacked_2color.png

openstackdocstheme/theme/starlingxdocs/static/images/logo-vert.svg

@@ -0,0 +1 @@
+StarlingX_Logo_RGB_Stacked_2color.svg

openstackdocstheme/theme/starlingxdocs/theme.conf

@@ -0,0 +1,14 @@
+[theme]
+inherit = openstackdocs
+stylesheet = css/basic.css
+pygments_style = native
+
+[options]
+#analytics_tracking_code = UA-17511903-1
+sidebar_mode = toctree
+display_badge = True
+display_toc = True
+display_global_toc_section = True
+root_title = StarlingX Docs
+sidebar_dropdown = os_docs
+show_other_versions = False

openstackdocstheme/theme/starlingxdocs_pdf/logo-full.png

@@ -0,0 +1 @@
+../starlingxdocs/static/images/StarlingX_Logo_RGB_Horizontal_2color.png

openstackdocstheme/theme/starlingxdocs_pdf/logo-full.svg

@@ -0,0 +1 @@
+../starlingxdocs/static/images/StarlingX_Logo_RGB_Horizontal_2color.svg

openstackdocstheme/theme/starlingxdocs_pdf/pdftheme.sty

@@ -0,0 +1,67 @@
+\makeatletter
+
+% Do not print release information if empty
+% Note: Sphinx does support version variable in conf.py to latex yet
+\def \ifempty#1{\def\temp{#1} \ifx\temp\empty }
+\renewcommand{\release}[1]{
+   \ifempty{#1}
+     \newcommand{\osreleasetitle}{}
+     \newcommand{\osreleaseheader}{}
+   \else
+     \newcommand{\osreleasetitle}{\LARGE Release Version: #1\newline}
+     \newcommand{\osreleaseheader}{\space\small\nouppercase{(Release Version: #1)}}
+   \fi
+}
+
+% Defines title page
+\renewcommand{\maketitle}{
+  \begin{titlepage}
+    \begin{flushleft}
+       \includegraphics[width=3.5cm, height=0.8cm]{\openstacklogo}
+    \end{flushleft}
+    \vskip 6em%
+    \begin{center}
+       % Document title
+       {\Huge \textbf \@title}
+    \end{center}
+
+    \begin{flushright}
+       % Expect align right but center
+       \vskip 2em%
+       % RELEASE VERSION
+       {\osreleasetitle}
+    \end{flushright}
+
+    \vskip 6em%
+
+    \begin{flushright}
+       % Author
+       {\LARGE \@author}
+       \vskip 20em%
+       % Creation date
+       {\Large \@date}
+    \end{flushright}
+  \end{titlepage}
+}
+
+% Customizes page header & footer for OpenStack
+\fancypagestyle{normal}{
+  \fancyhf{}
+  \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
+  \fancyfoot[RE,LO]{{\py@HeaderFamily\nouppercase\rightmark}}
+  \fancyhead[LE,RO]{{\py@HeaderFamily\@title\osreleaseheader}}
+  \fancyhead[RE,LO]{{\py@HeaderFamily\includegraphics[width=3.5cm, height=0.8cm]{\openstacklogo}}}
+}
+
+% Customizes colors
+\definecolor{VerbatimColor}{rgb}{.95,.95,.95}
+
+% Do not use chapter and section number
+\setcounter{secnumdepth}{-1}
+
+% Font selection (English)
+\usepackage{fontspec}
+\defaultfontfeatures{Scale=MatchLowercase}
+\setmainfont{Liberation Serif}
+\setsansfont{Liberation Sans}
+\setmonofont[SmallCapsFont={Liberation Mono}]{Liberation Mono}

releasenotes/notes/add-starlingxdocs-10a33318f8630486.yaml

@@ -0,0 +1,11 @@
+---
+features:
+  - |
+    Add support for additional themes is included in the package.  The
+    first theme is ``starlingxdocs``.  The initial implementation sets up
+    the new theme to inherit from ``openstackdocs`` and updates some of
+    the ``openstackdocs`` bits that are hard coded in the Python.
+
+    For example::
+
+        html_theme = 'starlingxdocs'

tox.ini

@@ -31,6 +31,12 @@ commands =
   rm -rf doc/build api-ref/build
   sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html
 
+[testenv:docs-starlingxdocs]
+basepython = python3
+commands =
+  rm -rf doc/build api-ref/build
+  sphinx-build -a -E -W -d doc/build/doctrees -b html -D html_theme=starlingxdocs doc/source doc/build/html
+
 [testenv:html]
 commands =
   rm -rf doc/build api-ref/build
@@ -49,7 +55,6 @@ commands =
   rm -rf api-ref/build
   sphinx-build -a -E -W -d api-ref/build/doctrees -b html api-ref/source api-ref/build/html
 
-
 [testenv:buildpdf]
 # Only build PDF and push it to publish-docs folder so that OpenStack
 # CI jobs will publish it.
@@ -63,6 +68,19 @@ commands =
   mkdir -p publish-docs
   cp doc/build/pdf/os-doc-demo.pdf publish-docs
 
+[testenv:buildpdf-starlingxdocs]
+# Only build PDF and push it to publish-docs folder so that OpenStack
+# CI jobs will publish it.
+whitelist_externals =
+  make
+  cp
+  mkdir
+commands =
+  sphinx-build -a -E -W -d doc/build/doctrees -b latex -D html_theme=starlingxdocs doc/source doc/build/pdf
+  make -C doc/build/pdf
+  mkdir -p publish-docs
+  cp doc/build/pdf/os-doc-demo.pdf publish-docs
+
 [testenv:bindep]
 # Do not install any requirements. We want this to be fast and work even if
 # system dependencies are missing, since it's used to tell you what system