sphinx-fediverse documentation
==============================
For more of my work, please see my `home page <https://oliviaappleton.com/>`__.
.. |downloads| image:: https://img.shields.io/pepy/dt/sphinx-fediverse
:alt: PyPI Total Downloads
:target: https://pepy.tech/projects/sphinx-fediverse
.. |license| image:: https://img.shields.io/pypi/l/sphinx-fediverse
:alt: PyPI License
:target: https://pypi.org/project/sphinx-fediverse
.. |status| image:: https://img.shields.io/pypi/status/sphinx-fediverse
:alt: PyPI Status
:target: https://pypi.org/project/sphinx-fediverse
.. |version| image:: https://img.shields.io/pypi/v/sphinx-fediverse
:alt: PyPI Version
:target: https://pypi.org/project/sphinx-fediverse
.. |sponsors| image:: https://img.shields.io/github/sponsors/LivInTheLookingGlass
:alt: GitHub Sponsors
:target: https://github.com/LivInTheLookingGlass/sphinx-fediverse
.. |issues| image:: https://img.shields.io/github/issues/LivInTheLookingGlass/sphinx-fediverse
:alt: Open GitHub Issues
:target: https://github.com/LivInTheLookingGlass/sphinx-fediverse/issues
.. |prs| image:: https://img.shields.io/github/issues-pr/LivInTheLookingGlass/sphinx-fediverse
:alt: Open GitHub Pull Requests
:target: https://github.com/LivInTheLookingGlass/sphinx-fediverse/pulls
| |license| |status| |version| |downloads|
| |issues| |prs| |sponsors|
.. first-cut
Quick Start Guide
~~~~~~~~~~~~~~~~~
Installation
------------
.. code:: bash
pip install sphinx-fediverse
Configuration
-------------
There are a few necessary values that you must provide:
.. table::
======================== ============================================ ===============================
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:
.. code:: python
extensions = [
# ...
'sphinx_fediverse',
]
And add the following to each page you want a comments section to appear in:
.. code:: reStructuredText
.. 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
.. code:: reStructuredText
.. 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 <https://sphinx-fediverse.oliviaappleton.com/alabaster/>`_
- `Read the Docs <https://sphinx-fediverse.oliviaappleton.com/sphinx_rtd_theme/>`_
- `shibuya <https://sphinx-fediverse.oliviaappleton.com/shibuya/>`_
- `agogo <https://sphinx-fediverse.oliviaappleton.com/agogo/>`_
- `bizstyle <https://sphinx-fediverse.oliviaappleton.com/bizstyle/>`_
- `classic <https://sphinx-fediverse.oliviaappleton.com/classic/>`_
- `haiku <https://sphinx-fediverse.oliviaappleton.com/haiku/>`_
- `nature <https://sphinx-fediverse.oliviaappleton.com/nature/>`_
- `pyramid <https://sphinx-fediverse.oliviaappleton.com/pyramid/>`_
- `scrolls <https://sphinx-fediverse.oliviaappleton.com/scrolls/>`_
- `sphinxdoc <https://sphinx-fediverse.oliviaappleton.com/sphinxdoc/>`_
- `traditional <https://sphinx-fediverse.oliviaappleton.com/traditional/>`_
Dependencies
~~~~~~~~~~~~
Note that by using this plugin, you will be including the following in your page:
- `Marked <https://marked.js.org/>`_ for rendering Markdown
- `DOMPurify <https://github.com/cure53/DOMPurify>`_ for HTML sanitization
We also use `Babel <https://babeljs.io/>`_ to ensure compatibility with most browsers. This is not included directly,
but is used to pre-process the included javascript before release.
Raw data
{
"_id": null,
"home_page": "https://sphinx-fediverse.oliviaappleton.com",
"name": "sphinx-fediverse",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "sphinx fediverse comments activitypub mastodon",
"author": "Olivia Appleton-Crocker",
"author_email": "liv@oliviaappleton.com",
"download_url": "https://files.pythonhosted.org/packages/e4/a0/b1bb6b058ffe42f45a2b9c60aebd928431a168ddf0f980bb226087ecf1d6/sphinx_fediverse-0.8.3.tar.gz",
"platform": null,
"description": "sphinx-fediverse documentation\n==============================\n\nFor more of my work, please see my `home page <https://oliviaappleton.com/>`__.\n\n.. |downloads| image:: https://img.shields.io/pepy/dt/sphinx-fediverse\n :alt: PyPI Total Downloads\n :target: https://pepy.tech/projects/sphinx-fediverse\n.. |license| image:: https://img.shields.io/pypi/l/sphinx-fediverse\n :alt: PyPI License\n :target: https://pypi.org/project/sphinx-fediverse\n.. |status| image:: https://img.shields.io/pypi/status/sphinx-fediverse\n :alt: PyPI Status\n :target: https://pypi.org/project/sphinx-fediverse\n.. |version| image:: https://img.shields.io/pypi/v/sphinx-fediverse\n :alt: PyPI Version\n :target: https://pypi.org/project/sphinx-fediverse\n.. |sponsors| image:: https://img.shields.io/github/sponsors/LivInTheLookingGlass\n :alt: GitHub Sponsors\n :target: https://github.com/LivInTheLookingGlass/sphinx-fediverse\n.. |issues| image:: https://img.shields.io/github/issues/LivInTheLookingGlass/sphinx-fediverse\n :alt: Open GitHub Issues\n :target: https://github.com/LivInTheLookingGlass/sphinx-fediverse/issues\n.. |prs| image:: https://img.shields.io/github/issues-pr/LivInTheLookingGlass/sphinx-fediverse\n :alt: Open GitHub Pull Requests\n :target: https://github.com/LivInTheLookingGlass/sphinx-fediverse/pulls\n\n| |license| |status| |version| |downloads|\n| |issues| |prs| |sponsors|\n\n.. first-cut\n\nQuick Start Guide\n~~~~~~~~~~~~~~~~~\n\nInstallation\n------------\n\n.. code:: bash\n\n pip install sphinx-fediverse\n\nConfiguration\n-------------\n\nThere are a few necessary values that you must provide:\n\n.. table::\n\n ======================== ============================================ ===============================\n Option Description Example\n ======================== ============================================ ===============================\n html_baseurl The host your documentation will be on https://www.sphinx-doc.org/\n fedi_flavor The API your server implements ``'mastodon'`` or ``'misskey'``\n fedi_username The username of the account to make posts on xkcd\n fedi_instance The host you're making comments on botsin.space\n comments_mapping_file The name of the comments map file comments_mapping.json (default)\n replace_index_with_slash True to replace ``/index.html`` with ``/`` True (default)\n enable_post_creation True to automatically post, False for manual True (default)\n raise_error_if_no_post True to raise an error if not post is made True (default)\n ======================== ============================================ ===============================\n\nWe also rely on some environment variables.\n\nFor Mastodon instances we require: ``MASTODON_CLIENT_ID``, ``MASTODON_CLIENT_SECRET``, ``MASTODON_ACCESS_TOKEN``.\n\nFor Misskey instances we require: ``MISSKEY_ACCESS_TOKEN``.\n\nEach of these must be set if you want to have automatic post creation. They are\nintentionally not included in the config file so you are incentivized to not store them publicly.\n\nUsage\n-----\n\nTo use this extension, simply add it to your ``conf.py``'s extension list:\n\n.. code:: python\n\n extensions = [\n # ...\n 'sphinx_fediverse',\n ]\n\nAnd add the following to each page you want a comments section to appear in:\n\n.. code:: reStructuredText\n\n .. fedi-comments::\n\nThis will enable a comments section for each post. Upon build, a Mastodon post will be generated for each new page.\nThis will be stored in the same directory as your config file. The ID of each page's post will be embedded into the\noutput documents, and used to retrieve comments.\n\n.. warning::\n\n sphinx-fediverse only works in pure HTML builds. If you produce other builds, you *must* wrap it in an \"only\" directive\n\n .. code:: reStructuredText\n\n .. only:: html\n\n .. fedi-comments::\n\nSupported Themes\n~~~~~~~~~~~~~~~~\n\nBecause this project includes styling, we need to ensure compatibility with each theme individually. To view it in any\nofficially supported theme, click one of the links below:\n\n- `alabaster <https://sphinx-fediverse.oliviaappleton.com/alabaster/>`_\n- `Read the Docs <https://sphinx-fediverse.oliviaappleton.com/sphinx_rtd_theme/>`_\n- `shibuya <https://sphinx-fediverse.oliviaappleton.com/shibuya/>`_\n- `agogo <https://sphinx-fediverse.oliviaappleton.com/agogo/>`_\n- `bizstyle <https://sphinx-fediverse.oliviaappleton.com/bizstyle/>`_\n- `classic <https://sphinx-fediverse.oliviaappleton.com/classic/>`_\n- `haiku <https://sphinx-fediverse.oliviaappleton.com/haiku/>`_\n- `nature <https://sphinx-fediverse.oliviaappleton.com/nature/>`_\n- `pyramid <https://sphinx-fediverse.oliviaappleton.com/pyramid/>`_\n- `scrolls <https://sphinx-fediverse.oliviaappleton.com/scrolls/>`_\n- `sphinxdoc <https://sphinx-fediverse.oliviaappleton.com/sphinxdoc/>`_\n- `traditional <https://sphinx-fediverse.oliviaappleton.com/traditional/>`_\n\nDependencies\n~~~~~~~~~~~~\n\nNote that by using this plugin, you will be including the following in your page:\n\n- `Marked <https://marked.js.org/>`_ for rendering Markdown\n- `DOMPurify <https://github.com/cure53/DOMPurify>`_ for HTML sanitization\n\nWe also use `Babel <https://babeljs.io/>`_ to ensure compatibility with most browsers. This is not included directly,\nbut is used to pre-process the included javascript before release.\n",
"bugtrack_url": null,
"license": null,
"summary": "Add fediverse comments to your sphinx page",
"version": "0.8.3",
"project_urls": {
"Documentation": "https://sphinx-fediverse.oliviaappleton.com",
"Homepage": "https://sphinx-fediverse.oliviaappleton.com",
"Issue Tracker": "https://github.com/LivInTheLookingGlass/sphinx-fediverse/issues",
"Source Code": "https://github.com/LivInTheLookingGlass/sphinx-fediverse"
},
"split_keywords": [
"sphinx",
"fediverse",
"comments",
"activitypub",
"mastodon"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "44cd25e6df9c06fc65131d0b54762904314fe4fb56112e2f8014ad67c8aed5e7",
"md5": "5d02ff5ba9317df7d128c8db434ffbf6",
"sha256": "3ec84379366f733f1f507e3a3bbbf112770b584bb4206cddb4314a726043997f"
},
"downloads": -1,
"filename": "sphinx_fediverse-0.8.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5d02ff5ba9317df7d128c8db434ffbf6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 49561,
"upload_time": "2025-03-19T06:09:38",
"upload_time_iso_8601": "2025-03-19T06:09:38.195829Z",
"url": "https://files.pythonhosted.org/packages/44/cd/25e6df9c06fc65131d0b54762904314fe4fb56112e2f8014ad67c8aed5e7/sphinx_fediverse-0.8.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e4a0b1bb6b058ffe42f45a2b9c60aebd928431a168ddf0f980bb226087ecf1d6",
"md5": "e9b1a4a929a08112fda66b470454da1e",
"sha256": "931e9a42087c27e6f25154d3a55ee7a914e67c647ba2f7196077afa40395f683"
},
"downloads": -1,
"filename": "sphinx_fediverse-0.8.3.tar.gz",
"has_sig": false,
"md5_digest": "e9b1a4a929a08112fda66b470454da1e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 49799,
"upload_time": "2025-03-19T06:09:39",
"upload_time_iso_8601": "2025-03-19T06:09:39.404205Z",
"url": "https://files.pythonhosted.org/packages/e4/a0/b1bb6b058ffe42f45a2b9c60aebd928431a168ddf0f980bb226087ecf1d6/sphinx_fediverse-0.8.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-19 06:09:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LivInTheLookingGlass",
"github_project": "sphinx-fediverse",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "doctools",
"specs": []
},
{
"name": "mastodon.py",
"specs": []
},
{
"name": "misskey.py",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "sphinx",
"specs": []
}
],
"lcname": "sphinx-fediverse"
}
JSON
