This package provides several Sphinx extensions that are used in the LXD documentation, but can also be useful for other documentation sets.
Install the package with the following command:
pip install lxd-sphinx-extensions
The package provides several Sphinx extensions that can be used in combination or separately.
This extension allows adding related links (Discourse links and general related links) on a per-page basis. The links are specified as metadata in the RST files. They can be displayed at any place in the output by adapting the Sphinx template.
Add related-links
to your extensions list in conf.py
to enable the extension:
extensions = [
(...),
 "related-links"
]
If you want to add Discourse links, you must also configure the prefix for your Discourse instance in the html_context
variable:
html_context = {
(...),
"discourse_prefix": "https://discuss.linuxcontainers.org/t/"
}
The extension provides two functions that can be used in your template:
discourse_links(meta.discourse)
: Returns an unordered list (<ul>
) of Discourse links.related_links(meta.relatedlinks)
: Returns an unordered list (<ul>
) of related links.
For example, to include the related links in your template based on the Furo theme, place code similar to the following in your _templates/page.html
file:
{% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %}
{% set furo_hide_toc_orig = furo_hide_toc %}
{% set furo_hide_toc=false %}
{% endif %}
{% block right_sidebar %}
<div class="toc-sticky toc-scroll">
{% if not furo_hide_toc_orig %}
<div class="toc-title-container">
<span class="toc-title">
{{ _("Contents") }}
</span>
</div>
<div class="toc-tree-container">
<div class="toc-tree">
{{ toc }}
</div>
</div>
{% endif %}
{% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %}
<div class="relatedlinks-title-container">
<span class="relatedlinks-title">
Related links
</span>
</div>
<div class="relatedlinks-container">
<div class="relatedlinks">
{% if meta.discourse and discourse_prefix %}
{{ discourse_links(meta.discourse) }}
{% endif %}
{% if meta.relatedlinks %}
{{ related_links(meta.relatedlinks) }}
{% endif %}
</div>
</div>
{% endif %}
</div>
{% endblock right_sidebar %}
See the Sphinx documentation for information on how templating works in Sphinx.
The extension comes with a CSS file that is suitable for the template example as given above. You can override these styles or define your own, depending on the theme and template that you use.
Specify your Discourse links and related links in the metadata at the top of the page.
For Discourse links, specify only the topic IDs (in a comma-separated list).
For related links, specify the full URLs (in a comma-separated list).
The link text is extracted automatically or can be specified in Markdown syntax.
Note that spaces are ignored; if you need spaces in the title, replace them with  
.
If Sphinx complains about the metadata value because it starts with "[", enclose the full value in double quotes.
The following example uses MyST syntax for the metadata:
---
discourse: 1234,56789
relatedlinks: https://www.example.com, [Link text](https://www.example.com)
---
This extension adds a :youtube:
directive that you can use to add links to YouTube videos at any place in an input file.
Add youtube-links
to your extensions list in conf.py
to enable the extension:
extensions = [
(...),
 "youtube-links"
]
The extension comes with a CSS file that implements the style for the p.youtube_link
element.
You can override the style in your own style sheet.
To add a YouTube link to your page, use the :youtube:
directive and specify the link to the video.
For example, in MyST syntax:
```{youtube} https://www.youtube.com/watch?v=4iNpiL-lrXU
```
This extension adds custom roles that can be used in rST.
Currently implemented:
spellexception
- Includes the provided text in<spellexception></spellexception>
, which makes it possible to exclude it from a spell checker.