sphinx-fediverse 0.8.2

Add fediverse comments to your sphinx page

For more of my work, please see my home page.

Quick Start Guide

Installation

pip install sphinx-fediverse

Configuration

There are a few necessary values that you must 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)

We also rely on some environment variables.

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::

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

• haiku

• nature

• pyramid

• scrolls

• sphinxdoc

• traditional

Dependencies

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

• Marked for rendering Markdown

• 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.