sphinx-fediverse documentation

For more of my work, please see my home page. For a detailed description of how this works, see this blog post

Quick Start Guide

Installation

pip install sphinx-fediverse

Configuration

There are a several values that you may provide:

Option	Description	Example
html_baseurl	The host your documentation will be on	https://www.sphinx-doc.org/
fedi_flavor	The API your server implements	'mastodon' or 'misskey'
fedi_username	The username of the account to make posts on	xkcd
fedi_instance	The host you’re making comments on	botsin.space
comments_mapping_file	The name of the comments map file	comments_mapping.json (default)
replace_index_with_slash	True to replace /index.html with /	True (default)
enable_post_creation	True to automatically post, False for manual	True (default)
raise_error_if_no_post	True to raise an error if not post is made	True (default)
comment_fetch_depth	The number of recursive fetches to make	5 (default)
comment_section_level	The header level of the comments section	2 (default)
comment_section_title	The title of the comments section	Comments (default)
allow_custom_emoji	Whether to replace emoji shortcodes with images	True (default)
allow_sensitive_emoji	Whether to parse sensitive custom emoji	False (default)
allow_media_attachments	Whether to include attached images	True (default)
allow_avatars	Whether to include user avatar images	True (default)
delay_comment_load	Delay loading comments until they are in view	True (default)
default_reaction_emoji	The default reaction to use when unsupported	❤ (default)
fedi_retry_delay	The amount of time to wait on rate-limit error	100 (default, in ms)

We also rely on environment variables for authentication.

For Mastodon instances we require: MASTODON_CLIENT_ID, MASTODON_CLIENT_SECRET, MASTODON_ACCESS_TOKEN.

For Misskey instances we require: MISSKEY_ACCESS_TOKEN.

Each of these must be set if you want to have automatic post creation. They are intentionally not included in the config file so you are incentivized to not store them publicly.

Usage

To use this extension, simply add it to your conf.py’s extension list:

extensions = [
   # ...
   'sphinx_fediverse',
]

And add the following to each page you want a comments section to appear in:

.. fedi-comments::

This will enable a comments section for each post. Upon build, a Mastodon post will be generated for each new page. This will be stored in the same directory as your config file. The ID of each page’s post will be embedded into the output documents, and used to retrieve comments.

Warning

sphinx-fediverse only works in pure HTML builds. If you produce other builds, you must wrap it in an “only” directive

.. only:: html

   .. fedi-comments::

Directive Options

In addition to the above configuration values, you can modify most of them on a per-directive basis!

Option	Description	Example(s)
fedi_flavor	(See Above)	(See Above)
fedi_username	(See Above)	(See Above)
fedi_instance	(See Above)	(See Above)
comments_mapping_file	(See Above)	(See Above)
replace_index_with_slash	(See Above)	(See Above)
enable_post_creation	(See Above)	(See Above)
raise_error_if_no_post	(See Above)	(See Above)
fetch_depth	(See comment_fetch_depth Above)	(See Above)
section_level	(See comment_section_level Above)	(See Above)
section_title	(See comment_section_title Above)	(See Above)
post_id	A hardcoded post ID to use for comments	None (default), 114032235423688612
allow_custom_emoji	(See Above)	(See Above)
allow_sensitive_emoji	(See Above)	(See Above)
allow_media_attachments	(See Above)	(See Above)
allow_avatars	(See Above)	(See Above)
delay_comment_load	(See Above)	(See Above)
default_reaction_emoji	(See Above)	(See Above)
fedi_retry_delay	(See Above)	(See Above)

Supported Themes

Because this project includes styling, we need to ensure compatibility with each theme individually. To view it in any officially supported theme, click one of the links below:

• alabaster

• Read the Docs

• shibuya

• agogo

• bizstyle

• classic

• nature

• pyramid

• scrolls

• sphinxdoc

• traditional

Dependencies

JavaScript

Note that by using this plugin, you will be including the following in your page:

• Marked for rendering Markdown (Misskey only)

• DOMPurify for HTML sanitization

We also use Babel to ensure compatibility with most browsers. This is not included directly, but is used to pre-process the included javascript before release.

Python

In the Python stack, you will be utilizing the following:

• Sphinx

• docutils

• At least one of: Mastodon.py, Misskey.py

Privacy Policy

When rendering federated comments, this extension may load images, custom emoji, or avatars directly from third-party Fediverse instances (e.g. mastodon.social, misskey.io). As with any embedded resource, your visitors’ browsers may send requests to those instances, which can include their IP address and user agent.

This extension performs no tracking, remote logging, or cookie storage. All data is fetched live in the browser at page load and is never persisted or sent to third parties by the extension itself.

If you are concerned about data exposure to remote domains, you may disable media attachments, custom emoji, or avatars using directive options such as allow_media_attachments, allow_custom_emoji, allow_avatars. Any help in ensuring full GDPR (and similar) compliance would be greatly appreciated.

Comments ,