Metadata-Version: 2.4
Name: sphinx-notionbuilder
Version: 2025.8.27.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 :: 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: beartype>=0.21.0
Requires-Dist: docutils>=0.21
Requires-Dist: notion-client>=2.0.0
Requires-Dist: sphinx>=8.2.3
Requires-Dist: sphinx-toolbox>=4.0.0
Requires-Dist: ultimate-notion>=0.8
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.4.8; 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.17.1; 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: pyenchant==3.3.0rc1; extra == "dev"
Requires-Dist: pygments==2.19.2; extra == "dev"
Requires-Dist: pylint==3.3.8; extra == "dev"
Requires-Dist: pylint-per-file-ignores==1.4.0; extra == "dev"
Requires-Dist: pyproject-fmt==2.6.0; extra == "dev"
Requires-Dist: pyright==1.1.404; extra == "dev"
Requires-Dist: pyroma==5.0; extra == "dev"
Requires-Dist: pytest==8.4.1; extra == "dev"
Requires-Dist: pytest-cov==6.2.1; extra == "dev"
Requires-Dist: pyyaml==6.0.2; extra == "dev"
Requires-Dist: ruff==0.12.10; 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.0.20250822; extra == "dev"
Requires-Dist: vulture==2.14; extra == "dev"
Requires-Dist: yamlfix==1.17.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",
   ]

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)

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>`_.

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.

Supported features
------------------

.. |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
