Add RST Glossary

Automatically convert the glossary from DocBook XML to RST with each
build and use it for building the RST guides.

Add the glossary to User Guides and Networking Guide.

Use glossary in User Guides in places where it was used before. This
removes one TODO.

Fix CORS capitalization.

Partial-Bug: #1421813
Change-Id: I3fba6d54b01759f39f8e1467a7606cdbd2dd0165

.gitignore

@@ -10,6 +10,7 @@ target/
 /doc/user-guides/build-admin/
 build/
 /build-*.log.gz
+glossary.rst
 
 # Python compiled files
 *.pyc

doc/glossary/glossary-terms.xml

@@ -2120,9 +2120,9 @@
       </glossdef>
     </glossentry>
     <glossentry>
-      <glossterm>Cross-origin resource sharing (CORS)</glossterm>
+      <glossterm>Cross-Origin Resource Sharing (CORS)</glossterm>
       <indexterm class="singular">
-        <primary>Cross-origin resource sharing (CORS)</primary>
+        <primary>Cross-Origin Resource Sharing (CORS)</primary>
       </indexterm>
       <glossdef>
         <para>A mechanism that allows many resources (for example,

doc/networking-guide/source/index.rst

@@ -16,6 +16,8 @@ Contents:
    scenario-l3ha-ovs.rst
    scenario-ovs-providernet.rst
 
+   glossary.rst
+
 Indices and tables
 ==================
 

doc/user-guides/source/enduser/cli_create_and_manage_stacks.rst

@@ -8,8 +8,8 @@ Create and manage stacks
 The Orchestration module enables you to orchestrate multiple composite
 cloud applications. This module supports use of both the Amazon Web
 Services (AWS) CloudFormation template format through both a Query API
-that is compatible with CloudFormation and the native OpenStack Heat
-Orchestration Template (HOT) format through a REST API.
+that is compatible with CloudFormation and the native OpenStack
+:term:`Heat Orchestration Template (HOT)` format through a REST API.
 
 These flexible template languages enable application developers to
 describe and automate the deployment of infrastructure, services, and

doc/user-guides/source/enduser/cli_provide_user_data_to_instances.rst

@@ -7,7 +7,7 @@ Provide user data to instances
 
 A user data file is a special key in the metadata service that holds a
 file that cloud-aware applications in the guest instance can access. For
-example, one application that uses user data is the
+example, one application that uses :term:`user data` is the
 `cloud-init <https://help.ubuntu.com/community/CloudInit>`__ system,
 which is an open-source package from Ubuntu that is available on various
 Linux distributions and which handles early initialization of a cloud

doc/user-guides/source/enduser/dashboard_stacks.rst

@@ -10,10 +10,7 @@ orchestrate multiple composite cloud applications. This
 service supports the use of both the Amazon Web Services (AWS)
 CloudFormation template format through both a Query API that
 is compatible with CloudFormation and the native OpenStack
-Heat Orchestration Template (HOT) format through a REST API.
-
-.. TODO: (OL) Once glossary is available for .RST, add a link
-   to <glossterm>Heat Orchestration Template (HOT)</glossterm>
+:term:`Heat Orchestration Template (HOT)` format through a REST API.
 
 These flexible template languages enable application
 developers to describe and automate the deployment of

doc/user-guides/source/enduser/sdk_assign_cors_headers.rst

@@ -7,10 +7,10 @@
 Assign CORS headers to requests
 ===============================
 
-Cross-Origin Resource Sharing (CORS) is a specification that defines how
-browsers and servers communicate across origins by using HTTP headers,
-such as those assigned by Object Storage API requests. The Object
-Storage API supports the following headers:
+:term:`Cross-Origin Resource Sharing (CORS)` is a specification that
+defines how browsers and servers communicate across origins by using
+HTTP headers, such as those assigned by Object Storage API
+requests. The Object Storage API supports the following headers:
 
 - Access-Control-Allow-Credentials
 - Access-Control-Allow-Methods

doc/user-guides/source/index-admin.rst

@@ -28,6 +28,8 @@ Contents
 
    common/app_support.rst
 
+   glossary.rst
+
 Indices and tables
 ~~~~~~~~~~~~~~~~~~
 

doc/user-guides/source/index.rst

@@ -31,6 +31,8 @@ Contents
 
    common/app_support.rst
 
+   glossary.rst
+
 Indices and tables
 ~~~~~~~~~~~~~~~~~~
 

tools/build-user-guides.sh

@@ -1,5 +1,10 @@
 #!/bin/sh -e
 
+echo "Generating Glossary"
+echo "==================="
+tools/glossary2rst.py doc/user-guides/source/glossary.rst
+echo "Done."
+echo ""
 echo "Building End User Guide"
 echo "======================="
 sphinx-build -t user_only -E -W doc/user-guides/source/ doc/user-guides/build/html

tools/generatepot-rst.sh

@@ -30,6 +30,8 @@ if [ "$DOCNAME" = "user-guides" ] ; then
     OPTS="-t user_only -t admin_only"
 fi
 
+# Build Glossary
+tools/glossary2rst.py > doc/user-guides/source/glossary.rst
 # First remove the old pot file, otherwise the new file will contain
 # old references
 rm -f doc/$DOCNAME/source/locale/$DOCNAME.pot

tools/glossary2rst.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python
+
+# 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
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# 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.
+
+
+import re
+import sys
+
+from lxml import etree
+
+SKIP_TAGS = ['indexterm', 'info', 'primary', 'title']
+
+KNOWN_TAGS = [
+    'code',
+    'command',
+    'filename',
+    'link',
+    'literal',
+    'glossary',
+    'glossdef',
+    'glossdiv',
+    'glossentry',
+    'glossterm',
+    'para',
+    'phrase',
+    'systemitem',
+    'title'
+    ]
+
+# Marks the first glossdiv entry
+FIRST_GLOSSDIV = True
+
+
+def remove_indent(s):
+    """Remove indention of paragraph."""
+    s = "\n".join(i.lstrip() for i in s.splitlines())
+    return s
+
+
+def concat(element):
+    """Concatenate element and its children."""
+    s = ""
+    if element.text is not None:
+        s += remove_indent(element.text)
+    # Add all children
+    for i in element.getchildren():
+        s += convert(i)
+        if i.tail is not None:
+            if len(s) > 0 and not s[-1].isspace() and i.tail[0] in " \t":
+                s += i.tail[0]
+            s += remove_indent(i.tail)
+    return s
+
+
+def indent(element, indent):
+    """Indent paragraph."""
+    start = "\n\n"
+
+    lines = [" " * indent + i for i in concat(element).splitlines()
+             if i and not i.isspace()]
+    return start + "\n".join(lines)
+
+
+def link(element):
+    # Only handles the single link we need...
+    href = element.attrib['{http://www.w3.org/1999/xlink}href']
+    href = href.lstrip()
+    if href == "http://git.openstack.org/cgit/openstack/openstack-manuals":
+        s = ("`openstack/openstack-manuals repository " +
+             "<http://git.openstack.org/cgit/openstack/openstack-manuals>`__")
+        return s
+    print ("link not handled %s" % href)
+    sys.exit(1)
+
+
+def glossdiv(element):
+
+    s = ""
+    global FIRST_GLOSSDIV
+    if FIRST_GLOSSDIV:
+        s = '.. glossary::\n\n'
+        FIRST_GLOSSDIV = False
+
+    return s + concat(element)
+
+
+def glossentry(element):
+    s = "\n"
+    glossterm = element.find("{http://docbook.org/ns/docbook}glossterm")
+    if glossterm.text is not None:
+        s += "   " + glossterm.text + "\n"
+
+    glossdef = element.find("{http://docbook.org/ns/docbook}glossdef")
+    if glossdef is not None:
+        s += indent(glossdef, 6)
+    return s
+
+
+def convert(element):
+    if not isinstance(element.tag, basestring):
+        print("Element %s not handled, aborting!" % element.text)
+    tag = element.tag.replace('{http://docbook.org/ns/docbook}', '')
+    if tag in SKIP_TAGS:
+        return ""
+    if tag not in KNOWN_TAGS:
+        print("Tag %s not handled, aborting!" % tag)
+        sys.exit(1)
+    if tag == "command":
+        return ":command:`%s`" % element.text
+    if tag == "code":
+        return "`%s`" % element.text
+    if tag == "filename":
+        return ":file:`%s`" % element.text
+    if tag == "glossary":
+        return concat(element)
+    if tag == "glossdiv":
+        return glossdiv(element)
+    if tag == "glossentry":
+        return glossentry(element)
+    if tag == "link":
+        return link(element)
+    if tag == "literal":
+        return "`%s`" % element.text
+    if tag == "para":
+        return "\n\n" + concat(element)
+    if tag == "phrase":
+        return element.text
+    if tag == "systemitem":
+        return element.text
+
+    print("not handled tag %s - %s" % (element.tag, element.text))
+    sys.exit(1)
+
+
+def rst_convert(element):
+    output = convert(element)
+    # Replace multiple empty lines with single empty line
+    output = re.sub(r"\n{3,}", "\n\n", output)
+    return output
+
+
+def glossary_convert(filename):
+
+    try:
+        parser = etree.XMLParser(remove_comments=True)
+        doc = etree.parse(filename, parser=parser)
+    except etree.XMLSyntaxError as e:
+        print(" Warning: file %s is invalid XML: %s" % (filename, e))
+
+    rstcontent = rst_convert(doc.getroot()).encode('utf-8')
+    heading = "========\n" + "Glossary\n" + "========\n\n"
+    heading += ".. comments\n"
+    heading += "   This file file is automatically generated, edit the master"
+    heading += "   doc/glossary/glossary-terms.xml to update it."
+
+    if len(sys.argv) != 2:
+        print(heading + rstcontent)
+    else:
+        with open(sys.argv[1], 'w') as fp:
+            fp.write(heading)
+            fp.write(rstcontent)
+
+
+if __name__ == '__main__':
+    glossary_convert("doc/glossary/glossary-terms.xml")

tox.ini

@@ -54,6 +54,7 @@ commands =
   mkdir -p publish-docs/draft/user-guide-admin/content/
   rsync -a doc/user-guides/build-admin/html/ publish-docs/draft/user-guide-admin/content/
   # Build RST networking guide
+  {toxinidir}/tools/glossary2rst.py doc/networking-guide/source/glossary.rst
   sphinx-build -E -W doc/networking-guide/source doc/networking-guide/build/html
   mkdir -p publish-docs/networking-guide/content/
   rsync -a doc/networking-guide/build/html/ publish-docs/networking-guide/content/
@@ -63,10 +64,13 @@ commands =
 [testenv:docs]
 commands = 
   {toxinidir}/tools/build-user-guides.sh
+  {toxinidir}/tools/glossary2rst.py doc/networking-guide/source/glossary.rst
   sphinx-build -W doc/networking-guide/source doc/networking-guide/build/html
 
 [testenv:network]
-commands = sphinx-build -W doc/networking-guide/source doc/networking-guide/build/html
+commands = 
+  {toxinidir}/tools/glossary2rst.py doc/networking-guide/source/glossary.rst
+  sphinx-build -W doc/networking-guide/source doc/networking-guide/build/html
 
 [testenv:publishdocs]
 # Prepare all documents (except www subdir) so that they can get