[GTK] Local cross references are broken in API documentation
authorcarlosgc@webkit.org <carlosgc@webkit.org@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Fri, 20 Apr 2018 10:33:30 +0000 (10:33 +0000)
committercarlosgc@webkit.org <carlosgc@webkit.org@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Fri, 20 Apr 2018 10:33:30 +0000 (10:33 +0000)
https://bugs.webkit.org/show_bug.cgi?id=184771

Reviewed by Michael Catanzaro.

.:

Update the documentation html paths and install the JSC GLib API too.

* Source/PlatformGTK.cmake:

Tools:

The problem is that gtkdoc-fixxref expects the links to be in the form html/modulename (like the installed
ones), but we generate the documentation as modulename/html. So, links to WebKitDOM or JSC are generated as
../html/Foo. The rebase command considers html to be the module name in this case, creating broken links in all
the cases.

* gtk/gtkdoc.py:
(GTKDoc._copy_doc_files_to_output_dir): We don't have any html dir in the source tree so, we are not copying
anything here.
(GTKDoc._run_gtkdoc_mkhtml): Create the html dir here using html/modulename instead now.
(GTKDoc._run_gtkdoc_fixxref): Pass the new directory as module dir to gtkdoc-fixxref and fix several links for
which gtkdoc-fixxref always uses absolute paths.
* gtk/manifest.txt.in: Update the documentation html paths and include the JSC GLib API in the tarball too.

git-svn-id: https://svn.webkit.org/repository/webkit/trunk@230837 268f45cc-cd09-0410-ab3c-d52691b4dbfc

ChangeLog
Source/PlatformGTK.cmake
Tools/ChangeLog
Tools/gtk/gtkdoc.py
Tools/gtk/manifest.txt.in

index 37fbfb1..9754a9d 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2018-04-20  Carlos Garcia Campos  <cgarcia@igalia.com>
+
+        [GTK] Local cross references are broken in API documentation
+        https://bugs.webkit.org/show_bug.cgi?id=184771
+
+        Reviewed by Michael Catanzaro.
+
+        Update the documentation html paths and install the JSC GLib API too.
+
+        * Source/PlatformGTK.cmake:
+
 2018-04-18  Carlos Garcia Campos  <cgarcia@igalia.com>
 
         Unreviewed. Update OptionsGTK.cmake and NEWS for 2.21.1 release.
index c42ce34..6dd6b43 100644 (file)
@@ -14,12 +14,15 @@ list(APPEND DocumentationDependencies
 )
 
 if (ENABLE_GTKDOC)
-    install(DIRECTORY ${CMAKE_BINARY_DIR}/Documentation/webkit2gtk-${WEBKITGTK_API_VERSION}/html/
+    install(DIRECTORY ${CMAKE_BINARY_DIR}/Documentation/webkit2gtk-${WEBKITGTK_API_VERSION}/html/webkit2gtk-${WEBKITGTK_API_VERSION}
             DESTINATION "${CMAKE_INSTALL_DATADIR}/gtk-doc/html/webkit2gtk-${WEBKITGTK_API_VERSION}"
     )
-    install(DIRECTORY ${CMAKE_BINARY_DIR}/Documentation/webkitdomgtk-${WEBKITGTK_API_VERSION}/html/
+    install(DIRECTORY ${CMAKE_BINARY_DIR}/Documentation/webkitdomgtk-${WEBKITGTK_API_VERSION}/html/webkitdomgtk-${WEBKITGTK_API_VERSION}
             DESTINATION "${CMAKE_INSTALL_DATADIR}/gtk-doc/html/webkitdomgtk-${WEBKITGTK_API_VERSION}"
     )
+    install(DIRECTORY ${CMAKE_BINARY_DIR}/Documentation/jsc-glib-${WEBKITGTK_API_VERSION}/html/jsc-glib-${WEBKITGTK_API_VERSION}
+            DESTINATION "${CMAKE_INSTALL_DATADIR}/gtk-doc/html/jsc-glib-${WEBKITGTK_API_VERSION}"
+    )
 endif ()
 
 macro(ADD_GTKDOC_GENERATOR _stamp_name _extra_args)
index 6b58fc3..5977f6a 100644 (file)
@@ -1,3 +1,23 @@
+2018-04-20  Carlos Garcia Campos  <cgarcia@igalia.com>
+
+        [GTK] Local cross references are broken in API documentation
+        https://bugs.webkit.org/show_bug.cgi?id=184771
+
+        Reviewed by Michael Catanzaro.
+
+        The problem is that gtkdoc-fixxref expects the links to be in the form html/modulename (like the installed
+        ones), but we generate the documentation as modulename/html. So, links to WebKitDOM or JSC are generated as
+        ../html/Foo. The rebase command considers html to be the module name in this case, creating broken links in all
+        the cases.
+
+        * gtk/gtkdoc.py:
+        (GTKDoc._copy_doc_files_to_output_dir): We don't have any html dir in the source tree so, we are not copying
+        anything here.
+        (GTKDoc._run_gtkdoc_mkhtml): Create the html dir here using html/modulename instead now.
+        (GTKDoc._run_gtkdoc_fixxref): Pass the new directory as module dir to gtkdoc-fixxref and fix several links for
+        which gtkdoc-fixxref always uses absolute paths.
+        * gtk/manifest.txt.in: Update the documentation html paths and include the JSC GLib API in the tarball too.
+
 2018-04-19  Brady Eidson  <beidson@apple.com>
 
         Make back forward cache work with process swapping.
index 03c8e8e..f0a09f1 100644 (file)
@@ -14,6 +14,7 @@
 # License along with this library; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
+import codecs
 import errno
 import logging
 import os
@@ -247,17 +248,6 @@ class GTKDoc(object):
         self._create_directory_if_nonexistent(self.output_dir)
         copy_all_files_in_directory(self.doc_dir, self.output_dir)
 
-        if not html:
-            return
-
-        self.logger.debug('Copying HTML files to output directory...')
-        html_src_dir = os.path.join(self.doc_dir, 'html')
-        html_dest_dir = os.path.join(self.output_dir, 'html')
-        self._create_directory_if_nonexistent(html_dest_dir)
-
-        if os.path.exists(html_src_dir):
-            copy_all_files_in_directory(html_src_dir, html_dest_dir)
-
     def _write_version_xml(self):
         if not self.version:
             self.logger.info('No version specified, so not writing version.xml')
@@ -358,7 +348,9 @@ class GTKDoc(object):
         self._run_command(args, cwd=self.output_dir)
 
     def _run_gtkdoc_mkhtml(self):
-        html_dest_dir = os.path.join(self.output_dir, 'html')
+        # gtkdoc-fixxref expects the paths to be html/modulename.
+        html_dest_dir = os.path.join(self.output_dir, 'html', self.module_name)
+        self._create_directory_if_nonexistent(html_dest_dir)
         if not os.path.isdir(html_dest_dir):
             raise Exception("%s is not a directory, could not generate HTML"
                             % html_dest_dir)
@@ -377,11 +369,32 @@ class GTKDoc(object):
     def _run_gtkdoc_fixxref(self):
         args = ['gtkdoc-fixxref',
                 '--module=%s' % self.module_name,
-                '--module-dir=html',
-                '--html-dir=html']
+                '--module-dir=html/%s' % self.module_name]
         args.extend(['--extra-dir=%s' % extra_dir for extra_dir in self.cross_reference_deps])
         self._run_command(args, cwd=self.output_dir, ignore_warnings=True)
 
+        # gtkdoc-fixxref has some predefined links for which it always uses absolute paths.
+        html_dir_prefix = os.path.join(self.virtual_root + self.prefix, 'share', 'gtk-doc', 'html')
+        module_dir = os.path.join(self.output_dir, 'html', self.module_name)
+        for entry in os.listdir(module_dir):
+            if not entry.endswith('.html'):
+                continue
+
+            filename = os.path.join(module_dir, entry)
+            contents = ''
+            with codecs.open(filename, 'r', encoding='utf-8') as f:
+                contents = f.read()
+
+            if not html_dir_prefix in contents:
+                continue
+
+            tmp_filename = filename + '.new'
+            new_contents = contents.replace(html_dir_prefix, '..')
+            with codecs.open(tmp_filename, 'w', encoding='utf-8') as f:
+                f.write(new_contents)
+
+            os.rename(tmp_filename, filename)
+
     def rebase_installed_docs(self):
         if not os.path.isdir(self.output_dir):
             raise Exception("Tried to rebase documentation before generating it.")
index f95816f..4c3bac8 100644 (file)
@@ -95,5 +95,6 @@ directory Tools/TestWebKitAPI
 file CMakeLists.txt
 file Tools/CMakeLists.txt
 
-directory ${CMAKE_BINARY_DIR}/Documentation/webkit2gtk-${WEBKITGTK_API_VERSION}/html Documentation/webkit2gtk-${WEBKITGTK_API_VERSION}/html
-directory ${CMAKE_BINARY_DIR}/Documentation/webkitdomgtk-${WEBKITGTK_API_VERSION}/html Documentation/webkitdomgtk-${WEBKITGTK_API_VERSION}/html
+directory ${CMAKE_BINARY_DIR}/Documentation/webkit2gtk-${WEBKITGTK_API_VERSION}/html/webkit2gtk-${WEBKITGTK_API_VERSION} Documentation/webkit2gtk-${WEBKITGTK_API_VERSION}/html
+directory ${CMAKE_BINARY_DIR}/Documentation/webkitdomgtk-${WEBKITGTK_API_VERSION}/html/webkitdomgtk-${WEBKITGTK_API_VERSION} Documentation/webkitdomgtk-${WEBKITGTK_API_VERSION}/html
+directory ${CMAKE_BINARY_DIR}/Documentation/jsc-glib-${WEBKITGTK_API_VERSION}/html/jsc-glib-${WEBKITGTK_API_VERSION} Documentation/jsc-glib-${WEBKITGTK_API_VERSION}/html