Add sphinx.util.nodes:make_id() to generate better node_id

1 files changed, 23 insertions, 0 deletions

diff --git a/sphinx/util/nodes.py b/sphinx/util/nodes.py
index f33a6a001..7c7300c60 100644
--- a/sphinx/util/nodes.py
+++ b/sphinx/util/nodes.py
@@ -28,6 +28,7 @@ if False:
     # For type annotation
     from typing import Type  # for python3.5.1
     from sphinx.builders import Builder
+    from sphinx.environment import BuildEnvironment
     from sphinx.utils.tags import Tags
 
 logger = logging.getLogger(__name__)
@@ -435,6 +436,28 @@ def inline_all_toctrees(builder: "Builder", docnameset: Set[str], docname: str,
     return tree
 
 
+def make_id(env: "BuildEnvironment", document: nodes.document,
+            prefix: str = '', term: str = None) -> str:
+    """Generate an appropriate node_id for given *prefix* and *term*."""
+    node_id = None
+    if prefix:
+        idformat = prefix + "-%s"
+    else:
+        idformat = document.settings.id_prefix + "%s"
+
+    # try to generate node_id by *term*
+    if prefix and term:
+        node_id = nodes.make_id(idformat % term)
+        if node_id == prefix:
+            # *term* is not good to generate a node_id.
+            node_id = None
+
+    while node_id is None or node_id in document.ids:
+        node_id = idformat % env.new_serialno(prefix)
+
+    return node_id
+
+
 def make_refnode(builder: "Builder", fromdocname: str, todocname: str, targetid: str,
                  child: Node, title: str = None) -> nodes.reference:
     """Shortcut to create a reference node."""