From 323bdb1ba0149002686c412fda68d5c3f79e7df4 Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Wed, 12 Feb 2014 20:50:45 +0100 Subject: [PATCH] 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 | 34 +++++++++++++++++++++- doc-test.conf.sample | 14 +++++---- os_doc_tools/doctest.py | 63 ++++++++++++++++++++++++++++++++--------- 3 files changed, 91 insertions(+), 20 deletions(-) diff --git a/README.rst b/README.rst index 3aa59f32..5ee05b3f 100644 --- a/README.rst +++ b/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 --- diff --git a/doc-test.conf.sample b/doc-test.conf.sample index e114a48d..ff49ffb4 100644 --- a/doc-test.conf.sample +++ b/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 diff --git a/os_doc_tools/doctest.py b/os_doc_tools/doctest.py index dab71854..cdbf72c8 100755 --- a/os_doc_tools/doctest.py +++ b/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():