sphinx-peek

Sphinx扩展，用于查看引用

开发中！

该扩展在所选引用旁边添加一个小图标，可以点击查看引用的目标。

• 可调整大小的模态窗口
• 在滚动和窗口调整大小时锚定到引用
• 支持嵌套引用查看

请参阅https://sphinx-peek.readthedocs.io/中的文档

开发笔记

又一个用于预览链接的sphinx扩展！

目标

• 尽可能简单
• 所有CSS和JavaScript都包含在扩展中

已经有

• sphinx-hoverxref:

  此方法通过向某些内部和intersphinx引用添加特定的HTML类，然后使用JavaScript在鼠标悬停时显示预览窗口来实现，该窗口包含通过向ReadTheDocs服务器发出API调用获取的内容。

  这种方法的主要缺点是，它仅在文档由ReadTheDocs提供时才能工作。此外，intersphinx预览仅在目标文档也由ReadTheDocs提供时才能工作。

• sphinx-tippy

  此方法通过在构建过程中预先创建所有预览内容来实现，并使用tippy.js在鼠标悬停时显示预览窗口。

  缺点是可能难以使预览内容看起来很好，并且难以与其他文档主题集成。

• sphinx-preview

  此方法通过使用JavaScript添加iframe窗口来预览。

sphinx-preview的更改

本扩展采用了 sphinx-preview 的方法，但进行了一些修改，包括

1. 用原生 JavaScript 替换了 jQuery 的使用
2. 始终使用可点击的图标来显示预览窗口，而不是鼠标悬停（我认为这给了用户更多的控制权，并理解哪些链接可以预览）
3. 修复了滚动到锚点行为和一些预览窗口定位的 bug
4. 在滚动和窗口调整大小时，将预览窗口锚定到参考位置
5. 出于开发目的，还在 JavaScript 代码中添加了 JSDoc 类型注解，并使用 pre-commit 钩子检查代码的格式和类型安全性。