Add module name to doc source (to allow intersphinx usage)

[arthur-tacca]

Fixes #341. With this change, typing_extensions can be used from other libraries' documentation via intersphinx.

I included add_module_names = False, which means that the typing_extensions. prefix will not show up in the docs before identifiers, because that was the consensus on the issue report.

However, while testing I did notice another: even with that setting turned on, the anchors are still changed to include the prefix. For example:

• Current link: https://typing-extensions.readthedocs.io/en/latest/#Literal
• New link: https://typing-extensions.readthedocs.io/en/latest/#typing_extensions.Literal

That will break any existing external pages that link directly to an anchor within the docs.

[ghost]

All commit authors signed the Contributor License Agreement.

[AlexWaygood]

However, while testing I did notice another: even with that setting turned on, the anchors are still changed to include the prefix. For example:

* Current link: [typing-extensions.readthedocs.io/en/latest/#Literal](https://typing-extensions.readthedocs.io/en/latest/#Literal)

* New link: [typing-extensions.readthedocs.io/en/latest/#typing_extensions.Literal](https://typing-extensions.readthedocs.io/en/latest/#typing_extensions.Literal)

That will break any existing external pages that link directly to an anchor within the docs.

Is there any way to add redirects for those, that you know of?

[arthur-tacca]

Not that I'm aware of. I tried manually inserting a target (which Sphinx/rST terminology for an anchor):

.. _NamedTuple:

.. class:: NamedTuple

   See :py:class:`typing.NamedTuple`.

Even putting aside how much clutter this would add, it doesn't work: Sphinx lower cases the label, so you can link to #namedtuple but not #NamedTuple. I tried quoting the target name but that had no effect.

[AlexWaygood]

It's a shame about the anchors, but I think this is worth it for intersphinx. LGTM, but I'll wait to see if any other maintainers object.

[AlexWaygood]

@CAM-Gerlach, if you have the time -- do you know any way of preserving the anchors here or easily adding redirects, by any chance?

[arthur-tacca]

Actually I spoke too soon – I found a way to fix up the HTML by delving into Sphinx's more advanced customisation points. Adding this to the end of conf.py seems to do it:

from sphinx.writers.html import HTMLTranslator
from docutils.nodes import Element, Node, Text

class MyTranslator(HTMLTranslator):
    def visit_desc_signature(self, node: Element) -> None:
        desc_name = node.get("fullname")
        if desc_name:
            self.body.append(f'<span id="{desc_name}"></span>')
        super().visit_desc_signature(node)

def setup(app):
     app.set_translator('html', MyTranslator)

It links a few pixels too high compared to the real anchors but I don't think that's a big deal. And it doesn't do anything for TypeVar (in fact that entry is the reason for the check that desc_name is truthy) because it doesn't have a link to it at all, even before this pull request.

Any thoughts?

[AlexWaygood]

Thanks for looking into it! That seems worth it to me; it's not too much added complexity to our conf.py file.

[arthur-tacca]

OK I added that code in a new commit. (I also removed the line of config that referenced the non-existent _static directory, as this was causing a warning.)

[JelleZijlstra]

Could you fix the lint issue in CI? (Probably just run Black on conf.py.)

[arthur-tacca]

@JelleZijlstra I think this fixes it. Also I realised that I used a slightly wrong class from Sphinx (HTMLTranslator instead of HTML5Translator) which meant the font of the identifier being documented appeared very slightly smaller than previously, so I also fixed that.

[arthur-tacca]

Thank you! 🎉