namespace needs to exactly match `external_cpp_references` config

[2bndy5]

~This is unrelated to the changes here, but~ I'm reviewing the docs and I found the external_cpp_references example doesn't work when the parameter data type is explicitly of global scope (::nlohmann::json) rather it works when using nlohmann::json (as exactly defined in the conf.py setting). I'm not sure if there's a way to strip the global namespace using cpp_strip_namespaces_from_signatures option.

Originally posted by @2bndy5 in https://github.com/jbms/sphinx-immaterial/issues/99#issuecomment-1172808163

[2bndy5]

relevant comment from @jbms:

The external_cpp_references extension won't be affected by cpp_strip_namespaces_from_signatures --- that option only affects how they are displayed in the HTML output, but not how the cross-referencing works.

In external_cpp_references I think we should always strip a leading :: from any targets before trying to match them.

I agree that it would also be nice if cpp_strip_namespces_from_signatures could also support stripping a leading :: though.

[2bndy5]

In trying to reproduce this, I think the build env is somehow effecting this. If I add the global :: and rebuild with -a, then the data type is still correctly hyperlinked (contradictory of the observation in OP that was based on a fresh build).

[2bndy5]

While the original experience seems to have been solved in https://github.com/jbms/sphinx-immaterial/pull/99/commits/315e3bc710f3b34909e910ca99ad2b72e928b6a7 , the remaining observations about global scope operators still should be addressed.

[2bndy5]

In external_cpp_references I think we should always strip a leading :: from any targets before trying to match them.

Locally, I've altered external_cpp_references to strip any leading :: from the config's keys (on builder-inited event). I also see that the :: is already stripped before matching the pending-xref. https://github.com/jbms/sphinx-immaterial/blob/c7e5ec93450ad78f54da0fe2544862b8472aa71a/sphinx_immaterial/apidoc/cpp/external_cpp_references.py#L39-L40 I can submit a PR for review...

---

I agree that it would also be nice if cpp_strip_namespces_from_signatures could also support stripping a leading :: though.

In exploring this, I think I stumbled onto a separate issue. It looks like Sphinx has trouble interpreting C++ type identifiers if the type begins with a ::.

When I made the following changes

--- a/docs/apidoc/cpp/index.rst
+++ b/docs/apidoc/cpp/index.rst
@@ -20,9 +20,9 @@ C++ domain customization
 
       .. cpp:type:: my_ns2::my_nested_ns::B
 
-      .. cpp:type:: my_ns3::C
+      .. cpp:type:: ::my_ns3::C
 
-      .. cpp:function:: void my_ns1::MyFunction(my_ns1::A x, my_ns2::my_nested_ns::B y, my_ns3::C);
+      .. cpp:function:: void my_ns1::MyFunction(my_ns1::A x, my_ns2::my_nested_ns::B y, ::my_ns3::C);

I get errors saying:

docs\apidoc\cpp\index.rst:23: WARNING: cpp:identifier reference target not found: ::my_ns3
docs\apidoc\cpp\index.rst:25: WARNING: cpp:identifier reference target not found: ::my_ns3

But the type C is resolved from pending xref. This problem seems to be theme-specific as it does not occur with the alabaster theme.

[jbms]

I get errors saying:

docs\apidoc\cpp\index.rst:23: WARNING: cpp:identifier reference target not found: ::my_ns3
docs\apidoc\cpp\index.rst:25: WARNING: cpp:identifier reference target not found: ::my_ns3

But the type C is resolved from pending xref. This problem seems to be theme-specific as it does not occur with the alabaster theme.

I'm a bit surprised that the issue does not occur with other themes. I thought that issue is the one mentioned here:

https://github.com/jbms/sphinx-immaterial/blob/c7e5ec93450ad78f54da0fe2544862b8472aa71a/docs/conf.py#L415-L422

[2bndy5]

I forgot about the ignored nitpicky errors. Looks like there's some duplicates in the list. I re-run my test of alabaster with -n, and the errors indeed show up. But, our nox session (docs(html)) doesn't use nitpicky mode, so this shouldn't have been observed.

EDIT: I now see this in the conf.py: https://github.com/jbms/sphinx-immaterial/blob/c7e5ec93450ad78f54da0fe2544862b8472aa71a/docs/conf.py#L401