Add currentmodule directive

Add a new directive that allows namespaces to be re-used and enables
`namespace` to be the canonical reference. This re-uses patterns used in
the ruby and python domains and gives a solution to #27

Author: markstory

sphinxcontrib/phpdomain.py

@@ -457,6 +457,28 @@ def run(self):
         return ret
 
 
+class PhpCurrentNamespace(Directive):
+    """
+    This directive is just to tell Sphinx that we're documenting
+    stuff in namespace foo, but links to namespace foo won't lead here.
+    """
+
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {}
+
+    def run(self):
+        env = self.state.document.settings.env
+        modname = self.arguments[0].strip()
+        if modname == 'None':
+            env.temp_data['php:namespace'] = None
+        else:
+            env.temp_data['php:namespace'] = modname
+        return []
+
+
 class PhpXRefRole(XRefRole):
     """
     Provides cross reference links for PHP objects
@@ -578,6 +600,8 @@ class PhpDomain(Domain):
         'interface': PhpClasslike,
         'trait': PhpClasslike,
         'namespace': PhpNamespace,
+        'currentmodule': PhpCurrentNamespace,
+        'currentnamespace': PhpCurrentNamespace,
     }
 
     roles = {

test/test_doc.rst

@@ -316,6 +316,7 @@ Test Case - not including namespace
 
 :php:class:`LibraryClass`
 
+
 :php:class:`~LibraryName\\LibraryClass`
 
 :php:func:`LibraryClass::instanceMethod`
@@ -326,6 +327,10 @@ Test Case - not including namespace
 
 :php:const:`LibraryClass::TEST_CONST`
 
+:php:class:`LibraryName\\OtherClass`
+
+:php:class:`LibraryName\\ThirdClass`
+
 :php:class:`NamespaceClass`
 
 :php:func:`NamespaceClass::firstMethod`

test/test_doc2.rst

@@ -23,3 +23,22 @@ Instance of this interface is returned by :php:meth:`Imagine\Image\ImageInterfac
 
     :returns: Imagine\Draw\DrawerInterface
 
+Re-used namespace
+=================
+
+.. php:currentmodule:: LibraryName
+
+No indexing errors or links should point to this namespace.
+
+.. php:class:: ThirdClass
+
+    Another class in a currentmodule block
+
+.. php:currentnamespace:: LibraryName
+
+No indexing errors or links should point to this namespace.
+
+.. php:class:: OtherClass
+
+    Another class in a reused namespace
+