[gtk-doc] db2html: add a 2nd template and implement nav links

[Stefan Sauer <stefkost src gnome org>]

commit 7fd77d747f4070f9043d880812c3f2cf26e82ded
Author: Stefan Sauer <ensonic users sf net>
Date:   Sat Dec 16 22:39:29 2017 +0100

    db2html: add a 2nd template and implement nav links
    
    We now use the iterator from anytree to flatten the file-tree. With this
    we can generate prev/next links. Add macros for the link tags in the head
    section (missing titles still).

 tools/db2html.py              |   47 +++++++++++++++++++++++++---------------
 tools/templates/book.html     |    5 ++-
 tools/templates/common.html   |   39 ++++++++++++++++++++++++++++-----
 tools/templates/refentry.html |   18 +++++++++++++++
 4 files changed, 83 insertions(+), 26 deletions(-)
---
diff --git a/tools/db2html.py b/tools/db2html.py
index 58482af..e6ed556 100644
--- a/tools/db2html.py
+++ b/tools/db2html.py
@@ -39,6 +39,7 @@ python3 tools/db2html.py tests/bugs/docs/tester-docs.xml
 ll tests/bugs/docs/db2html
 cp tests/bugs/docs/html/*.{css,png} tests/bugs/docs/db2html/
 xdg-open tests/bugs/docs/db2html/index.html
+meld tests/bugs/docs/{html,db2html}
 """
 
 import argparse
@@ -47,7 +48,7 @@ import logging
 import os
 import sys
 
-from anytree import Node
+from anytree import Node, PreOrderIter
 from jinja2 import Environment, FileSystemLoader
 from lxml import etree
 
@@ -114,6 +115,7 @@ TEMPLATE_ENV = Environment(
 
 TEMPLATES = {
     'book': TEMPLATE_ENV.get_template('book.html'),
+    'refentry': TEMPLATE_ENV.get_template('refentry.html'),
 }
 
 
@@ -144,7 +146,7 @@ def gen_chunk_name(node):
     return name
 
 
-def chunk(out_dir, xml_node, parent=None):
+def chunk(xml_node, parent=None):
     """Chunk the tree.
 
     The first time, we're called with parent=None and in that case we return
@@ -152,26 +154,24 @@ def chunk(out_dir, xml_node, parent=None):
     """
     # print('<%s %s>' % (xml_node.tag, xml_node.attrib))
     if xml_node.tag in CHUNK_TAGS:
-        base = gen_chunk_name(xml_node) + '.html'
-        out_filename = os.path.join(out_dir, base)
-        # print('*** %s ***' % (out_filename))
+        filename = gen_chunk_name(xml_node) + '.html'
         # TODO: do we need to remove the xml-node from the parent?
         #       we generate toc from the files tree
         # from copy import deepcopy
         # ..., xml=deepcopy(xml_node), ...
         # xml_node.getparent().remove(xml_node)
-        parent = Node(xml_node.tag, parent=parent, xml=xml_node, filename=out_filename)
+        parent = Node(xml_node.tag, parent=parent, xml=xml_node, filename=filename)
     for child in xml_node:
-        chunk(out_dir, child, parent)
+        chunk(child, parent)
 
     return parent
 
 
-def convert(node):
-    """Convert the docbook chunks to html files."""
+def convert(out_dir, files, node):
+    """Convert the docbook chunks to a html file."""
 
     logging.info('Writing: %s', node.filename)
-    with open(node.filename, 'wt') as html:
+    with open(os.path.join(out_dir, node.filename), 'wt') as html:
         if node.name in TEMPLATES:
             # TODO: ideally precomiple common xpath exprs once:
             #   func = etree.XPath("//b")
@@ -181,16 +181,25 @@ def convert(node):
 
             template = TEMPLATES[node.name]
             template.globals['xpath'] = lxml_xpath
-            # TODO: extract from xml
             params = {
+                'nav_home': (node.root.filename, ''),
             }
+            # up, prev, next: link + title
+            # TODO: need titles
+            if node.parent:
+                params['nav_up'] = (node.parent.filename, '')
+            ix = files.index(node)
+            if ix > 0:
+                params['nav_prev'] = (files[ix - 1].filename, '')
+            if ix < len(files) - 1:
+                params['nav_next'] = (files[ix + 1].filename, '')
+
             html.write(template.render(**params))
+            # attempt to get the title, does not work
+            # print("Title: %s" % template.module.title)
         else:
             logging.warning('Add template for "%s"', node.name)
 
-    for child in node.children:
-        convert(child)
-
 
 def main(index_file):
     tree = etree.parse(index_file)
@@ -213,10 +222,12 @@ def main(index_file):
     # We need two passes:
     # 1) recursively walk the tree and chunk it into a python tree so that we
     #   can generate navigation and link tags
-    files = chunk(out_dir, tree.getroot())
-    # 2) walk the tree and output files
-    # TODO: iterate with the anytree iterator and use multiprocessing
-    convert(files)
+    files = chunk(tree.getroot())
+    # 2) iterate the tree and output files
+    # TODO: use multiprocessing
+    files = list(PreOrderIter(files))
+    for node in files:
+        convert(out_dir, files, node)
 
 
 if __name__ == '__main__':
diff --git a/tools/templates/book.html b/tools/templates/book.html
index f828c62..c606bb3 100644
--- a/tools/templates/book.html
+++ b/tools/templates/book.html
@@ -1,10 +1,11 @@
-{% from 'common.html' import doctype, navigation_main %}
-{% set title = xpath('./bookinfo/title/text()') %}
+{% from 'common.html' import doctype, head_links, navigation_main %}
+{% set title = xpath('//bookinfo/title/text()') %}
 {{ doctype() }}
 <html>
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>{{ title }}</title>
+{{ head_links(nav_home, nav_up, nav_prev, nav_next) }}
 <link rel="stylesheet" href="style.css" type="text/css">
 </head>
 <body>
diff --git a/tools/templates/common.html b/tools/templates/common.html
index 58b0032..64b3e86 100644
--- a/tools/templates/common.html
+++ b/tools/templates/common.html
@@ -2,18 +2,45 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 {% endmacro %}
 
+{% macro head_links(home, up, prev, next) %}
+<link rel="home" href="{{ home[0] }}" title="{{ home[1] }}">
+{% if up is defined %}
+<link rel="up" href="{{ up[0] }}" title="{{ up[1] }}">
+{% endif %}
+{% if prev is defined %}
+<link rel="prev" href="{{ prev[0] }}" title="{{ prev[1] }}">
+{% endif %}
+{% if next is defined %}
+<link rel="next" href="{{ next[0] }}" title="{{ next[1] }}">
+{% endif %}
+{% endmacro %}
+
 {% macro navigation_main(title) %}
-<div>
-  <table class="navigation" id="top" width="100%" cellpadding="2" cellspacing="0">
-    <tr><th valign="middle"><p class="title">{{ title }}</p></th></tr>
-  </table>
-</div>
+<table class="navigation" id="top" width="100%" cellpadding="2" cellspacing="0">
+  <tr><th valign="middle"><p class="title">{{ title }}</p></th></tr>
+</table>
 {% endmacro %}
 
 {% macro navigation_std(title) %}
 {% endmacro %}
 
-{% macro navigation_ref(title) %}
+{% macro navigation_ref() %}
+<table class="navigation" id="top" width="100%" cellpadding="2" cellspacing="5">
+  <tr valign="middle">
+    <td width="100%" align="left" class="shortcuts">
+      <a href="#" class="shortcut">Top</a>
+      <span id="nav_description">
+        <span class="dim">|</span> 
+        <a href="#tester-GtkdocTester.description" class="shortcut">Description</a>
+      </span>
+    </td>
+    <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" 
alt="Home"></a></td>
+    <td><a accesskey="u" href="ch01.html"><img src="up.png" width="16" height="16" border="0" 
alt="Up"></a></td>
+    <td><a accesskey="p" href="ch01.html"><img src="left.png" width="16" height="16" border="0" 
alt="Prev"></a></td>
+    <td><a accesskey="n" href="api-index.html"><img src="right.png" width="16" height="16" border="0" 
alt="Next"></a></td>
+  </tr>
+</table>
+
 {% endmacro %}
 
 {% macro navigation_idx(title) %}
diff --git a/tools/templates/refentry.html b/tools/templates/refentry.html
new file mode 100644
index 0000000..f9c2176
--- /dev/null
+++ b/tools/templates/refentry.html
@@ -0,0 +1,18 @@
+{% from 'common.html' import doctype, head_links, navigation_ref %}
+{% set title = xpath('//refentry/refmeta/refentrytitle/text()') %}
+{{ doctype() }}
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>{{ title }}</title>
+{{ head_links(nav_home, nav_up, nav_prev, nav_next) }}
+<link rel="stylesheet" href="style.css" type="text/css">
+</head>
+<body>
+<div class="book">
+<div class="titlepage">
+{{ navigation_ref() }}
+</div>
+</div>
+</body>
+</html>
\ No newline at end of file