openstack/openstack-doc-tools
Code Issues Proposed changes

Handle translations

Browse Source 
Add a new option -l LANGUAGE to build and publish localized content
that is in generated/$LANGUAGE and copy content to
publish_docs/$LANGUAGE.

Add new option --only-book to build only specific manual.

Read gerrit-doc.properties if exists to pass values to maven.

Change-Id: I6a07fe02428679d0e5e00a4d67f1b11d9c85b262
This commit is contained in:
Andreas Jaeger 2014-02-04 20:32:17 +01:00
parent 5b4186cf0b
commit 131a50461b
3 changed files with 88 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
README.rst
View File

@ -68,39 +68,41 @@ Release notes
0.5
---
* Test that resources in wadl files have an xml:id (lp:bug 1275007)
* Improve formatting of python command line clients (lp:bug 1274699)
* Test that resources in wadl files have an xml:id (lp:bug 1275007).
* Improve formatting of python command line clients (lp:bug 1274699).
* Copy all generated books to directory publish-docs in the git
top-level (lp:blueprint draft-docs-on-docs-draft)
top-level (lp:blueprint draft-docs-on-docs-draft).
* Requires now a config file in top-level git directory named
doc-test.conf
doc-test.conf.
* Allow building of translated manuals, these need to be setup first
with "generatedocbook -l LANGUAGE -b BOOK".
0.4
---
* New option --exceptions-file to pass list of files to ignore
completely
* Major improvements for automatic generation of option tables
completely.
* Major improvements for automatic generation of option tables.
* New tool openstack-auto-commands to document python
command line clients
command line clients.
0.3
---
* Fixes path for automated translation toolchain to fix lp:bug 1216153
* Validates .xsd .xsl and.xjb files in addition to .xml
* Fixes validation of WADL files to validate properly against XML schema
* Fixes path for automated translation toolchain to fix lp:bug 1216153.
* Validates .xsd .xsl and.xjb files in addition to .xml.
* Fixes validation of WADL files to validate properly against XML schema.
0.2
---
* Enables local copies of RNG schema for validation
* Enables ignoring directories when checking
* Enables local copies of RNG schema for validation.
* Enables ignoring directories when checking.
0.1
---
Initial release
Initial release.
Contributing
============

12
doc/source/man/openstack-doc-test.rst
View File

@ -48,17 +48,23 @@ OPTIONS
File that will be skipped during validation.
**--force**
Force the validation of all files and build all books.
Force the validation of all files and build all books.
**-h, --help**
Show help message and exit.
Show help message and exit.
**--ignore-dir IGNORE_DIR**
Directory to ignore for building of manuals. The parameter can
be passed multiple times to add several directories.
**--ignore-errors**
Do not exit on failures.
Do not exit on failures.
**--language LANGUAGE, -l LANGUAGE**
Build translated manual for language in path generate/$LANGUAGE .
**--only-book ONLY_BOOK**
Build each specified manual.
**--verbose**
Verbose execution.

75
os_doc_tools/doctest.py
View File

@ -644,7 +644,10 @@ def publish_book(publish_path, book):
# Assumption: The path for the book is the same as the name of directory
# the book is in. We need to special case any exceptions.
book_path = os.path.join(publish_path, book)
if cfg.CONF.language:
book_path = os.path.join(publish_path, cfg.CONF.language, book)
else:
book_path = os.path.join(publish_path, book)
# Note that shutil.copytree does not allow an existing target directory,
# thus delete it.
@ -654,6 +657,10 @@ def publish_book(publish_path, book):
source = os.path.join('target/docbkx/webhelp', book)
elif os.path.isdir(os.path.join('target/docbkx/webhelp/local', book)):
source = os.path.join('target/docbkx/webhelp/local', book)
elif os.path.isdir(os.path.join('target/docbkx/webhelp/',
cfg.CONF.release_path, book)):
source = os.path.join('target/docbkx/webhelp/',
cfg.CONF.release_path, book)
elif (book in BOOK_MAPPINGS):
source = BOOK_MAPPINGS[book]
@ -672,6 +679,8 @@ def build_book(book, publish_path):
returncode = 0
base_book = os.path.basename(book)
base_book_orig = base_book
comments = "-Dcomments.enabled=%s" % cfg.CONF.comments_enabled
release = "-Drelease.path.name=%s" % cfg.CONF.release_path
try:
# Clean first and then build so that the output of all guides
# is available
@ -684,6 +693,7 @@ def build_book(book, publish_path):
base_book = "install-guide (for debian)"
output = subprocess.check_output(
["mvn", "generate-sources", "-B",
comments, release,
"-Doperating.system=apt-debian", "-Dprofile.os=debian"],
stderr=subprocess.STDOUT
)
@ -691,6 +701,7 @@ def build_book(book, publish_path):
base_book = "install-guide (for Fedora)"
output = subprocess.check_output(
["mvn", "generate-sources", "-B",
comments, release,
"-Doperating.system=yum",
"-Dprofile.os=centos;fedora;rhel"],
stderr=subprocess.STDOUT
@ -699,6 +710,7 @@ def build_book(book, publish_path):
base_book = "install-guide (for openSUSE)"
output = subprocess.check_output(
["mvn", "generate-sources", "-B",
comments, release,
"-Doperating.system=zypper", "-Dprofile.os=opensuse;sles"],
stderr=subprocess.STDOUT
)
@ -706,6 +718,7 @@ def build_book(book, publish_path):
base_book = "install-guide (for Ubuntu)"
output = subprocess.check_output(
["mvn", "generate-sources", "-B",
comments, release,
"-Doperating.system=apt", "-Dprofile.os=ubuntu"],
stderr=subprocess.STDOUT
)
@ -717,7 +730,7 @@ def build_book(book, publish_path):
stderr=subprocess.STDOUT
)
output = subprocess.check_output(
["mvn", "generate-sources", "-B"],
["mvn", "generate-sources", comments, release, "-B"],
stderr=subprocess.STDOUT
)
# Repository: identity-api
@ -728,22 +741,22 @@ def build_book(book, publish_path):
stderr=subprocess.STDOUT
)
output = subprocess.check_output(
["mvn", "generate-sources", "-B"],
["mvn", "generate-sources", comments, release, "-B"],
stderr=subprocess.STDOUT
)
# Repository: image-api
elif base_book == "openstack-image-service-api":
output = subprocess.check_output(
["markdown-docbook.sh", "image-api-v2.0"],
["markdown-docbook.sh", comments, release, "image-api-v2.0"],
stderr=subprocess.STDOUT
)
output = subprocess.check_output(
["mvn", "generate-sources", "-B"],
["mvn", "generate-sources", comments, release, "-B"],
stderr=subprocess.STDOUT
)
else:
output = subprocess.check_output(
["mvn", "generate-sources", "-B"],
["mvn", "generate-sources", comments, release, "-B"],
stderr=subprocess.STDOUT
)
except subprocess.CalledProcessError as e:
@ -779,7 +792,8 @@ def find_affected_books(rootdir, book_exceptions, file_exceptions,
books = []
affected_books = set()
build_all_books = force or check_modified_affects_all(rootdir, verbose)
build_all_books = (force or check_modified_affects_all(rootdir, verbose) or
cfg.CONF.only_book)
# Dictionary that contains a set of files.
# The key is a filename, the set contains files that include this file.
@ -811,8 +825,11 @@ def find_affected_books(rootdir, book_exceptions, file_exceptions,
elif root.endswith('doc') or root == rootdir:
continue
elif "pom.xml" in files:
books.append(root)
book_root = root
if (not cfg.CONF.only_book or
(cfg.CONF.only_book and
os.path.basename(root) in cfg.CONF.only_book)):
books.append(root)
book_root = root
# No need to check single books if we build all, we just
# collect list of books
@ -893,7 +910,9 @@ def find_affected_books(rootdir, book_exceptions, file_exceptions,
new_files.append(g)
affected_files.add(g)
if build_all_books:
if cfg.CONF.only_book:
print("Building specified books.")
elif build_all_books:
print("Building all books.")
elif affected_books:
books = affected_books
@ -962,6 +981,22 @@ def build_affected_books(rootdir, book_exceptions, file_exceptions,
print("Building of books finished successfully.\n")
def read_properties():
"""Read gerrit-doc.properties."""
gerrit_file = os.path.join(get_gitroot(), 'gerrit-doc.properties')
if os.path.isfile(gerrit_file):
for line in open(gerrit_file, 'r'):
content = line.strip().split('=')
if len(content) > 1:
if content[0] == "DOC_RELEASE_PATH":
cfg.CONF.release_path = content[1]
elif content[0] == "DOC_COMMENTS_ENABLED":
cfg.CONF.comments_enabled = content[1]
def add_exceptions(file_exception, verbose):
"""Add list of exceptions from file_exceptions."""
@ -999,6 +1034,11 @@ cli_OPTS = [
help="Directory to ignore for building of manuals. The "
"parameter can be passed multiple times to add "
"several directories."),
cfg.StrOpt('language', default=None, short='l',
help="Build translated manual for language in path "
"generate/$LANGUAGE ."),
cfg.MultiStrOpt('only-book', default=None,
help="Build each specified manual."),
]
OPTS = [
@ -1011,6 +1051,10 @@ OPTS = [
"must be in the same order as the book option."),
cfg.StrOpt("repo-name", default=None,
help="Name of repository."),
cfg.StrOpt("release-path", default="trunk",
help="Value to pass to maven for release.path.name."),
cfg.StrOpt("comments-enabled", default="0",
help="Value to pass to maven for comments.enabled."),
]
@ -1031,6 +1075,10 @@ def handle_options():
if CONF.verbose:
print("Verbose execution")
if CONF.language:
print("Building for language '%s'" % CONF.language)
if CONF.file_exception:
add_exceptions(CONF.file_exception, CONF.verbose)
@ -1065,7 +1113,11 @@ def main():
handle_options()
doc_path = get_gitroot()
if not CONF.api_site:
if CONF.language:
doc_path = os.path.join(doc_path, 'generated', CONF.language)
if CONF.verbose:
print("Using %s as root" % doc_path)
elif not CONF.api_site:
doc_path = os.path.join(doc_path, 'doc')
if CONF.check_build and www_touched(False):
@ -1095,6 +1147,7 @@ def main():
check_deleted_files(doc_path, FILE_EXCEPTIONS, CONF.verbose)
if CONF.check_build:
read_properties()
build_affected_books(doc_path, BOOK_EXCEPTIONS,
FILE_EXCEPTIONS,
CONF.verbose, CONF.force,