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
This commit is contained in:
Andreas Jaeger
Anne Gentle
parent
ccbfdb592f
commit
323bdb1ba0
34
README.rst
34
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
|
||||
---
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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():
|
||||
|
||||
Loading…
Reference in New Issue
Block a user