Skip to main content

Sphinx Desktop

Makes editing of Sphinx based documentation easier on desktops.

Installs a protocol handler for sphinx:// urls.

Why?

  • Online edit links and pull requests (e.g. github) are high overhead.
  • Desktop editors are better, and closer to the build/preview tooling.

Supported Operating Systems

  • Linux

URL Format

sphinx://{project}/{release}/{page}.{md,rst}.

Quick Start

Install sphinx-desktop

pip install sphinx-desktop

Install the sphinx:// scheme handler (Linux/XDG)

sphinx-desktop install-xdg

Mapping a project

Create a configuration file for sphinx-desktop ~/.config/sphinx-desktop.toml.

Replace the values relevant for your project:

[sphinx]
  
[[sphinx.projects]]
name = "project-name"
path =  { expand = "~/path/to/project-name/documents/source" }
release = "*"

release may be defined for specific releases, otherwise it defaults to * (meaning any release). Additional projects may be added by defining extra [[sphinx.projects]] sections with the appropriate values.

Overriding the Sphinx HTML Template

To add sphinx:// links to your documentation, you must modify your templates. To do this with most themes that derive from the sphinx basic theme:

  1. Add a file named sourcelink.html to _templates in the source directory, which will override the default sourcelink.html:
{%- if show_source and has_source and sourcename %}
<div role="note" aria-label="source link">
    <h3>{{ _('This Page') }}</h3>
    <ul class="this-page-menu">
        <li><a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow">{{ _('Show Source') }}</a></li>
        <li><a href="sphinx://sphinx://{{project}}/{{release}}/{{ pagename }}{{ page_source_suffix }}" rel="nofollow">{{ _('Edit Sources') }}</a></li>
    </ul>
</div>
{%- endif %}
If you use a theme that doesn't base itself on the Sphinx `basic` theme, you'll need to modify the jinja template approriately.

Command Line and Manual Usage

Opening a project:

sphinx-desktop open sphinx://project/release/$path

Alternatively, you may use xdg-open after installing the sphinx:// scheme handler:

xdg-open sphinx://project/release/$path

Links

Documentation Source Code (Source Hut)

Metadata

Release files for sphinx-desktop 20240301

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sphinx-desktop 20240301
File Size Uploaded Provenance Actions
sphinx-desktop-20240301.tar.gz 4.6 kB Without provenance Details for sphinx-desktop-20240301.tar.gz

Release files / sphinx-desktop-20240301.tar.gz

Download URL sphinx-desktop-20240301.tar.gz
Size 4.6 kB
Tags Source
SHA-256 checksum
How to use checksums
4fb84056c935ab65fbea22fd5c69e2dc7689244e6b89bda3a500c0cda204e9ef
BLAKE2b-256 checksum
How to use checksums
e946b3e982146b7dd121513f9d582ec889e99e8ec9d496aa4e1aa34ecf78543b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.2 CPython/3.9.18

Security for sphinx-desktop 20240301

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

20240301 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page