| Name | sphinx-desktop JSON |
| Version |
20240301
JSON |
| download |
| home_page | |
| Summary | Open sphinx:// links on your desktop. |
| upload_time | 2024-03-01 07:07:26 |
| maintainer | |
| docs_url | None |
| author | Nate Skulic, MetaCompany |
| requires_python | >=3.6 |
| license | |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Sphinx Desktop
Makes editing of [Sphinx](https://www.sphinx-doc.org/) 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
```shell
pip install sphinx-desktop
```
### Install the `sphinx://` scheme handler (Linux/XDG)
```shell
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:
```toml
[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`:
```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 %}
```
```{note}
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:
```shell
sphinx-desktop open sphinx://project/release/$path
```
Alternatively, you may use xdg-open after installing the `sphinx://` scheme handler:
```shell
xdg-open sphinx://project/release/$path
```
# Links
[Documentation](https://meta.company/go/sphinx-desktop)
[Source Code](https://sr.ht/) (Source Hut)
Raw data
{
"_id": null,
"home_page": "",
"name": "sphinx-desktop",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Nate Skulic, MetaCompany",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/e9/46/b3e982146b7dd121513f9d582ec889e99e8ec9d496aa4e1aa34ecf78543b/sphinx-desktop-20240301.tar.gz",
"platform": null,
"description": "# Sphinx Desktop\n\nMakes editing of [Sphinx](https://www.sphinx-doc.org/) based documentation easier on desktops.\n\nInstalls a protocol handler for `sphinx://` urls. \n\n## Why?\n\n- Online edit links and pull requests (e.g. github) are high overhead.\n- Desktop editors are better, and closer to the build/preview tooling.\n\n## Supported Operating Systems\n\n- Linux\n\n## URL Format\n\n`sphinx://{project}/{release}/{page}.{md,rst}`.\n\n## Quick Start\n\n### Install sphinx-desktop\n\n```shell\npip install sphinx-desktop\n```\n\n### Install the `sphinx://` scheme handler (Linux/XDG)\n\n```shell\nsphinx-desktop install-xdg\n```\n\n### Mapping a project\n\nCreate a configuration file for sphinx-desktop `~/.config/sphinx-desktop.toml`.\n\nReplace the values relevant for your project:\n\n```toml\n[sphinx]\n \n[[sphinx.projects]]\nname = \"project-name\"\npath = { expand = \"~/path/to/project-name/documents/source\" }\nrelease = \"*\"\n```\n\n`release` may be defined for specific releases, otherwise it defaults to `*` (meaning any release). \nAdditional projects may be added by defining extra `[[sphinx.projects]]` sections with the appropriate values.\n\n### Overriding the Sphinx HTML Template\n\nTo add `sphinx://` links to your documentation, you must modify your templates. To do this with most themes that derive\nfrom the sphinx basic theme:\n\n1. Add a file named `sourcelink.html` to `_templates` in the source directory, which will override the default `sourcelink.html`:\n\n```html\n{%- if show_source and has_source and sourcename %}\n<div role=\"note\" aria-label=\"source link\">\n <h3>{{ _('This Page') }}</h3>\n <ul class=\"this-page-menu\">\n <li><a href=\"{{ pathto('_sources/' + sourcename, true)|e }}\" rel=\"nofollow\">{{ _('Show Source') }}</a></li>\n <li><a href=\"sphinx://sphinx://{{project}}/{{release}}/{{ pagename }}{{ page_source_suffix }}\" rel=\"nofollow\">{{ _('Edit Sources') }}</a></li>\n </ul>\n</div>\n{%- endif %}\n```\n\n```{note}\nIf you use a theme that doesn't base itself on the Sphinx `basic` theme, you'll need to modify the jinja template approriately.\n```\n\n# Command Line and Manual Usage\n\nOpening a project:\n\n```shell\n\nsphinx-desktop open sphinx://project/release/$path\n```\n\nAlternatively, you may use xdg-open after installing the `sphinx://` scheme handler:\n\n```shell\nxdg-open sphinx://project/release/$path\n```\n\n\n# Links\n\n[Documentation](https://meta.company/go/sphinx-desktop)\n[Source Code](https://sr.ht/) (Source Hut)\n",
"bugtrack_url": null,
"license": "",
"summary": "Open sphinx:// links on your desktop.",
"version": "20240301",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e946b3e982146b7dd121513f9d582ec889e99e8ec9d496aa4e1aa34ecf78543b",
"md5": "065369d97fe06e6ff811ec0afb481d3a",
"sha256": "4fb84056c935ab65fbea22fd5c69e2dc7689244e6b89bda3a500c0cda204e9ef"
},
"downloads": -1,
"filename": "sphinx-desktop-20240301.tar.gz",
"has_sig": false,
"md5_digest": "065369d97fe06e6ff811ec0afb481d3a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 4632,
"upload_time": "2024-03-01T07:07:26",
"upload_time_iso_8601": "2024-03-01T07:07:26.049827Z",
"url": "https://files.pythonhosted.org/packages/e9/46/b3e982146b7dd121513f9d582ec889e99e8ec9d496aa4e1aa34ecf78543b/sphinx-desktop-20240301.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-01 07:07:26",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "sphinx-desktop"
}
