| Name | sphinx_peek JSON |
| Version |
0.0.3
JSON |
| download |
| home_page | None |
| Summary | A sphinx extension for peeking at internal references. |
| upload_time | 2024-01-26 01:23:24 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
sphinx
extension
preview
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# sphinx-peek
[![PyPI][pypi-badge]][pypi-link]
> Sphinx extension for peeking at references
**In Development!**
The extension adds a small icon next to select references,
that can be clicked to peek at the target of the reference.
- Resizable modal window
- Anchored to the reference during scrolling and window resizing
- Nested reference peeking supported
See documentation at <https://sphinx-peek.readthedocs.io/>
## Development notes
Yet another sphinx-extension for previewing links!
Aims:
- As simple as possible
- All CSS and JavaScript is bundled with the extension
There is already:
- [sphinx-hoverxref](https://github.com/readthedocs/sphinx-hoverxref):
This works by adding specific HTML classes to certain internal and intersphinx references,
and then using JavaScript to show a preview window on mouseover,
which is populated with content obtained by making an API call to the ReadTheDocs server.
The key drawback of this approach is that it only works when the documentation is being served by ReadTheDocs.
Also intersphinx previews only work when the target documentation is also being served by ReadTheDocs.
- [sphinx-tippy](https://github.com/sphinx-extensions2/sphinx-tippy)
This works by creating all preview content in advance, during the build process, and uses [tippy.js](https://atomiks.github.io/tippyjs/) to show the preview window on mouseover.
A drawback is that it can be difficult to make the preview content look good,
and integrate with the rest of the documentation theme.
- [sphinx-preview](https://github.com/useblocks/sphinx-preview)
This works by using Javascript to add iframe windows for previewing.
### Changes to sphinx-preview
This extension adapts the approach of `sphinx-preview`, but makes some changes including:
1. Replaces the use of JQuery with vanilla JavaScript
2. Always uses clickable icons to show the preview window, rather than mouseover hover (I feel this gives the user more control, and understanding of which links are preview-able)
3. Fixes some bugs with the scroll-to-anchor behaviour, and preview window positioning
4. Adds anchoring of the preview window to the reference, during scrolling and window resizing
5. For development purposes, also adds [JSDoc type annotations](https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html#providing-type-hints-in-js-via-jsdoc) to the JavaScript code and uses pre-commit hooks to check the formatting and type safety of the code.
[pypi-badge]: https://img.shields.io/pypi/v/sphinx-peek.svg
[pypi-link]: https://pypi.org/project/sphinx-peek
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx_peek",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "sphinx,extension,preview",
"author": null,
"author_email": "Chris Sewell <chrisj_sewell@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e1/10/39b3ba7afc7656a8f87e9dd331fe47143e2bf083f598853888d3b7db6c70/sphinx_peek-0.0.3.tar.gz",
"platform": null,
"description": "# sphinx-peek\n\n[![PyPI][pypi-badge]][pypi-link]\n\n> Sphinx extension for peeking at references\n\n**In Development!**\n\nThe extension adds a small icon next to select references,\nthat can be clicked to peek at the target of the reference.\n\n- Resizable modal window\n- Anchored to the reference during scrolling and window resizing\n- Nested reference peeking supported\n\nSee documentation at <https://sphinx-peek.readthedocs.io/>\n\n\n## Development notes\n\nYet another sphinx-extension for previewing links!\n\nAims:\n\n- As simple as possible\n- All CSS and JavaScript is bundled with the extension\n\nThere is already:\n\n- [sphinx-hoverxref](https://github.com/readthedocs/sphinx-hoverxref):\n\n This works by adding specific HTML classes to certain internal and intersphinx references,\n and then using JavaScript to show a preview window on mouseover,\n which is populated with content obtained by making an API call to the ReadTheDocs server.\n\n The key drawback of this approach is that it only works when the documentation is being served by ReadTheDocs.\n Also intersphinx previews only work when the target documentation is also being served by ReadTheDocs.\n\n- [sphinx-tippy](https://github.com/sphinx-extensions2/sphinx-tippy)\n\n This works by creating all preview content in advance, during the build process, and uses [tippy.js](https://atomiks.github.io/tippyjs/) to show the preview window on mouseover.\n\n A drawback is that it can be difficult to make the preview content look good,\n and integrate with the rest of the documentation theme.\n\n- [sphinx-preview](https://github.com/useblocks/sphinx-preview)\n\n This works by using Javascript to add iframe windows for previewing.\n\n### Changes to sphinx-preview\n\nThis extension adapts the approach of `sphinx-preview`, but makes some changes including:\n\n1. Replaces the use of JQuery with vanilla JavaScript\n2. Always uses clickable icons to show the preview window, rather than mouseover hover (I feel this gives the user more control, and understanding of which links are preview-able)\n3. Fixes some bugs with the scroll-to-anchor behaviour, and preview window positioning\n4. Adds anchoring of the preview window to the reference, during scrolling and window resizing\n5. For development purposes, also adds [JSDoc type annotations](https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html#providing-type-hints-in-js-via-jsdoc) to the JavaScript code and uses pre-commit hooks to check the formatting and type safety of the code.\n\n[pypi-badge]: https://img.shields.io/pypi/v/sphinx-peek.svg\n[pypi-link]: https://pypi.org/project/sphinx-peek\n",
"bugtrack_url": null,
"license": null,
"summary": "A sphinx extension for peeking at internal references.",
"version": "0.0.3",
"project_urls": {
"Documentation": "https://sphinx-peek.readthedocs.io/",
"Homepage": "https://github.com/sphinx-extensions2/sphinx-peek"
},
"split_keywords": [
"sphinx",
"extension",
"preview"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ec82e3a5b6a11060586ecfd91789a0fbce0dc1b35c249ffa8d0ba748c86897ee",
"md5": "a7d466212db0bed12c7c8177bd320574",
"sha256": "4227328e49052047f7404d08354627eb65dea26393839325e34b0a75fdb47c56"
},
"downloads": -1,
"filename": "sphinx_peek-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a7d466212db0bed12c7c8177bd320574",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10128,
"upload_time": "2024-01-26T01:23:22",
"upload_time_iso_8601": "2024-01-26T01:23:22.827721Z",
"url": "https://files.pythonhosted.org/packages/ec/82/e3a5b6a11060586ecfd91789a0fbce0dc1b35c249ffa8d0ba748c86897ee/sphinx_peek-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e11039b3ba7afc7656a8f87e9dd331fe47143e2bf083f598853888d3b7db6c70",
"md5": "3ae9c93478c8605a65890c542ce7879d",
"sha256": "28460d21cf09e6f39e83c153d3c5cb725aefdec51e39d6cc81a931f512066487"
},
"downloads": -1,
"filename": "sphinx_peek-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "3ae9c93478c8605a65890c542ce7879d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 40788660,
"upload_time": "2024-01-26T01:23:24",
"upload_time_iso_8601": "2024-01-26T01:23:24.716646Z",
"url": "https://files.pythonhosted.org/packages/e1/10/39b3ba7afc7656a8f87e9dd331fe47143e2bf083f598853888d3b7db6c70/sphinx_peek-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-26 01:23:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sphinx-extensions2",
"github_project": "sphinx-peek",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "sphinx_peek"
}
