Open sphinx:// links on your desktop.
Project description
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:
- Add a file named
sourcelink.html
to_templates
in the source directory, which will override the defaultsourcelink.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)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.