[NaCl SDK Docs] Fix many issues with the doc generator.

native_client_sdk/src/doc/doxygen/rst_index.py

 #!/usr/bin/env python
 # Copyright (c) 2014 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
 import cStringIO
 import fnmatch
 import optparse
 import os
 import re
 import sys
 
 VALID_CHANNELS = ('stable', 'beta', 'dev')
 
-ROOT_FILE_CONTENTS = """.. _pepper_%(channel)s_index:
+ROOT_FILE_CONTENTS = """\
+.. _pepper_%(channel)s_index:
+
 
 :orphan:
 
 .. DO NOT EDIT! This document is auto-generated by doxygen/rst_index.py.
 
 ########################################
 Pepper API Reference (%(channel_title)s)
 ########################################
 
 This page lists the API for Pepper %(version)s. Apps that use this API can
 run in Chrome %(version)s or higher.
 
 :ref:`Pepper C API Reference <pepper_%(channel)s_c_index>`
 ===========================================================
 
 :ref:`Pepper C++ API Reference <pepper_%(channel)s_cpp_index>`
 ===============================================================
 
 """
 
-C_FILE_CONTENTS = """.. _pepper_%(channel)s_c_index:
+C_FILE_CONTENTS = """\
+.. _pepper_%(channel)s_c_index:
+.. _c-api%(channel_alt)s:
 
 .. DO NOT EDIT! This document is auto-generated by doxygen/rst_index.py.
 
 ##########################################
 Pepper C API Reference (%(channel_title)s)
 ##########################################
 
 This page lists the C API for Pepper %(version)s. Apps that use this API can
 run in Chrome %(version)s or higher.
 
-`Interfaces <group___interfaces.html>`_
-=======================================
+`Interfaces <pepper_%(channel)s/c/group___interfaces.html>`__
+=============================================================
 %(interfaces)s
 
-`Structures <group___structs.html>`_
-====================================
+`Structures <pepper_%(channel)s/c/group___structs.html>`__
+==========================================================
 %(structures)s
 
-`Functions <group___functions.html>`_
-=====================================
+`Functions <pepper_%(channel)s/c/group___functions.html>`__
+===========================================================
 
-`Enums <group___enums.html>`_
-=============================
+`Enums <pepper_%(channel)s/c/group___enums.html>`__
+===================================================
 
-`Typedefs <group___typedefs.html>`_
-===================================
+`Typedefs <pepper_%(channel)s/c/group___typedefs.html>`__
+=========================================================
 
-`Macros <globals_defs.html>`_
-=============================
+`Macros <pepper_%(channel)s/c/globals_defs.html>`__
+===================================================
 
 Files
 =====
 %(files)s
 """
 
 C_INTERFACE_WILDCARDS =  ['struct_p_p_p__*', 'struct_p_p_b__*']
 
 C_STRUCT_WILDCARDS =  ['struct_p_p__*', 'union_p_p__*']
 
-CPP_FILE_CONTENTS = """.. _pepper_%(channel)s_cpp_index:
+CPP_FILE_CONTENTS = """\
+.. _pepper_%(channel)s_cpp_index:
+.. _cpp-api%(channel_alt)s:
 
 .. DO NOT EDIT! This document is auto-generated by doxygen/rst_index.py.
 
 ############################################
 Pepper C++ API Reference (%(channel_title)s)
 ############################################
 
 This page lists the C++ API for Pepper %(version)s. Apps that use this API can
 run in Chrome %(version)s or higher.
 
-`Classes <inherits.html>`_
-==========================
+`Classes <pepper_%(channel)s/cpp/inherits.html>`__
+==================================================
 %(classes)s
 
 Files
 =====
 %(files)s
 """
 
 CPP_CLASSES_WILDCARDS = ['classpp_1_1*.html']
 CPP_CLASSES_EXCLUDES = ['*-members*']
 
@@ skipping 41 matching lines @@
       cap = False
     out += c
 
   # Strip trailing version number (e.g. PPB_Audio_1_1 -> PPB_Audio)
   return re.sub(r'_\d_\d$', '', out)
 
 
 def GetPath(filepath):
   if os.path.exists(filepath):
     return filepath
-  raise OSError('Couldnt find: ' + filepath)
+  raise OSError('Couldn\'t find: ' + filepath)
 
 
-def MakeReSTListFromFiles(path, matches, excludes=None):
+def MakeReSTListFromFiles(prefix, path, matches, excludes=None):
   dir_files = os.listdir(path)
   good_files = []
   for match in matches:
     good_files.extend(fnmatch.filter(dir_files, match))
 
   if excludes:
     for exclude in excludes:
       good_files = [filename for filename in good_files
                     if not fnmatch.fnmatch(filename, exclude)]
 
   good_files.sort()
-  return '\n'.join('  * `%s <%s>`_\n' % (GetName(f), f) for f in good_files)
+  return '\n'.join('  * `%s <%s/%s>`__\n' % (GetName(f), prefix, f)
+                   for f in good_files)
 
 
 def MakeTitleCase(s):
   return s[0].upper() + s[1:]
 
+def MakeChannelAlt(channel):
+  if channel == 'stable':
+    return ''
+  else:
+    return '-' + channel
+
 
 def GenerateRootIndex(channel, version, out_filename):
   channel_title = MakeTitleCase(channel)
+  channel_alt = MakeChannelAlt(channel)
 
   # Use StringIO so we don't write out a partial file on error.
   output = cStringIO.StringIO()
   output.write(ROOT_FILE_CONTENTS % vars())
 
   with open(out_filename, 'w') as f:
     f.write(output.getvalue())
 
 
 def GenerateCIndex(root_dir, channel, version, out_filename):
-  interfaces = MakeReSTListFromFiles(root_dir, C_INTERFACE_WILDCARDS)
-  structures = MakeReSTListFromFiles(root_dir, C_STRUCT_WILDCARDS)
-  files = MakeReSTListFromFiles(root_dir, FILE_WILDCARDS)
+  prefix = 'pepper_%s/c' % channel
+  interfaces = MakeReSTListFromFiles(prefix, root_dir, C_INTERFACE_WILDCARDS)
+  structures = MakeReSTListFromFiles(prefix, root_dir, C_STRUCT_WILDCARDS)
+  files = MakeReSTListFromFiles(prefix, root_dir, FILE_WILDCARDS)
   channel_title = MakeTitleCase(channel)
+  channel_alt = MakeChannelAlt(channel)
 
   # Use StringIO so we don't write out a partial file on error.
   output = cStringIO.StringIO()
   output.write(C_FILE_CONTENTS % vars())
 
   with open(out_filename, 'w') as f:
     f.write(output.getvalue())
 
 
 def GenerateCppIndex(root_dir, channel, version, out_filename):
-  classes = MakeReSTListFromFiles(root_dir, CPP_CLASSES_WILDCARDS,
+  prefix = 'pepper_%s/cpp' % channel
+  classes = MakeReSTListFromFiles(prefix, root_dir, CPP_CLASSES_WILDCARDS,
                                   CPP_CLASSES_EXCLUDES)
-  files = MakeReSTListFromFiles(root_dir, FILE_WILDCARDS)
+  files = MakeReSTListFromFiles(prefix, root_dir, FILE_WILDCARDS)
   channel_title = MakeTitleCase(channel)
+  channel_alt = MakeChannelAlt(channel)
 
   # Use StringIO so we don't write out a partial file on error.
   output = cStringIO.StringIO()
   output.write(CPP_FILE_CONTENTS % vars())
 
   with open(out_filename, 'w') as f:
     f.write(output.getvalue())
 
 
 def main(argv):
@@ skipping 35 matching lines @@
   return 0
 
 
 if __name__ == '__main__':
   try:
     rtn = main(sys.argv[1:])
   except KeyboardInterrupt:
     sys.stderr.write('%s: interrupted\n' % os.path.basename(__file__))
     rtn = 1
   sys.exit(rtn)