如何在Sphinx中为torch.FloatStorage添加源码跳转链接？

Hey there! Let's walk through how to add those handy [source] links that jump directly to the code file for your classes and methods—just like you see in PyTorch's official docs.

Option 1: Use Sphinx with sphinx.ext.linkcode (Recommended) #

If you're building your docs with Sphinx (the standard tool for Python documentation), the linkcode extension is the way to go. It automatically generates those source links for you. Here's how to set it up:

• Enable the extension in your conf.py:
  Add 'sphinx.ext.linkcode' to your extensions list:

  extensions = [
      # ... other extensions like sphinx.ext.autodoc
      'sphinx.ext.linkcode',
  ]
  

• Define a linkcode_resolve function in conf.py:
  This function tells Sphinx where to find the source code for each object. Adjust the paths/URLs to match your project:

  def linkcode_resolve(domain, info):
      if domain != 'py':
          return None
      if not info['module']:
          return None
      filename = info['module'].replace('.', '/') + '.py'
      # For offline docs (local file path)
      return f'../{filename}'
      # For online docs (e.g., GitHub repo)
      # return f'https://github.com/your-username/your-repo/blob/main/{filename}'
  

  When you build your docs, Sphinx will automatically append a [source] link next to each class and method, pointing to the correct file.

Option 2: Manual Linking (For Custom Docs) #

If you're building docs manually (not using Sphinx), you can add links directly with Markdown to mirror PyTorch's style:

• For classes:

  `class your_package.FloatStorage` [source](../path/to/your/storage.py)
  

  Replace the path with the relative/absolute location of your source file.

• For methods (with line-specific anchors):
  If your tool supports line anchors (most static site generators do), link directly to the method's starting line:

  `byte()` Casts this storage to byte type [source](../path/to/your/storage.py#L42)
  

  The #L42 suffix jumps users straight to line 42 where the byte() method is defined.

Pro Tip #

Stick to consistent path formats—relative paths work best for docs hosted alongside your code, while absolute URLs are ideal for online docs. If using Git, you can even link to specific commit hashes (e.g., GitHub's blob URLs) to ensure users see the code version matching your docs.

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