added configuration option to enable use of xml:id in title

Author: engineerjoe440

README.md

@@ -61,10 +61,11 @@ extensions = [
 There are two configurable parameters for `conf.py` that correspond to
 `rst2db.py` parameters:
 
-| Name | Description |
-|------|-------------|
-| *docbook_template_file* | template file that will be used to position the document parts. This should be a valid DocBook .xml file that contains  Requires Jinja2 to be installed if specified. |
-| *docbook_default_root_element* | default root element for a file-level document.  Default is 'section'. |
+| Name | Description | Default |
+|------|-------------|---------|
+| *docbook_template_file* | Template file that will be used to position the document parts. This should be a valid DocBook .xml file that contains  Requires Jinja2 to be installed if specified. | "`section`" |
+| *docbook_default_root_element* | Default root element for a file-level document.  Default is 'section'. | `None` |
+| *docbook_use_xml_id_in_titles* | Control to enable the use of `xml:id=...` attribute in `title` XML tags. | `False` |
 
 For example:
 

sphinx_docbook/docbook_builder.py

@@ -35,8 +35,10 @@ def process_with_template(self, contents):
             )
             sys.exit(1)
 
-        full_template_path = os.path.join(sphinx_app.env.srcdir,
-                        sphinx_app.config.docbook_template_file)
+        full_template_path = os.path.join(
+            sphinx_app.env.srcdir,
+            sphinx_app.config.docbook_template_file
+        )
 
         if not os.path.exists(full_template_path):
             sys.stderr.write(
@@ -53,8 +55,8 @@ def process_with_template(self, contents):
                 trim_blocks=True)
 
         try:
-            t = jinja2env.get_template(self.template_filename)
-            t.render(data=data)
+            template = jinja2env.get_template(self.template_filename)
+            template.render(data=data)
         #pylint: disable=bare-except
         except:
             sys.stderr.write(
@@ -64,7 +66,7 @@ def process_with_template(self, contents):
             sys.exit(1)
         #pylint: enable=bare-except
 
-        return t.render(data=data)
+        return template.render(data=data)
 
 
     def get_target_uri(self, docname, typ=None):
@@ -84,7 +86,8 @@ def write_doc(self, docname, doctree):
         docutils_writer = DocBookWriter(
             root_element=self.root_element,
             document_id=docname,
-            output_xml_header=(self.template_filename == None)
+            output_xml_header=(self.template_filename == None),
+            use_xml_id_in_titles=sphinx_app.config.docbook_use_xml_id_in_titles,
         )
 
         # get the docbook output.
@@ -109,4 +112,5 @@ def setup(app):
     # pylint: enable=global-variable-undefined, invalid-name
     app.add_config_value('docbook_default_root_element', 'section', 'env')
     app.add_config_value('docbook_template_file', None, 'env')
+    app.add_config_value('docbook_use_xml_id_in_titles', False, 'env')
     app.add_builder(DocBookBuilder)

sphinx_docbook/docbook_writer.py

@@ -22,6 +22,7 @@ def _print_error(text, node = None):
     if node:
         sys.stderr.write(f"  {node}\n")
 
+_NAMESPACE_ID = '{http://www.w3.org/XML/1998/namespace}id'
 
 class DocBookWriter(writers.Writer):
     """
@@ -38,21 +39,29 @@ class DocBookWriter(writers.Writer):
     """
     # pylint: disable=attribute-defined-outside-init
 
-    def __init__(self, root_element, document_id=None, output_xml_header=True):
+    def __init__(
+        self,
+        root_element: str,
+        document_id: str = None,
+        output_xml_header: bool = True,
+        use_xml_id_in_titles: bool = False,
+    ):
         """Initialize the writer. Takes the root element of the resulting
         DocBook output as its sole argument."""
         writers.Writer.__init__(self)
         self.document_type = root_element
         self.document_id = document_id
         self.output_xml_header = output_xml_header
+        self.use_xml_id_in_titles = use_xml_id_in_titles
 
     def translate(self):
         """Call the translator to translate the document."""
         self.visitor = DocBookTranslator(
             self.document,
             self.document_type,
             self.document_id,
-            self.output_xml_header
+            self.output_xml_header,
+            self.use_xml_id_in_titles,
         )
         self.document.walkabout(self.visitor)
         self.output = self.visitor.astext()
@@ -64,8 +73,14 @@ class DocBookTranslator(nodes.NodeVisitor):
     # pylint: disable=missing-function-docstring, unnecessary-pass
     # pylint: disable=unused-argument
 
-    def __init__(self, document, document_type, document_id = None,
-                 output_xml_header=True):
+    def __init__(
+        self,
+        document,
+        document_type: str,
+        document_id: str = None,
+        output_xml_header: bool = True,
+        use_xml_id_in_titles: bool = False,
+    ):
         """Initialize the translator. Takes the root element of the resulting
         DocBook output as its sole argument."""
         nodes.NodeVisitor.__init__(self, document)
@@ -75,6 +90,7 @@ def __init__(self, document, document_type, document_id = None,
         self.document_id = document_id
         self.in_first_section = False
         self.output_xml_header = output_xml_header
+        self.use_xml_id_in_titles = use_xml_id_in_titles
 
         self.in_pre_block = False
         self.in_figure = False
@@ -541,16 +557,15 @@ def depart_subtitle(self, node):
 
     def visit_title(self, node):
         attribs = {}
-        # first check to see if an {http://www.w3.org/XML/1998/namespace}id was
-        # supplied.
-        if len(node['ids']) > 0:
-            attribs['{http://www.w3.org/XML/1998/namespace}id'] = node['ids'][0]
-        elif len(node.parent['ids']) > 0:
-            # If the parent node has an ID, we can use that and add '.title' at
-            # the end to make a deterministic title ID.
-            attribs[
-                '{http://www.w3.org/XML/1998/namespace}id'
-            ] = f"{node.parent['ids'][0]}.title"
+        if self.use_xml_id_in_titles:
+            # first check to see if an {http://www.w3.org/XML/1998/namespace}id
+            # was supplied.
+            if len(node['ids']) > 0:
+                attribs[_NAMESPACE_ID] = node['ids'][0]
+            elif len(node.parent['ids']) > 0:
+                # If the parent node has an ID, we can use that and add
+                # '.title' at the end to make a deterministic title ID.
+                attribs[_NAMESPACE_ID] = f"{node.parent['ids'][0]}.title"
         self._push_element('title', attribs)