修改intersphinx_mapping后Sphinx仍默认链接Python2文档求助

I’ve run into this exact quirk with Sphinx 1.7.0 and intersphinx before—here’s how to fix it so your Python object references default to Python 3 without needing the python: prefix every time:

• Clean up your intersphinx_mapping in conf.py
  Make sure you only have the Python 3 mapping defined, and remove any leftover Python 2 entries. Your config should look something like this:

  intersphinx_mapping = {
      'python': ('https://docs.python.org/3', None),
      # Remove any lines pointing to Python 2 docs, e.g., ('python2', ...)
  }
  

  Sometimes if you had both Python 2 and 3 mappings configured, Sphinx might prioritize the older one by default.

• Delete the intersphinx cache
  Sphinx caches intersphinx metadata to speed up builds, and old Python 2 cache files might be overriding your new settings. Look for the .intersphinx directory inside your build output folder (usually _build/html/.intersphinx or similar) and delete it entirely. Then rebuild your docs from scratch with make html (or your build command of choice).

• Verify your cross-reference syntax
  For most Python objects, you shouldn’t need a prefix anymore once the above steps are done. For example, writing :class:str`` should now link directly to the Python 3 str docs instead of Python 2. If you still see old links, double-check that you haven’t accidentally left any python2: prefixes in your source files.

This should resolve the default linking behavior—Sphinx 1.7.0 relies heavily on that cache, so deleting it is often the missing piece when config changes don’t take effect immediately.

内容的提问来源于stack exchange，提问作者philngo