Browse Source

Allow setting of publish directory

You can now set the publication directory for a book. This will
allow to make more generic Jenkins jobs since we can now say for example
that api-quick-start-onepager-external gets published as

Fix publishing so that books published to trunk or havana etc are
copied to the proper subdirectory of publish-docs.

Change-Id: Ifb45a352e6f803321dcfcfcc5f8f17b7876f209b
Andreas Jaeger 8 years ago
committed by Anne Gentle
  1. 34
  2. 14
  3. 63


@ -62,6 +62,38 @@ downloaded each time for validation of XML and WADL files.
Please see the ``README.txt`` in the directory for details on where
these files come from.
Publishing of books
If you run the ``openstack-doc-test --check-build``, it will copy all
the books to the directory ``publish-docs`` in the top-level directory
of your repository.
By default, it outputs a directory with the same name as the directory
where the pom.xml file lives in, such as admin-guide-cloud. You can
also check the output of the build job for the name.
Some books need special treatment and there are three options you can
set in the file ``doc-test.conf``:
* ``book`` - the name of a book that needs special treatment
* ``target_dir`` - the path of subdirectory starting at ``target``
that is the root for publishing
* ``publish_dir`` - a new name to publish a book under
As an example, to publish the compute-api version 2 in the directory
``publish-docs/api/openstack-compute/2``, use::
book = openstack-compute-api-2
target_dir = target/docbkx/webhelp/api/openstack-compute/2
publish_dir = api/openstack-compute/2
Note that these options can be specified multiple times and should
always be used this way. You do not need to set ``publish_dir`` but if
you set it, you need to use it every time.
Also note that these are optional settings, the logic in the tool is
sufficient for many of the books.
Release notes
@ -75,6 +107,7 @@ Release notes
- Generate log file for each build.
- Do not install and in
/usr/bin, use special scripts dir instead.
- Allow to configure the directory used under publish-doc
* generatedocbook and generatepot have been merged into a single
file, the command has been renamed to
@ -82,7 +115,6 @@ Release notes
compatibility, wrapper scripts are installed that will be removed
in version 0.8.


@ -9,9 +9,13 @@ file_exception=os-object-api-1.0.wadl
# These two options need to come as pairs:
# These two (or three) options need to come as pairs/triplets.
# Either add publish_pair for each book/target_dir pair or not at all.
# If publish_dir is not specified, book is used as publish_dir.
book = api-quick-start
target_dir = target/docbkx/webhelp/api-quick-start-onepager-external
#publish_dir = api-quick-start
book = api-ref
target_dir = target/docbkx/html
#publish_dir = api-ref


@ -53,9 +53,12 @@ FILE_EXCEPTIONS = []
# These are books that we aren't checking yet
# Mappings from books to directories
# Mappings from books to build directories under target
# Mappings from books to publish directories
# List of recognized (allowable) os profiling directives.
@ -648,26 +651,38 @@ 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.
if cfg.CONF.language:
book_path = os.path.join(publish_path, cfg.CONF.language, book)
book_path = os.path.join(publish_path, book)
# Publishing directory
book_path = publish_path
# Note that shutil.copytree does not allow an existing target directory,
# thus delete it.
shutil.rmtree(book_path, ignore_errors=True)
if cfg.CONF.language:
book_path = os.path.join(book_path, cfg.CONF.language)
if os.path.isdir(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)):
source = os.path.join('target/docbkx/webhelp/local', book)
book_path = os.path.join(book_path, 'local')
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)
book_path = os.path.join(book_path, cfg.CONF.release_path)
elif (book in BOOK_MAPPINGS):
source = BOOK_MAPPINGS[book]
book_publish_dir = BOOK_PUBLISH_MAPPINGS[book]
book_publish_dir = book
book_path = os.path.join(book_path, book_publish_dir)
if cfg.CONF.debug:
print("Uploading book %s to %s" % (book, book_path))
# Note that shutil.copytree does not allow an existing target directory,
# thus delete it.
shutil.rmtree(book_path, ignore_errors=True)
shutil.copytree(source, book_path,
@ -1079,13 +1094,22 @@ cli_OPTS = [
OPTS = [
# NOTE(jaegerandi): books and target-dirs could be a DictOpt
# but I could not get this working properly.
# NOTE(jaegerandi): books, target-dirs, publish-dir could be a
# DictOpt but I could not get this working properly.
cfg.MultiStrOpt("book", default=None,
help="Name of book that needs special mapping."),
help="Name of book that needs special mapping. "
"This is the name of directory where the pom.xml "
"file lives."),
cfg.MultiStrOpt("target-dir", default=None,
help="Target directory for a book. The option "
"must be in the same order as the book option."),
help="Directory name in target dir for a book. "
"The option must be in the same order as the book "
cfg.MultiStrOpt("publish-dir", default=None,
help="Directory name where book will be copied to "
"in publish-docs directory. This option must be in "
"same order as the book option. Either give this option "
"for all books or for none. If publish-dir is not "
"specified, book is used as publish-dir."),
cfg.StrOpt("repo-name", default=None,
help="Name of repository."),
cfg.StrOpt("release-path", default="trunk",
@ -1134,14 +1158,25 @@ def handle_options():
if CONF.check_build and and CONF.target_dir:
if len( != len(CONF.target_dir):
print("ERROR: books and target-dirs need to have a 1:1 "
print("ERROR: book and target_dir options need to have a 1:1 "
if (CONF.publish_dir and
len(CONF.publish_dir) != len(CONF.target_dir)):
print("ERROR: publish_dir and target_dir need to have a 1:1 "
"relationship if publish_dir is specified.")
for i in range(len(
BOOK_MAPPINGS[[i]] = CONF.target_dir[i]
if CONF.verbose:
print(" Target dir for %s is %s" %
([i], BOOK_MAPPINGS[[i]]))
if CONF.publish_dir:
for i in range(len(
BOOK_PUBLISH_MAPPINGS[[i]] = CONF.publish_dir[i]
if CONF.verbose:
print(" Publish dir for %s is %s" %
def main():