sphinx-fediverse 0.9.1

Add fediverse comments to your Sphinx page

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)

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

Note

This feature is a work in progress

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

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

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