Use absolute paths in template on publishdocs

Current relative path resolution on template variables
(TOPDIR, CSSDIR, SCRIPTDIR, IMAGEDIR) cannot be used in css templates
which rendered css files are used on docsthemes.

This patch proposes to purposely use absolute URL paths
for publishdocs environment to prevent from side effects using
relative paths and apply the template variables to the tmpl files
which could not be applied previously by changing www-generator tool.

Also, changes doc-contrib-guide documentation properly.

Change-Id: I3ffda6cc6fa360a09dbcbba2ec924be054a88142

doc/doc-contrib-guide/source/doc-tools/template-generator.rst

@@ -299,22 +299,27 @@ loop contexts).
   extract the correct subset of the data.
 
 ``TOPDIR``
-  The relative path to the top of the build output. This is useful for
+  The path to the top of the build output (relative path by default and
+  absolute URL with ``--publish`` option). This is useful for
   building paths between output pages in a way that allows those pages
   to move around later.
 
 ``SCRIPTDIR``
-  The relative path to the location of the JavaScript directory in the
+  The path to the location of the JavaScript directory in the
-  build output. This is useful for building links to JavaScript files.
+  build output (relative path by default and absolute URL with
+  ``--publish`` option).
+  This is useful for building links to JavaScript files.
 
 ``CSSDIR``
-  The relative path to the location of the directory containing the
+  The path to the location of the directory containing the
-  CSS files in the build output. This is useful for building links to
+  CSS files in the build output (relative path by default and absolute URL
+  with ``--publish`` option). This is useful for building links to
   CSS files.
 
 ``IMAGEDIR``
-  The relative path to the location of the directory containing image
+  The path to the location of the directory containing image
-  files in the build output. This is useful for building links to
+  files in the build output (relative path by default and absolute URL
+  with ``--publish`` option). This is useful for building links to
   images.
 
 ``SERIES``

tools/publishdocs.sh

@@ -36,7 +36,7 @@ if [ "$PUBLISH" = "build" ] ; then
 fi
 if [ "$PUBLISH" = "publish" ] ; then
     python3 tools/www-generator.py --source-directory www/ \
-        --output-directory publish-docs
+        --output-directory publish-docs --publish
     rsync -a www/static/ publish-docs/
     # Don't publish these files
     rm publish-docs/www-index.html

tools/www-generator.py

@@ -155,6 +155,11 @@ def parse_command_line_arguments():
                         action='append',
                         help='project to check (defaults to all)',
                         )
+    parser.add_argument('--publish',
+                        default=False,
+                        action='store_true',
+                        help='use absolute paths for publish environment',
+                        )
     return parser.parse_args()
 
 
@@ -475,18 +480,25 @@ def _get_official_repos():
 
 
 def render_template(environment, project_data, regular_repos, infra_repos,
-                    template_files, template_file, output_directory, extra={}):
+                    template_files, template_file, output_directory,
+                    is_publish, extra={}):
     logger = logging.getLogger()
     logger.info("generating %s", template_file)
 
     # Determine the relative path to a few common directories so
     # we don't need to set them in the templates.
-    topdir = os.path.relpath(
+    if is_publish:
-        '.', os.path.dirname(template_file),
+        topdir = 'https://docs.openstack.org/'
-    ).rstrip('/') + '/'
+        scriptdir = topdir + 'common/js/'
-    scriptdir = os.path.join(topdir, 'common', 'js').rstrip('/') + '/'
+        cssdir = topdir + 'common/css/'
-    cssdir = os.path.join(topdir, 'common', 'css').rstrip('/') + '/'
+        imagedir = topdir + 'common/images/'
-    imagedir = os.path.join(topdir, 'common', 'images').rstrip('/') + '/'
+    else:
+        topdir = os.path.relpath(
+            '.', os.path.dirname(template_file),
+        ).rstrip('/') + '/'
+        scriptdir = os.path.join(topdir, 'common', 'js').rstrip('/') + '/'
+        cssdir = os.path.join(topdir, 'common', 'css').rstrip('/') + '/'
+        imagedir = os.path.join(topdir, 'common', 'images').rstrip('/') + '/'
 
     series_match = SERIES_PAT.match(template_file)
     if series_match:
@@ -610,6 +622,7 @@ def main():
             template_files,
             template_file,
             args.output_directory,
+            args.publish
         )
         output_pages.append(template_file)
 
@@ -623,6 +636,7 @@ def main():
             template_files,
             page_list_template,
             args.output_directory,
+            args.publish,
             extra={
                 'file_list': output_pages,
             },

www/templates/deprecated_badge.tmpl

@@ -1,12 +1,9 @@
 {# -*- mode: html -*- #}
 
 <!-- Custom CSS -->
-{# reason to not use the CSSDIR its because introduces a relative path #}
-{# not an absolute, so when its included on docthemes, its tried to include the css #}
-{# from a wrong path instead of the right one #}
 
-<link href="https://docs.openstack.org/common/css/deprecated-badge.css" rel="stylesheet">
+<link href="{{ CSSDIR }}deprecated-badge.css" rel="stylesheet">
-<script src="https://docs.openstack.org/common/js/deprecated-badge.js"></script>
+<script src="{{ SCRIPTDIR }}deprecated-badge.js"></script>
 
 <div id="deprecated-badge" class="deprecated-badge fixed
     {% if SERIES == RELEASED_SERIES %}

www/templates/project_deprecated_badge.tmpl

@@ -1,12 +1,9 @@
 {# -*- mode: html -*- #}
 
 <!-- Custom CSS -->
-{# reason to not use the CSSDIR its because introduces a relative path #}
-{# not an absolute, so when its included on docthemes, its tried to include the css #}
-{# from a wrong path instead of the right one #}
 
-<link href="https://docs.openstack.org/common/css/deprecated-badge.css" rel="stylesheet">
+<link href="{{ CSSDIR }}deprecated-badge.css" rel="stylesheet">
-<script src="https://docs.openstack.org/common/js/deprecated-badge.js"></script>
+<script src="{{ SCRIPTDIR }}deprecated-badge.js"></script>
 
 <div id="deprecated-badge" class="deprecated-badge fixed
     {% if SERIES == RELEASED_SERIES %}
@@ -41,4 +38,4 @@
         {% endif %}
         <a href="#top" class="deprecated-badge-right"><i class="fa fa-chevron-up" aria-hidden="true"></i>&nbsp;Back to Top</a>
     </div>
-</div>
+</div>