From a8465c7cc1db65f86665e0446f9f4e07a441dc05 Mon Sep 17 00:00:00 2001
From: "James E. Blair" <jim@acmegating.com>
Date: Thu, 11 Nov 2021 14:22:53 -0800
Subject: [PATCH] Add :zuul:path support

This is to support documenting zookeeper paths in the Zuul developer
docs.

Change-Id: Id29eee89b38b34a3dac09750d6cabb442551e211
---
 doc/source/example-paths.rst | 32 +++++++++++++++++
 doc/source/index.rst         |  1 +
 zuul_sphinx/zuul.py          | 70 ++++++++++++++++++++++++++++++++++--
 3 files changed, 101 insertions(+), 2 deletions(-)
 create mode 100644 doc/source/example-paths.rst

diff --git a/doc/source/example-paths.rst b/doc/source/example-paths.rst
new file mode 100644
index 0000000..92f7ed1
--- /dev/null
+++ b/doc/source/example-paths.rst
@@ -0,0 +1,32 @@
+ZooKeeper Paths
+---------------
+
+.. path:: zuul
+
+   This is an example Zookeeper path
+
+.. path:: zuul/tenant
+
+   A sub path.  Since paths can get quite long, you may choose to
+   indent or to specify the full path.  The signature will appear the
+   same either way.
+
+   .. path:: <bar>
+      :ephemeral:
+
+      Another sub path.
+
+      .. path:: lock
+         :type: RLock
+         :ephemeral:
+
+         Another sub path.
+
+.. path:: zuul-system
+
+   Another top level path.
+
+References
+==========
+
+This is a path role: :path:`zuul/tenant/<bar>/lock`
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 41799db..1b5dd49 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -44,6 +44,7 @@ Examples
    example-roles
    example-autodoc
    example-statistics
+   example-paths
 
 Indices and tables
 ------------------
diff --git a/zuul_sphinx/zuul.py b/zuul_sphinx/zuul.py
index 2add2ed..f578884 100644
--- a/zuul_sphinx/zuul.py
+++ b/zuul_sphinx/zuul.py
@@ -234,7 +234,9 @@ class ZuulObjectDescription(ZuulDirective, ObjectDescription):
         'var': 'variable',
         'jobvar': 'job variable',
         'rolevar': 'role variable',
+        'path': 'path',
     }
+    separator = '.'
 
     def get_path(self):
         return self.env.ref_context.get('zuul:attr_path', [])
@@ -244,12 +246,12 @@ class ZuulObjectDescription(ZuulDirective, ObjectDescription):
 
     @property
     def parent_pathname(self):
-        return '.'.join(self.get_display_path())
+        return self.separator.join(self.get_display_path())
 
     @property
     def full_pathname(self):
         name = self.names[-1].lower()
-        return '.'.join(self.get_path() + [name])
+        return self.separator.join(self.get_path() + [name])
 
     def add_target_and_index(self, name, sig, signode):
         targetname = self.objtype + '-' + self.full_pathname
@@ -510,6 +512,67 @@ class ZuulStatDirective(ZuulObjectDescription):
         return sig
 
 
+class ZuulPathDirective(ZuulObjectDescription):
+    has_content = True
+
+    option_spec = {
+        'ephemeral': lambda x: x,
+        'noindex': lambda x: x,
+        'example': lambda x: x,
+        'type': lambda x: x,
+    }
+
+    separator = '/'
+
+    def before_content(self):
+        path = self.env.ref_context.setdefault('zuul:attr_path', [])
+        path.append(self.names[-1])
+        path = self.env.ref_context.setdefault('zuul:display_attr_path', [])
+        path.append(self.names[-1])
+
+    def after_content(self):
+        path = self.env.ref_context.get('zuul:attr_path')
+        if path:
+            path.pop()
+        path = self.env.ref_context.get('zuul:display_attr_path')
+        if path:
+            path.pop()
+
+    def handle_signature(self, sig, signode):
+        path = self.get_display_path()
+        signode['is_multiline'] = True
+        line = addnodes.desc_signature_line()
+        line['add_permalink'] = True
+        line += addnodes.desc_addname('/', '/')
+        for x in path:
+            line += addnodes.desc_addname(x + '/', x + '/')
+        for x in sig.split('/')[:-1]:
+            line += addnodes.desc_addname(x + '/', x + '/')
+        last = sig.split('/')[-1]
+        line += addnodes.desc_name(last, last)
+        signode += line
+        if 'type' in self.options:
+            line = addnodes.desc_signature_line()
+            line += addnodes.desc_type('Type: ', 'Type: ')
+            line += nodes.emphasis(self.options['type'],
+                                   self.options['type'])
+            signode += line
+        elif 'ephemeral' in self.options:
+            line = addnodes.desc_signature_line()
+            signode += line
+        if 'ephemeral' in self.options:
+            # This is appended to the type line, or a new blank line
+            # if no type.
+            line += addnodes.desc_annotation(' (ephemeral)', ' (ephemeral)')
+        if 'example' in self.options:
+            line = addnodes.desc_signature_line()
+            line += addnodes.desc_type('Example: ', 'Example: ')
+            line += nodes.literal(self.options['example'],
+                                  self.options['example'])
+            signode += line
+        return sig
+
+
 ######################################################################
 #
 # Autodoc directives
@@ -611,6 +674,7 @@ class ZuulDomain(Domain):
         'stat': ZuulStatDirective,
         'jobvar': ZuulJobVarDirective,
         'rolevar': ZuulRoleVarDirective,
+        'path': ZuulPathDirective,
         # Autodoc directives
         'autojob': ZuulAutoJobDirective,
         'autojobs': ZuulAutoJobsDirective,
@@ -643,6 +707,8 @@ class ZuulDomain(Domain):
                            warn_dangling=True),
         'rolevar': XRefRole(innernodeclass=nodes.inline,  # type: ignore
                             warn_dangling=True),
+        'path': XRefRole(innernodeclass=nodes.inline,  # type: ignore
+                         warn_dangling=True),
     }
 
     initial_data = {