From a8224a68b591f878f7ad6408fe8186ab8a34f0fc Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Sun, 12 Apr 2015 14:07:01 +0200 Subject: [PATCH] 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 | 1 + doc/glossary/glossary-terms.xml | 4 +- doc/networking-guide/source/index.rst | 2 + .../enduser/cli_create_and_manage_stacks.rst | 4 +- .../cli_provide_user_data_to_instances.rst | 2 +- .../source/enduser/dashboard_stacks.rst | 5 +- .../enduser/sdk_assign_cors_headers.rst | 8 +- doc/user-guides/source/index-admin.rst | 2 + doc/user-guides/source/index.rst | 2 + tools/build-user-guides.sh | 5 + tools/generatepot-rst.sh | 2 + tools/glossary2rst.py | 175 ++++++++++++++++++ tox.ini | 6 +- 13 files changed, 204 insertions(+), 14 deletions(-) create mode 100755 tools/glossary2rst.py diff --git a/.gitignore b/.gitignore index 554853c9e3..cc2ecab379 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ target/ /doc/user-guides/build-admin/ build/ /build-*.log.gz +glossary.rst # Python compiled files *.pyc diff --git a/doc/glossary/glossary-terms.xml b/doc/glossary/glossary-terms.xml index 3708376daf..d76886fbae 100644 --- a/doc/glossary/glossary-terms.xml +++ b/doc/glossary/glossary-terms.xml @@ -2120,9 +2120,9 @@ - Cross-origin resource sharing (CORS) + Cross-Origin Resource Sharing (CORS) - Cross-origin resource sharing (CORS) + Cross-Origin Resource Sharing (CORS) A mechanism that allows many resources (for example, diff --git a/doc/networking-guide/source/index.rst b/doc/networking-guide/source/index.rst index 5cc4973196..a3340fd247 100644 --- a/doc/networking-guide/source/index.rst +++ b/doc/networking-guide/source/index.rst @@ -16,6 +16,8 @@ Contents: scenario-l3ha-ovs.rst scenario-ovs-providernet.rst + glossary.rst + Indices and tables ================== diff --git a/doc/user-guides/source/enduser/cli_create_and_manage_stacks.rst b/doc/user-guides/source/enduser/cli_create_and_manage_stacks.rst index c8d75a3b2a..c7833b4d99 100644 --- a/doc/user-guides/source/enduser/cli_create_and_manage_stacks.rst +++ b/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 diff --git a/doc/user-guides/source/enduser/cli_provide_user_data_to_instances.rst b/doc/user-guides/source/enduser/cli_provide_user_data_to_instances.rst index 6e686a2096..f834fb9a32 100644 --- a/doc/user-guides/source/enduser/cli_provide_user_data_to_instances.rst +++ b/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 `__ system, which is an open-source package from Ubuntu that is available on various Linux distributions and which handles early initialization of a cloud diff --git a/doc/user-guides/source/enduser/dashboard_stacks.rst b/doc/user-guides/source/enduser/dashboard_stacks.rst index e9d612b777..ab8773715c 100644 --- a/doc/user-guides/source/enduser/dashboard_stacks.rst +++ b/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 Heat Orchestration Template (HOT) +:term:`Heat Orchestration Template (HOT)` format through a REST API. These flexible template languages enable application developers to describe and automate the deployment of diff --git a/doc/user-guides/source/enduser/sdk_assign_cors_headers.rst b/doc/user-guides/source/enduser/sdk_assign_cors_headers.rst index 792161c681..2dc35c6c2c 100644 --- a/doc/user-guides/source/enduser/sdk_assign_cors_headers.rst +++ b/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 diff --git a/doc/user-guides/source/index-admin.rst b/doc/user-guides/source/index-admin.rst index c12cba0b6d..af34a2bd9f 100644 --- a/doc/user-guides/source/index-admin.rst +++ b/doc/user-guides/source/index-admin.rst @@ -28,6 +28,8 @@ Contents common/app_support.rst + glossary.rst + Indices and tables ~~~~~~~~~~~~~~~~~~ diff --git a/doc/user-guides/source/index.rst b/doc/user-guides/source/index.rst index 94d5cb0d15..adfb626bda 100644 --- a/doc/user-guides/source/index.rst +++ b/doc/user-guides/source/index.rst @@ -31,6 +31,8 @@ Contents common/app_support.rst + glossary.rst + Indices and tables ~~~~~~~~~~~~~~~~~~ diff --git a/tools/build-user-guides.sh b/tools/build-user-guides.sh index 830e62672d..f552521922 100755 --- a/tools/build-user-guides.sh +++ b/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 diff --git a/tools/generatepot-rst.sh b/tools/generatepot-rst.sh index 036e649c9d..119a8f10e8 100755 --- a/tools/generatepot-rst.sh +++ b/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 diff --git a/tools/glossary2rst.py b/tools/glossary2rst.py new file mode 100755 index 0000000000..e25fbb6f51 --- /dev/null +++ b/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 " + + "`__") + 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") diff --git a/tox.ini b/tox.ini index 95094a72d2..4a3b523186 100644 --- a/tox.ini +++ b/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