Metadata-Version: 2.4
Name: sphinx-notionbuilder
Version: 2025.9.25.4
Summary: Sphinx extension to build Notion pages.
Author-email: Adam Dangoor <adamdangoor@gmail.com>
License-Expression: MIT
Project-URL: Source, https://github.com/adamtheturtle/sphinx-notionbuilder
Keywords: notion,sphinx
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/x-rst
Requires-Dist: atsphinx-audioplayer>=0.1.0
Requires-Dist: beartype>=0.21.0
Requires-Dist: click>=8.0.0
Requires-Dist: docutils>=0.21
Requires-Dist: sphinx>=8.2.3
Requires-Dist: sphinx-toolbox>=4.0.0
Requires-Dist: sphinxcontrib-video>=0.4.0
Requires-Dist: sphinxnotes-strike>=1.3
Requires-Dist: ultimate-notion>=0.9.2
Provides-Extra: dev
Requires-Dist: actionlint-py==1.7.7.23; extra == "dev"
Requires-Dist: check-manifest==0.50; extra == "dev"
Requires-Dist: deptry==0.23.1; extra == "dev"
Requires-Dist: doc8==2.0.0; extra == "dev"
Requires-Dist: doccmd==2025.9.19; extra == "dev"
Requires-Dist: docformatter==1.7.7; extra == "dev"
Requires-Dist: freezegun==1.5.5; extra == "dev"
Requires-Dist: furo==2025.7.19; extra == "dev"
Requires-Dist: interrogate==1.7.0; extra == "dev"
Requires-Dist: mypy[faster-cache]==1.18.2; extra == "dev"
Requires-Dist: mypy-strict-kwargs==2025.4.3; extra == "dev"
Requires-Dist: pre-commit==4.3.0; extra == "dev"
Requires-Dist: pydocstyle==6.3; extra == "dev"
Requires-Dist: pygments==2.19.2; extra == "dev"
Requires-Dist: pylint[spelling]==3.3.8; extra == "dev"
Requires-Dist: pylint-per-file-ignores==2.0.3; extra == "dev"
Requires-Dist: pyproject-fmt==2.6.0; extra == "dev"
Requires-Dist: pyright==1.1.405; extra == "dev"
Requires-Dist: pyroma==5.0; extra == "dev"
Requires-Dist: pytest==8.4.2; extra == "dev"
Requires-Dist: pytest-cov==7.0.0; extra == "dev"
Requires-Dist: pyyaml==6.0.2; extra == "dev"
Requires-Dist: ruff==0.13.1; extra == "dev"
Requires-Dist: shellcheck-py==0.11.0.1; extra == "dev"
Requires-Dist: shfmt-py==3.12.0.2; extra == "dev"
Requires-Dist: sphinx-lint==1.0.0; extra == "dev"
Requires-Dist: sphinx-pyproject==0.3.0; extra == "dev"
Requires-Dist: sphinx-substitution-extensions==2025.6.6; extra == "dev"
Requires-Dist: sphinxcontrib-spelling==8.0.1; extra == "dev"
Requires-Dist: types-docutils==0.22.2.20250924; extra == "dev"
Requires-Dist: vulture==2.14; extra == "dev"
Requires-Dist: yamlfix==1.18.0; extra == "dev"
Provides-Extra: release
Requires-Dist: check-wheel-contents==0.6.3; extra == "release"

|Build Status| |codecov| |PyPI|

Notion Builder for Sphinx
=========================

Extension for Sphinx which enables publishing documentation to Notion.

.. contents::

Installation
------------

``sphinx-notionbuilder`` is compatible with Python |minimum-python-version|\+.

.. code-block:: console

   $ pip install sphinx-notionbuilder

Add the following to ``conf.py`` to enable the extension:

.. code-block:: python

   """Configuration for Sphinx."""

   extensions = ["sphinx_notion"]

For collapsible sections (toggle blocks), also add the sphinx-toolbox collapse extension:

.. code-block:: python

   """Configuration for Sphinx."""

   extensions = [
       "sphinx_notion",
       "sphinx_toolbox.collapse",
   ]

For video support, also add the sphinxcontrib-video extension:

.. code-block:: python

   """Configuration for Sphinx."""

   extensions = [
       "sphinxcontrib.video",  # Must be before sphinx_notion
       "sphinx_notion",
   ]

For strikethrough text support, also add the `sphinxnotes-strike <https://github.com/sphinx-toolbox/sphinxnotes-strike>`_ extension:

.. code-block:: python

   """Configuration for Sphinx."""

   extensions = [
       "sphinxnotes.strike",  # Must be before sphinx_notion
       "sphinx_notion",
   ]

For audio support, also add the `atsphinx-audioplayer <https://github.com/atsphinx/atsphinx-audioplayer>`_ extension:

.. code-block:: python

   """Configuration for Sphinx."""

   extensions = [
       "atsphinx.audioplayer",
       "sphinx_notion",
   ]

Supported markup
----------------

The following syntax is supported:

- Headers
- Bulleted lists
- Code blocks
- Table of contents
- Block quotes
- Note, warning, and tip admonitions
- Collapsible sections (using sphinx-toolbox collapse directive)
- Images (with URLs or local paths)
- Videos (with URLs or local paths)
- Audio (with URLs or local paths)
- Tables
- Strikethrough text

See a `sample document source <https://raw.githubusercontent.com/adamtheturtle/sphinx-notionbuilder/refs/heads/main/sample/index.rst>`_ and the `published Notion page <https://www.notion.so/Sphinx-Notionbuilder-Sample-2579ce7b60a48142a556d816c657eb55>`_.

Using Audio
-----------

Audio files can be embedded using the ``audio`` directive. Both remote URLs and local file paths are supported:

.. code-block:: rst

   .. audio:: https://www.example.com/audio.mp3

   .. audio:: _static/local-audio.mp3

The audio will be rendered as an audio player in the generated Notion page.

Uploading Documentation to Notion
----------------------------------

After building your documentation with the Notion builder, you can upload it to Notion using the included command-line tool.

Prerequisites
~~~~~~~~~~~~~

1. Create a Notion integration at https://www.notion.so/my-integrations
2. Get your integration token and set it as an environment variable:

.. code-block:: console

   $ export NOTION_TOKEN="your_integration_token_here"

Usage
~~~~~

.. code-block:: console

   $ notion-upload -f path/to/output.json -p parent_page_id -t "Page Title"

Arguments:

- ``-f, --file``: Path to the JSON file generated by the Notion builder
- ``-p, --parent-page-id``: The ID of the parent page in Notion (must be shared with your integration)
- ``-t, --title``: Title for the new page in Notion

The command will create a new page if one with the given title doesn't exist, or update the existing page if one with the given title already exists.

.. |Build Status| image:: https://github.com/adamtheturtle/sphinx-notionbuilder/actions/workflows/ci.yml/badge.svg?branch=main
   :target: https://github.com/adamtheturtle/sphinx-notionbuilder/actions
.. |codecov| image:: https://codecov.io/gh/adamtheturtle/sphinx-notionbuilder/branch/main/graph/badge.svg
   :target: https://codecov.io/gh/adamtheturtle/sphinx-notionbuilder
.. |PyPI| image:: https://badge.fury.io/py/Sphinx-Notion-Builder.svg
   :target: https://badge.fury.io/py/Sphinx-Notion-Builder
.. |minimum-python-version| replace:: 3.11
