For more of my work, please see my home page. For a detailed description of how this works, see this blog post
)
)
pip install sphinx-fediverseThere 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.
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::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) |
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:
Note that by using this plugin, you will be including the following in your page:
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.
In the Python stack, you will be utilizing the following:
- Sphinx
- docutils
- At least one of: Mastodon.py, Misskey.py
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.