openstack
/
openstack-doc-tools
Code Issues Proposed changes

Handle translations 

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 0.5
--- ---
* Test that resources in wadl files have an xml:id (lp:bug 1275007) * Test that resources in wadl files have an xml:id (lp:bug 1275007).
* Improve formatting of python command line clients (lp:bug 1274699) * Improve formatting of python command line clients (lp:bug 1274699).
* Copy all generated books to directory publish-docs in the git * 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 * 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 0.4
--- ---
* New option --exceptions-file to pass list of files to ignore * New option --exceptions-file to pass list of files to ignore
completely completely.
* Major improvements for automatic generation of option tables * Major improvements for automatic generation of option tables.
* New tool openstack-auto-commands to document python * New tool openstack-auto-commands to document python
command line clients command line clients.
0.3 0.3
--- ---
* Fixes path for automated translation toolchain to fix lp:bug 1216153 * Fixes path for automated translation toolchain to fix lp:bug 1216153.
* Validates .xsd .xsl and.xjb files in addition to .xml * Validates .xsd .xsl and.xjb files in addition to .xml.
* Fixes validation of WADL files to validate properly against XML schema * Fixes validation of WADL files to validate properly against XML schema.
0.2 0.2
--- ---
* Enables local copies of RNG schema for validation * Enables local copies of RNG schema for validation.
* Enables ignoring directories when checking * Enables ignoring directories when checking.
0.1 0.1
--- ---
Initial release Initial release.
Contributing Contributing
============ ============

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

@ -48,17 +48,23 @@ OPTIONS
File that will be skipped during validation. File that will be skipped during validation.
**--force** **--force**
Force the validation of all files and build all books. Force the validation of all files and build all books.
**-h, --help** **-h, --help**
Show help message and exit. Show help message and exit.
**--ignore-dir IGNORE_DIR** **--ignore-dir IGNORE_DIR**
Directory to ignore for building of manuals. The parameter can Directory to ignore for building of manuals. The parameter can
be passed multiple times to add several directories. be passed multiple times to add several directories.
**--ignore-errors** **--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**
Verbose execution. 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 # 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. # 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, # Note that shutil.copytree does not allow an existing target directory,
# thus delete it. # thus delete it.
@ -654,6 +657,10 @@ def publish_book(publish_path, book):
source = os.path.join('target/docbkx/webhelp', book) source = os.path.join('target/docbkx/webhelp', book)
elif os.path.isdir(os.path.join('target/docbkx/webhelp/local', book)): elif os.path.isdir(os.path.join('target/docbkx/webhelp/local', book)):
source = 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): elif (book in BOOK_MAPPINGS):
source = BOOK_MAPPINGS[book] source = BOOK_MAPPINGS[book]
@ -672,6 +679,8 @@ def build_book(book, publish_path):
returncode = 0 returncode = 0
base_book = os.path.basename(book) base_book = os.path.basename(book)
base_book_orig = base_book base_book_orig = base_book
comments = "-Dcomments.enabled=%s" % cfg.CONF.comments_enabled
release = "-Drelease.path.name=%s" % cfg.CONF.release_path
try: try:
# Clean first and then build so that the output of all guides # Clean first and then build so that the output of all guides
# is available # is available
@ -684,6 +693,7 @@ def build_book(book, publish_path):
base_book = "install-guide (for debian)" base_book = "install-guide (for debian)"
output = subprocess.check_output( output = subprocess.check_output(
["mvn", "generate-sources", "-B", ["mvn", "generate-sources", "-B",
comments, release,
"-Doperating.system=apt-debian", "-Dprofile.os=debian"], "-Doperating.system=apt-debian", "-Dprofile.os=debian"],
stderr=subprocess.STDOUT stderr=subprocess.STDOUT
) )
@ -691,6 +701,7 @@ def build_book(book, publish_path):
base_book = "install-guide (for Fedora)" base_book = "install-guide (for Fedora)"
output = subprocess.check_output( output = subprocess.check_output(
["mvn", "generate-sources", "-B", ["mvn", "generate-sources", "-B",
comments, release,
"-Doperating.system=yum", "-Doperating.system=yum",
"-Dprofile.os=centos;fedora;rhel"], "-Dprofile.os=centos;fedora;rhel"],
stderr=subprocess.STDOUT stderr=subprocess.STDOUT
@ -699,6 +710,7 @@ def build_book(book, publish_path):
base_book = "install-guide (for openSUSE)" base_book = "install-guide (for openSUSE)"
output = subprocess.check_output( output = subprocess.check_output(
["mvn", "generate-sources", "-B", ["mvn", "generate-sources", "-B",
comments, release,
"-Doperating.system=zypper", "-Dprofile.os=opensuse;sles"], "-Doperating.system=zypper", "-Dprofile.os=opensuse;sles"],
stderr=subprocess.STDOUT stderr=subprocess.STDOUT
) )
@ -706,6 +718,7 @@ def build_book(book, publish_path):
base_book = "install-guide (for Ubuntu)" base_book = "install-guide (for Ubuntu)"
output = subprocess.check_output( output = subprocess.check_output(
["mvn", "generate-sources", "-B", ["mvn", "generate-sources", "-B",
comments, release,
"-Doperating.system=apt", "-Dprofile.os=ubuntu"], "-Doperating.system=apt", "-Dprofile.os=ubuntu"],
stderr=subprocess.STDOUT stderr=subprocess.STDOUT
) )
@ -717,7 +730,7 @@ def build_book(book, publish_path):
stderr=subprocess.STDOUT stderr=subprocess.STDOUT
) )
output = subprocess.check_output( output = subprocess.check_output(
["mvn", "generate-sources", "-B"], ["mvn", "generate-sources", comments, release, "-B"],
stderr=subprocess.STDOUT stderr=subprocess.STDOUT
) )
# Repository: identity-api # Repository: identity-api
@ -728,22 +741,22 @@ def build_book(book, publish_path):
stderr=subprocess.STDOUT stderr=subprocess.STDOUT
) )
output = subprocess.check_output( output = subprocess.check_output(
["mvn", "generate-sources", "-B"], ["mvn", "generate-sources", comments, release, "-B"],
stderr=subprocess.STDOUT stderr=subprocess.STDOUT
) )
# Repository: image-api # Repository: image-api
elif base_book == "openstack-image-service-api": elif base_book == "openstack-image-service-api":
output = subprocess.check_output( output = subprocess.check_output(
["markdown-docbook.sh", "image-api-v2.0"], ["markdown-docbook.sh", comments, release, "image-api-v2.0"],
stderr=subprocess.STDOUT stderr=subprocess.STDOUT
) )
output = subprocess.check_output( output = subprocess.check_output(
["mvn", "generate-sources", "-B"], ["mvn", "generate-sources", comments, release, "-B"],
stderr=subprocess.STDOUT stderr=subprocess.STDOUT
) )
else: else:
output = subprocess.check_output( output = subprocess.check_output(
["mvn", "generate-sources", "-B"], ["mvn", "generate-sources", comments, release, "-B"],
stderr=subprocess.STDOUT stderr=subprocess.STDOUT
) )
except subprocess.CalledProcessError as e: except subprocess.CalledProcessError as e:
@ -779,7 +792,8 @@ def find_affected_books(rootdir, book_exceptions, file_exceptions,
books = [] books = []
affected_books = set() 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. # Dictionary that contains a set of files.
# The key is a filename, the set contains files that include this file. # 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: elif root.endswith('doc') or root == rootdir:
continue continue
elif "pom.xml" in files: elif "pom.xml" in files:
books.append(root) if (not cfg.CONF.only_book or
book_root = root (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 # No need to check single books if we build all, we just
# collect list of books # collect list of books
@ -893,7 +910,9 @@ def find_affected_books(rootdir, book_exceptions, file_exceptions,
new_files.append(g) new_files.append(g)
affected_files.add(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.") print("Building all books.")
elif affected_books: elif affected_books:
books = 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") 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): def add_exceptions(file_exception, verbose):
"""Add list of exceptions from file_exceptions.""" """Add list of exceptions from file_exceptions."""
@ -999,6 +1034,11 @@ cli_OPTS = [
help="Directory to ignore for building of manuals. The " help="Directory to ignore for building of manuals. The "
"parameter can be passed multiple times to add " "parameter can be passed multiple times to add "
"several directories."), "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 = [ OPTS = [
@ -1011,6 +1051,10 @@ OPTS = [
"must be in the same order as the book option."), "must be in the same order as the book option."),
cfg.StrOpt("repo-name", default=None, cfg.StrOpt("repo-name", default=None,
help="Name of repository."), 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: if CONF.verbose:
print("Verbose execution") print("Verbose execution")
if CONF.language:
print("Building for language '%s'" % CONF.language)
if CONF.file_exception: if CONF.file_exception:
add_exceptions(CONF.file_exception, CONF.verbose) add_exceptions(CONF.file_exception, CONF.verbose)
@ -1065,7 +1113,11 @@ def main():
handle_options() handle_options()
doc_path = get_gitroot() 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') doc_path = os.path.join(doc_path, 'doc')
if CONF.check_build and www_touched(False): if CONF.check_build and www_touched(False):
@ -1095,6 +1147,7 @@ def main():
check_deleted_files(doc_path, FILE_EXCEPTIONS, CONF.verbose) check_deleted_files(doc_path, FILE_EXCEPTIONS, CONF.verbose)
if CONF.check_build: if CONF.check_build:
read_properties()
build_affected_books(doc_path, BOOK_EXCEPTIONS, build_affected_books(doc_path, BOOK_EXCEPTIONS,
FILE_EXCEPTIONS, FILE_EXCEPTIONS,
CONF.verbose, CONF.force, CONF.verbose, CONF.force,