Add a fullyQualifiedTitles option (#187)

By default, the behavior is unchanged, however when set to
True, all page titles for structures, unions, classes etc
include the namespace as a prefix.

Author: 5p4k

docs/reference/configs.rst

@@ -500,6 +500,8 @@ something like this, where special treatment is given to File pages specifically
 
 .. autodata:: exhale.configs.includeTemplateParamOrderList
 
+.. autodata:: exhale.configs.fullyQualifiedTitles
+
 .. autodata:: exhale.configs.pageLevelConfigMeta
 
 .. autodata:: exhale.configs.repoRedirectURL

exhale/configs.py

@@ -840,6 +840,23 @@ class and file hierarchies.
    other items being documented **only** work in HTML.
 '''
 
+fullyQualifiedTitles = False
+'''
+**Optional**
+    For Classes, Structs, Enum, Variables, Typedefs, Unions: everything except Functions.
+    Exhale can generate a fully qualified title on the item page, that is, it will
+    include the namespace as a prefix to the function. This will thus be reflected
+    in the table of contents.
+
+**Value in** ``exhale_args`` (bool)
+    This feature can be useful when you have different items with the same name but
+    in different namespace, e.g. ``server_side::error`` and ``client_side::error``.
+    By default, Exhale will generate a page title with the item name only (e.g.
+    ``error``), which might look confusing as there would be multiple entries with the
+    same name. By setting this to ``True``, all titles and ToC entries will be
+    qualified with the corresponding namespace.
+'''
+
 pageLevelConfigMeta = None
 '''
 **Optional**
@@ -1505,6 +1522,7 @@ def apply_sphinx_configurations(app):
         ("treeViewBootstrapLevels",                      int),
         # Page Level Customization
         ("includeTemplateParamOrderList",               bool),
+        ("fullyQualifiedTitles",                        bool),
         ("pageLevelConfigMeta",             six.string_types),
         ("repoRedirectURL",                 six.string_types),
         ("contentsDirectives",                          bool),

exhale/graph.py

@@ -2495,24 +2495,28 @@ class view hierarchy (<a href="..."> for the ``createTreeView = True`` option).
                         utils.fancyError(
                             f"Exhale does not know how to process {node.name}, "
                             f"tokenized to {template_tokens}.  Please report this bug.")
-                class_name = class_name.split("::")[-1]
+                if not configs.fullyQualifiedTitles:
+                    class_name = class_name.split("::")[-1]
 
                 # Join up the final class name and any potentially skipped templates.
                 title = utils.join_template_tokens([class_name] + skipped)
-            else:
+            elif not configs.fullyQualifiedTitles:
                 title = node.name.split("::")[-1]
+            else:
+                title = node.name
 
             # additionally, I feel that nested classes should have their fully qualified
-            # name without namespaces for clarity
-            prepend_parent = False
-            if node.kind in ["class", "struct", "enum", "union"]:
-                if node.parent is not None and node.parent.kind in ["class", "struct"]:
-                    prepend_parent = True
-            if prepend_parent:
-                title = "{parent}::{child}".format(
-                    parent=node.parent.name.split("::")[-1],
-                    child=title
-                )
+            # name without namespaces for clarity even if the titles are not fully qualified
+            if not configs.fullyQualifiedTitles:
+                prepend_parent = False
+                if node.kind in ["class", "struct", "enum", "union"]:
+                    if node.parent is not None and node.parent.kind in ["class", "struct"]:
+                        prepend_parent = True
+                if prepend_parent:
+                    title = "{parent}::{child}".format(
+                        parent=node.parent.name.split("::")[-1],
+                        child=title
+                    )
 
         # `unique_id` and `title` should be set approriately for all nodes by this point
         if node.kind in SPECIAL_CASES: