From 4718cb2e7fbc23d5074b1de775c5c3f170a5013a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20Vo=C5=99=C3=AD=C5=A1ek?= <mvorisek@mvorisek.cz>
Date: Thu, 3 Aug 2023 16:15:08 +0200
Subject: [PATCH] deprecate "ns" ref in favor of "namespace"

---
 doc/reference.rst          |  4 ++--
 sphinxcontrib/phpdomain.py | 12 +++++++++---
 test/rst_doc.html          |  4 ++--
 test/rst_doc.md            |  4 ++--
 4 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/doc/reference.rst b/doc/reference.rst
index 2a3232a..b63b1eb 100644
--- a/doc/reference.rst
+++ b/doc/reference.rst
@@ -155,12 +155,12 @@ Cross Referencing
 The following roles refer to php objects and are links are generated if a 
 matching directive is found:
 
-.. rst:role:: php:ns
+.. rst:role:: php:namespace
 
    Reference a namespace. Nested namespaces need to be separated by two \\ due 
    to the syntax of ReST::
    
-      .. php:ns:`LibraryName\\SubPackage` will work correctly.
+      .. php:namespace:`LibraryName\\SubPackage` will work correctly.
 
 .. rst:role:: php:func
 
diff --git a/sphinxcontrib/phpdomain.py b/sphinxcontrib/phpdomain.py
index 4c07007..042068c 100644
--- a/sphinxcontrib/phpdomain.py
+++ b/sphinxcontrib/phpdomain.py
@@ -751,7 +751,7 @@ class PhpDomain(Domain):
         "class": ObjType(_("class"), "class", "obj"),
         "attr": ObjType(_("attribute"), "attr", "obj"),
         "exception": ObjType(_("exception"), "exc", "obj"),
-        "namespace": ObjType(_("namespace"), "ns", "obj"),
+        "namespace": ObjType(_("namespace"), "namespace", "obj"),
         "interface": ObjType(_("interface"), "interface", "obj"),
         "trait": ObjType(_("trait"), "trait", "obj"),
         "enum": ObjType(_("enum"), "enum", "obj"),
@@ -784,7 +784,8 @@ class PhpDomain(Domain):
         "meth": PhpXRefRole(fix_parens=False),
         "attr": PhpXRefRole(),
         "const": PhpXRefRole(),
-        "ns": PhpXRefRole(),
+        "namespace": PhpXRefRole(),
+        "ns": PhpXRefRole(),  # deprecated, use "namespace"
         "obj": PhpXRefRole(),
         "interface": PhpXRefRole(),
         "trait": PhpXRefRole(),
@@ -826,7 +827,12 @@ def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode):
         return []
 
     def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
-        if typ == "ns" or typ == "obj" and target in self.data["namespaces"]:
+        if (
+            typ == "namespace"
+            or typ == "ns"
+            or typ == "obj"
+            and target in self.data["namespaces"]
+        ):
             docname, synopsis, deprecated = self.data["namespaces"].get(
                 target, ("", "", "")
             )
diff --git a/test/rst_doc.html b/test/rst_doc.html
index 49358c5..e8a7cd2 100644
--- a/test/rst_doc.html
+++ b/test/rst_doc.html
@@ -909,7 +909,7 @@ <h3>Test Case - not including namespace<a class="headerlink" href="#test-case-no
         <p>Within a namespace context you don&#x2019;t need to include the namespace in links.</p>
         <p>
           <a class="reference internal" href="#namespace-LibraryName">
-            <code class="xref php php-ns docutils literal notranslate">
+            <code class="xref php php-namespace docutils literal notranslate">
               <span class="pre">LibraryName</span>
             </code>
           </a>
@@ -1249,7 +1249,7 @@ <h2>Nested namespaces<a class="headerlink" href="#namespace-LibraryName\SubPacka
         <h3>Test Case - Test subpackage links<a class="headerlink" href="#test-case-test-subpackage-links" title="Permalink to this heading">&#xB6;</a></h3>
         <p>
           <a class="reference internal" href="#namespace-LibraryName\SubPackage">
-            <code class="xref php php-ns docutils literal notranslate">
+            <code class="xref php php-namespace docutils literal notranslate">
               <span class="pre">LibraryName\SubPackage</span>
             </code>
           </a>
diff --git a/test/rst_doc.md b/test/rst_doc.md
index a252b4b..9636dda 100644
--- a/test/rst_doc.md
+++ b/test/rst_doc.md
@@ -302,7 +302,7 @@ Test Case - not including namespace
 
 Within a namespace context you don't need to include the namespace in links.
 
-:php:ns:`LibraryName`
+:php:namespace:`LibraryName`
 
 :php:func:`namespaced_function()`
 
@@ -416,7 +416,7 @@ Nested namespaces
 Test Case - Test subpackage links
 ---------------------------------
 
-:php:ns:`LibraryName\\SubPackage`
+:php:namespace:`LibraryName\\SubPackage`
 
 :php:ns:`\\LibraryName\\SubPackage`