From 54aa873505e7fab2ed76dadf1fa2e685fe1d66f1 Mon Sep 17 00:00:00 2001
From: Andreas Jaeger <aj@suse.com>
Date: Fri, 16 Sep 2016 09:45:09 +0200
Subject: [PATCH] Add root-marker file to translated manuals

This is needed for publishing in the future:
This is so that we can create a list of directories to ignore when we
rsync documentation builds to a publishing site. Some builds are
published as subdirectories underneath the results of superior
builds.

This allows those superior builds to be rsynced without removing the
other builds that were published under them.

http://specs.openstack.org/openstack-infra/infra-specs/specs/doc-publishing.html

Change-Id: Ic8773caebecafa87b10c1ad4612bde6b1513b667
---
 bin/doc-tools-check-languages                 | 30 ++++++++++++-------
 .../notes/afs-docs-952f940dc7c47408.yaml      |  7 +++++
 2 files changed, 27 insertions(+), 10 deletions(-)
 create mode 100644 releasenotes/notes/afs-docs-952f940dc7c47408.yaml

diff --git a/bin/doc-tools-check-languages b/bin/doc-tools-check-languages
index 3cc862a7..644d1569 100755
--- a/bin/doc-tools-check-languages
+++ b/bin/doc-tools-check-languages
@@ -16,6 +16,10 @@ BUILD_FAIL=0
 INSTALL_TAGS="obs rdo ubuntu debian debconf"
 FIRSTAPP_TAGS="libcloud dotnet fog openstacksdk pkgcloud shade"
 
+# This marker is needed for Infra publishing and needs to go into the
+# root directory of each translated manual as file ".root-marker".
+MARKER_TEXT="Project: $ZUUL_PROJECT Ref: $ZUUL_REFNAME Build: $ZUUL_UUID"
+
 function build_rst {
     language=$1
     book=$2
@@ -93,9 +97,10 @@ function build_rst {
                 -d ${DOCTREES}
                 ${DOC_DIR}${book}/source/ \
                 ${BUILD_DIR}"
-            mkdir -p publish-docs/${language}/${book}-${tag}
-            rsync -a ${DOC_DIR}${book}/build-${tag}/html/ \
-                publish-docs/${language}/${book}-${tag}
+            PUBLISH_DIR=publish-docs/${language}/${book}-${tag}
+            mkdir -p ${PUBLISH_DIR}
+            rsync -a ${DOC_DIR}${book}/build-${tag}/html/ ${PUBLISH_DIR}
+            echo $MARKER_TEXT > ${PUBLISH_DIR}/.root-marker
         done
     elif [ ${book} = "install-guide" ] ; then
         # Install Guide has several variations, build all of them
@@ -122,9 +127,11 @@ function build_rst {
                     -d ${DOCTREES}
                     ${DOC_DIR}${book}-${tag}/source/ \
                     ${BUILD_DIR}"
-                mkdir -p publish-docs/${language}/${book}-${tag}
+                PUBLISH_DIR=publish-docs/${language}/${book}-${tag}
+                mkdir -p ${PUBLISH_DIR}
                 rsync -a ${DOC_DIR}${book}-${tag}/build-${tag}/html/ \
-                    publish-docs/${language}/${book}-${tag}
+                    ${PUBLISH_DIR}
+                echo $MARKER_TEXT > ${PUBLISH_DIR}/.root-marker
             else
                 ##
                 # Because Sphinx uses the first heading as title regardless of
@@ -148,9 +155,11 @@ function build_rst {
                     -d ${DOCTREES}
                     ${DOC_DIR}${book}/source/ \
                     ${BUILD_DIR}"
-                mkdir -p publish-docs/${language}/${book}-${tag}
+                PUBLISH_DIR=publish-docs/${language}/${book}-${tag}
+                mkdir -p ${PUBLISH_DIR}
                 rsync -a ${DOC_DIR}${book}/build-${tag}/html/ \
-                    publish-docs/${language}/${book}-${tag}
+                    ${PUBLISH_DIR}
+                echo $MARKER_TEXT > ${PUBLISH_DIR}/.root-marker
             fi
         done
     else
@@ -161,9 +170,10 @@ function build_rst {
             -d ${DOCTREES} \
             ${DOC_DIR}${book}/source/ \
             ${BUILD_DIR}"
-        mkdir -p publish-docs/${language}/${book}/
-        rsync -a ${DOC_DIR}${book}/build/html/ \
-            publish-docs/${language}/${book}/
+        PUBLISH_DIR=publish-docs/${language}/${book}/
+        mkdir -p ${PUBLISH_DIR}
+        rsync -a ${DOC_DIR}${book}/build/html/ ${PUBLISH_DIR}
+        echo $MARKER_TEXT > ${PUBLISH_DIR}/.root-marker
     fi
     # Remove newly created files
     git clean -f -q ${LOCALE_DIR}${language}/LC_MESSAGES/*.po
diff --git a/releasenotes/notes/afs-docs-952f940dc7c47408.yaml b/releasenotes/notes/afs-docs-952f940dc7c47408.yaml
new file mode 100644
index 00000000..662ffed3
--- /dev/null
+++ b/releasenotes/notes/afs-docs-952f940dc7c47408.yaml
@@ -0,0 +1,7 @@
+other:
+  - |
+    For translated manuals, the command ``doc-tools-check-languages``
+    now places a marker file in the root of each directory. This
+    marker file is needed for proper publishing in the OpenStack CI
+    environment. For details, see
+    http://specs.openstack.org/openstack-infra/infra-specs/specs/doc-publishing.html.