Merge "Add RST Glossary"
This commit is contained in:
commit
d7d7d8ee7c
1
.gitignore
vendored
1
.gitignore
vendored
@ -10,6 +10,7 @@ target/
|
|||||||
/doc/user-guides/build-admin/
|
/doc/user-guides/build-admin/
|
||||||
build/
|
build/
|
||||||
/build-*.log.gz
|
/build-*.log.gz
|
||||||
|
glossary.rst
|
||||||
|
|
||||||
# Python compiled files
|
# Python compiled files
|
||||||
*.pyc
|
*.pyc
|
||||||
|
@ -2120,9 +2120,9 @@
|
|||||||
</glossdef>
|
</glossdef>
|
||||||
</glossentry>
|
</glossentry>
|
||||||
<glossentry>
|
<glossentry>
|
||||||
<glossterm>Cross-origin resource sharing (CORS)</glossterm>
|
<glossterm>Cross-Origin Resource Sharing (CORS)</glossterm>
|
||||||
<indexterm class="singular">
|
<indexterm class="singular">
|
||||||
<primary>Cross-origin resource sharing (CORS)</primary>
|
<primary>Cross-Origin Resource Sharing (CORS)</primary>
|
||||||
</indexterm>
|
</indexterm>
|
||||||
<glossdef>
|
<glossdef>
|
||||||
<para>A mechanism that allows many resources (for example,
|
<para>A mechanism that allows many resources (for example,
|
||||||
|
@ -16,6 +16,8 @@ Contents:
|
|||||||
scenario-l3ha-ovs.rst
|
scenario-l3ha-ovs.rst
|
||||||
scenario-ovs-providernet.rst
|
scenario-ovs-providernet.rst
|
||||||
|
|
||||||
|
glossary.rst
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
==================
|
==================
|
||||||
|
|
||||||
|
@ -8,8 +8,8 @@ Create and manage stacks
|
|||||||
The Orchestration module enables you to orchestrate multiple composite
|
The Orchestration module enables you to orchestrate multiple composite
|
||||||
cloud applications. This module supports use of both the Amazon Web
|
cloud applications. This module supports use of both the Amazon Web
|
||||||
Services (AWS) CloudFormation template format through both a Query API
|
Services (AWS) CloudFormation template format through both a Query API
|
||||||
that is compatible with CloudFormation and the native OpenStack Heat
|
that is compatible with CloudFormation and the native OpenStack
|
||||||
Orchestration Template (HOT) format through a REST API.
|
:term:`Heat Orchestration Template (HOT)` format through a REST API.
|
||||||
|
|
||||||
These flexible template languages enable application developers to
|
These flexible template languages enable application developers to
|
||||||
describe and automate the deployment of infrastructure, services, and
|
describe and automate the deployment of infrastructure, services, and
|
||||||
|
@ -7,7 +7,7 @@ Provide user data to instances
|
|||||||
|
|
||||||
A user data file is a special key in the metadata service that holds a
|
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
|
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,
|
`cloud-init <https://help.ubuntu.com/community/CloudInit>`__ system,
|
||||||
which is an open-source package from Ubuntu that is available on various
|
which is an open-source package from Ubuntu that is available on various
|
||||||
Linux distributions and which handles early initialization of a cloud
|
Linux distributions and which handles early initialization of a cloud
|
||||||
|
@ -10,10 +10,7 @@ orchestrate multiple composite cloud applications. This
|
|||||||
service supports the use of both the Amazon Web Services (AWS)
|
service supports the use of both the Amazon Web Services (AWS)
|
||||||
CloudFormation template format through both a Query API that
|
CloudFormation template format through both a Query API that
|
||||||
is compatible with CloudFormation and the native OpenStack
|
is compatible with CloudFormation and the native OpenStack
|
||||||
Heat Orchestration Template (HOT) format through a REST API.
|
:term:`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>
|
|
||||||
|
|
||||||
These flexible template languages enable application
|
These flexible template languages enable application
|
||||||
developers to describe and automate the deployment of
|
developers to describe and automate the deployment of
|
||||||
|
@ -7,10 +7,10 @@
|
|||||||
Assign CORS headers to requests
|
Assign CORS headers to requests
|
||||||
===============================
|
===============================
|
||||||
|
|
||||||
Cross-Origin Resource Sharing (CORS) is a specification that defines how
|
:term:`Cross-Origin Resource Sharing (CORS)` is a specification that
|
||||||
browsers and servers communicate across origins by using HTTP headers,
|
defines how browsers and servers communicate across origins by using
|
||||||
such as those assigned by Object Storage API requests. The Object
|
HTTP headers, such as those assigned by Object Storage API
|
||||||
Storage API supports the following headers:
|
requests. The Object Storage API supports the following headers:
|
||||||
|
|
||||||
- Access-Control-Allow-Credentials
|
- Access-Control-Allow-Credentials
|
||||||
- Access-Control-Allow-Methods
|
- Access-Control-Allow-Methods
|
||||||
|
@ -28,6 +28,8 @@ Contents
|
|||||||
|
|
||||||
common/app_support.rst
|
common/app_support.rst
|
||||||
|
|
||||||
|
glossary.rst
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
@ -31,6 +31,8 @@ Contents
|
|||||||
|
|
||||||
common/app_support.rst
|
common/app_support.rst
|
||||||
|
|
||||||
|
glossary.rst
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
@ -1,5 +1,10 @@
|
|||||||
#!/bin/sh -e
|
#!/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 "Building End User Guide"
|
||||||
echo "======================="
|
echo "======================="
|
||||||
sphinx-build -t user_only -E -W doc/user-guides/source/ doc/user-guides/build/html
|
sphinx-build -t user_only -E -W doc/user-guides/source/ doc/user-guides/build/html
|
||||||
|
@ -30,6 +30,8 @@ if [ "$DOCNAME" = "user-guides" ] ; then
|
|||||||
OPTS="-t user_only -t admin_only"
|
OPTS="-t user_only -t admin_only"
|
||||||
fi
|
fi
|
||||||
|
|
||||||
|
# Build Glossary
|
||||||
|
tools/glossary2rst.py > doc/user-guides/source/glossary.rst
|
||||||
# First remove the old pot file, otherwise the new file will contain
|
# First remove the old pot file, otherwise the new file will contain
|
||||||
# old references
|
# old references
|
||||||
rm -f doc/$DOCNAME/source/locale/$DOCNAME.pot
|
rm -f doc/$DOCNAME/source/locale/$DOCNAME.pot
|
||||||
|
175
tools/glossary2rst.py
Executable file
175
tools/glossary2rst.py
Executable file
@ -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")
|
6
tox.ini
6
tox.ini
@ -54,6 +54,7 @@ commands =
|
|||||||
mkdir -p publish-docs/draft/user-guide-admin/content/
|
mkdir -p publish-docs/draft/user-guide-admin/content/
|
||||||
rsync -a doc/user-guides/build-admin/html/ 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
|
# 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
|
sphinx-build -E -W doc/networking-guide/source doc/networking-guide/build/html
|
||||||
mkdir -p publish-docs/networking-guide/content/
|
mkdir -p publish-docs/networking-guide/content/
|
||||||
rsync -a doc/networking-guide/build/html/ publish-docs/networking-guide/content/
|
rsync -a doc/networking-guide/build/html/ publish-docs/networking-guide/content/
|
||||||
@ -63,10 +64,13 @@ commands =
|
|||||||
[testenv:docs]
|
[testenv:docs]
|
||||||
commands =
|
commands =
|
||||||
{toxinidir}/tools/build-user-guides.sh
|
{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
|
sphinx-build -W doc/networking-guide/source doc/networking-guide/build/html
|
||||||
|
|
||||||
[testenv:network]
|
[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]
|
[testenv:publishdocs]
|
||||||
# Prepare all documents (except www subdir) so that they can get
|
# Prepare all documents (except www subdir) so that they can get
|
||||||
|
Loading…
Reference in New Issue
Block a user