Metadata-Version: 2.4
Name: sphinx-notionbuilder
Version: 2025.10.2
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-immaterial>=0.13.6
Requires-Dist: sphinx-simplepdf>=1.6.0
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.3
Provides-Extra: dev
Requires-Dist: actionlint-py==1.7.7.23; extra == "dev"
Requires-Dist: anstrip==0.2.2; 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.9.25; 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.7.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.3; extra == "dev"
Requires-Dist: ruff==0.13.2; 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: sphinxcontrib-text-styles==0.2.0; 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"
Provides-Extra: sample
Requires-Dist: sphinxcontrib-text-styles==0.2.0; extra == "sample"

|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",
   ]

For TODO list support, also add the `sphinx-immaterial <https://github.com/jbms/sphinx-immaterial>`_ task lists extension:

.. code-block:: python

   """Configuration for Sphinx."""

   extensions = [
       "sphinx_immaterial.task_lists",
       "sphinx_notion",
   ]

PDF support is included by default with the sphinx-notionbuilder extension.

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

The following syntax is supported:

- Headers
- Bulleted lists
- TODO lists (with checkboxes)
- Code blocks
- Table of contents
- Block quotes
- All standard admonitions (note, warning, tip, attention, caution, danger, error, hint, important)
- 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)
- PDFs (with URLs or local paths)
- Tables
- Strikethrough text
- Colored 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.

Using PDFs
----------

PDF files can be embedded using the ``pdf-include`` directive. Both remote URLs and local file paths are supported.

.. code-block:: rst

   .. pdf-include:: https://www.example.com/document.pdf

   .. pdf-include:: _static/local-document.pdf

The PDF will be rendered as an embedded PDF viewer in the generated Notion page.

Using Colored Text
------------------

Colored text can be added using the `sphinxcontrib-text-styles <https://sphinxcontrib-text-styles.readthedocs.io/>`_ extension. First, install the extension:

.. code-block:: console

   $ pip install sphinxcontrib-text-styles

Then add it to your ``conf.py``:

.. code-block:: python

   """Configuration for Sphinx."""

   extensions = [
       "sphinxcontrib_text_styles",
       "sphinx_notion",
   ]

You can then use colored text in your reStructuredText documents:

.. code-block:: rst

   This is :text-red:`red text`, :text-blue:`blue text`, and :text-green:`green text`.

The following colors are supported: red, blue, green, yellow, orange, purple, pink, brown, and gray.

Using TODO Lists
----------------

TODO lists with checkboxes can be created using the ``sphinx-immaterial.task_lists`` extension. Both bulleted and numbered lists support checkboxes:

.. code-block:: rst

   .. task-list::

       1. [x] Completed task
       2. [ ] Incomplete task
       3. [ ] Another task

   * [x] Bulleted completed task
   * [ ] Bulleted incomplete task

The checkboxes will be rendered as interactive TODO items in the generated Notion page, with completed tasks showing as checked and incomplete tasks as unchecked.

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:

- ``--file``: Path to the JSON file generated by the Notion builder
- ``--parent-id``: The ID of the parent page or database in Notion (must be shared with your integration)
- ``--parent-type``: "page" or "database"
- ``--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
