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
api-quick-start.

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

Change-Id: Ifb45a352e6f803321dcfcfcc5f8f17b7876f209b

README.rst

@@ -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 build-ha-guide.sh and markdown-docbook.sh 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.
 
-
 0.6
 ---
 

doc-test.conf.sample

@@ -9,9 +9,13 @@ file_exception=os-object-api-1.0.wadl
 ignore_dir=incubation
 ignore_dir=openstack-compute-api-1.0
 
-# These two options need to come as pairs:
-book=api-quick-start
-target_dir=target/docbkx/webhelp/api-quick-start-onepager-external
+# 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
+book = api-ref
+target_dir = target/docbkx/html
+#publish_dir = api-ref

os_doc_tools/doctest.py

@@ -53,9 +53,12 @@ FILE_EXCEPTIONS = []
 # These are books that we aren't checking yet
 BOOK_EXCEPTIONS = []
 
-# Mappings from books to directories
+# Mappings from books to build directories under target
 BOOK_MAPPINGS = {}
 
+# Mappings from books to publish directories
+BOOK_PUBLISH_MAPPINGS = {}
+
 RESULTS_OF_BUILDS = []
 
 # 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)
-    else:
-        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]
 
+    if book in BOOK_PUBLISH_MAPPINGS:
+        book_publish_dir = BOOK_PUBLISH_MAPPINGS[book]
+    else:
+        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,
                     ignore=shutil.ignore_patterns('*.xml'))
 
@@ -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 "
+                    "option."),
+    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 CONF.book and CONF.target_dir:
         if len(CONF.book) != 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 "
                   "relationship.")
             sys.exit(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.")
+            sys.exit(1)
         for i in range(len(CONF.book)):
             BOOK_MAPPINGS[CONF.book[i]] = CONF.target_dir[i]
             if CONF.verbose:
                 print(" Target dir for %s is %s" %
                       (CONF.book[i], BOOK_MAPPINGS[CONF.book[i]]))
+        if CONF.publish_dir:
+            for i in range(len(CONF.book)):
+                BOOK_PUBLISH_MAPPINGS[CONF.book[i]] = CONF.publish_dir[i]
+                if CONF.verbose:
+                    print(" Publish dir for %s is %s" %
+                          (CONF.book[i], BOOK_PUBLISH_MAPPINGS[CONF.book[i]]))
 
 
 def main():