Repository: nilearn/nilearn

Issue:
[DOC] Fix Sphinx issues related to adding new experimental module and typing
### Is there an existing issue for this?

- [X] I have searched the existing issues

### Describe your proposed suggestion in detail.

1. Linkcode extension error https://github.com/nilearn/nilearn/pull/4017#issuecomment-1739213117 and related workaround: https://github.com/nilearn/nilearn/blob/9133bd98ddc085e14d545fd0439be621c8679f91/doc/sphinxext/github_link.py#L43-L44

2. See Sphinx warning https://github.com/nilearn/nilearn/pull/4017#issuecomment-1739630179 and related hotfix of remving sphinx role here: https://github.com/nilearn/nilearn/blob/9133bd98ddc085e14d545fd0439be621c8679f91/doc/modules/experimental.rst?plain=1#L10

3. Sphinx autodoc has an issue with resolving external libraries like numpy when using typehints. It seems to be a bug similar to what is reported here https://github.com/sphinx-doc/sphinx/issues/10785. For now this autodoc argument is added to hide the typehints from the integrated typing https://github.com/nilearn/nilearn/blob/9133bd98ddc085e14d545fd0439be621c8679f91/doc/conf.py#L57
And if we have both docstrings and the typehints we have double rendering in the docs of the description of a e.g. class and this is redundant and looks ugly so we should also discuss how we want to approach adding docstrings + typing and how to configure what will be displayed. I'll post an example once the dev docs are built

### List any pages that would be impacted.

_No response_


Discussion:
Just fyi I updated the issue description. Point 3 might warrant some discussion. It'll be good to have a strategy for this before we go on typing the stable API
I suspect a "practical" way forward could be to open a draft PR where we add some type annotation to:
- a public function and
- a public class and its method 
 
and figure out:

1.

- the type checking config
- sphinx config 
 
that do not fail or throw warnings

2.

that looks nice in the rendered doc.
This is how a typed class with a docstring is rendered now for example:
![image](https://github.com/nilearn/nilearn/assets/63292494/72a66450-4b95-4534-83e4-d93c0504f9c0)

Note the parameters and attributes are repeated in red below the docstrings that describes them.

Link to new module in the docs: https://nilearn.github.io/dev/modules/experimental.html#module-nilearn.experimental


Resolving patch:
diff --git a/doc/sphinxext/github_link.py b/doc/sphinxext/github_link.py
--- a/doc/sphinxext/github_link.py
+++ b/doc/sphinxext/github_link.py
@@ -40,9 +40,12 @@ def _linkcode_resolve(domain, info, package, url_fmt, revision):
 
     class_name = info["fullname"].split(".")[0]
     module = __import__(info["module"], fromlist=[class_name])
-    if info["module"] == "nilearn.experimental.surface":
+    # For typed parameters, this will try to get uninitialized attributes
+    # and fail
+    try:
+        obj = attrgetter(info["fullname"])(module)
+    except AttributeError:
         return
-    obj = attrgetter(info["fullname"])(module)
 
     # Unwrap the object to get the correct source
     # file in case that is wrapped by a decorator


Test patch: