Changes to support conditionalizing rST 'substitutions'

Base set of substitutions added for organization name, product
names, document names amd rubrics.

This amendment adds a substitition for StarlingX OpenStack.

Change-Id: I236c193ae3a526a3903afa23a0a86db7d61f1244
Signed-off-by: Ron Stone <ronald.stone@windriver.com>

doc/source/conf.py

@@ -12,8 +12,8 @@
 # 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 os
-# import sys
+import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
 
@@ -71,6 +71,12 @@ openstackdocs_auto_name = False
 openstackdocs_bug_project = 'starlingx'
 openstackdocs_bug_tag = 'stx.docs'
 
+
+# Common substitution strings such as organization, product
+# and document names.
+rst_prolog = open('./shared/strings.txt', 'r').read()
+
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

doc/source/shared/strings.txt

@@ -0,0 +1,39 @@
+.. Common string substitutions for brand customization.
+.. NOTE: Do not use underscores in these substitution names.
+.. For more information, see
+.. https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions
+
+.. Organization name
+.. |org| replace:: StarlingX
+
+.. Short and long product names such as "StarlingX" and "Acme Co. StarlingX"
+.. |prod| replace:: StarlingX
+.. |prod-long| replace:: StarlingX
+.. |prod-os| replace:: StarlingX OpenStack
+
+.. Guide names, will be formatted in italics by default.
+.. |node-doc| replace:: :title:`StarlingX Node Configuration and Management`
+.. |planning-doc| replace:: :title:`StarlingX Planning`
+.. |sec-doc| replace:: :title:`StarlingX Security`
+.. |inst-doc| replace:: :title:`StarlingX Installation`
+.. |stor-doc| replace:: :title:`StarlingX Storage Configuration and Management`
+.. |intro-doc| replace:: :title:`StarlingX Introduction`
+.. |fault-doc| replace:: :title:`StarlingX Fault Management`
+.. |sysconf-doc| replace:: :title:`StarlingX System Configuration`
+.. |backup-doc| replace:: :title:`StarlingX Backup and Restore`
+.. |deploy-doc| replace:: :title:`StarlingX Deployment Configurations`
+.. |distcloud-doc| replace:: :title:`StarlingX Distributed Cloud`
+.. |usertasks-doc| replace:: :title:`StarlingX User Tasks`
+.. |admintasks-doc| replace:: :title:`StarlingX Administrator Tasks`
+.. |datanet-doc| replace:: :title:`StarlingX Data Networks`
+
+.. Task-oriented headings that should not appear in TOC
+.. These are used with the .. rubric:: directive. For example:
+.. .. rubric:: |postreq|
+
+.. |context| replace:: About this task
+.. |prereq| replace:: Prerequisites
+.. |proc| replace:: Procedure
+.. |postreq| replace:: Postrequisites
+.. |result| replace:: Results
+.. |eg| replace:: Example

tox.ini

@@ -16,7 +16,7 @@ deps =
   -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
   -r{toxinidir}/doc/requirements.txt
 commands =
-  sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html
+  sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html {posargs}
 
 [testenv:api-ref]
 deps = {[testenv:docs]deps}