nbsync 0.1.3__tar.gz → 0.2.0__tar.gz

{nbsync-0.1.3 → nbsync-0.2.0}/.github/workflows/docs.yaml

@@ -24,6 +24,6 @@ jobs:
       - name: Install uv
         run: pip install uv
       - name: Install the project
-        run: uv sync
+        run: uv sync --group docs
       - name: Deploy documentation
         run: uv run mkdocs gh-deploy --force

{nbsync-0.1.3 → nbsync-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: nbsync
-Version: 0.1.3
-Summary: MkDocs plugin treating Jupyter notebooks, Python scripts and Markdown files as first-class citizens for documentation with dynamic execution and real-time synchronization
+Version: 0.2.0
+Summary: A core library to synchronize Jupyter notebooks and Markdown documents, enabling seamless integration and dynamic content execution
 Project-URL: Documentation, https://daizutabi.github.io/nbsync/
 Project-URL: Source, https://github.com/daizutabi/nbsync
 Project-URL: Issues, https://github.com/daizutabi/nbsync/issues
@@ -28,7 +28,7 @@ License: MIT License
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
 License-File: LICENSE
-Keywords: documentation,dynamic-execution,jupyter,markdown,mkdocs,notebook,python,real-time-sync,visualization
+Keywords: documentation,dynamic-execution,jupyter,markdown,notebook,python,real-time-sync,visualization
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.10
@@ -39,8 +39,7 @@ Classifier: Topic :: Documentation
 Classifier: Topic :: Software Development :: Documentation
 Classifier: Topic :: Text Processing :: Markup :: Markdown
 Requires-Python: >=3.10
-Requires-Dist: mkdocs>=1.6
-Requires-Dist: nbstore>=0.4.7
+Requires-Dist: nbstore>=0.4.11
 Description-Content-Type: text/markdown
 
 # nbsync
@@ -50,11 +49,9 @@ Description-Content-Type: text/markdown
 [![Build Status][GHAction-image]][GHAction-link]
 [![Coverage Status][codecov-image]][codecov-link]
 
-<strong>Connect Jupyter notebooks to your MkDocs documentation</strong>
+<strong>Connect Jupyter notebooks and Markdown documents</strong>
 
-nbsync is a MkDocs plugin that seamlessly embeds Jupyter notebook
-visualizations in your documentation, solving the disconnect between
-code development and documentation.
+nbsync is a core library that seamlessly bridges Jupyter notebooks and Markdown documents, enabling dynamic content synchronization and execution.
 
 ## Why Use nbsync?
 
@@ -68,7 +65,7 @@ Data scientists, researchers, and technical writers face a common dilemma:
 
 ### Our Solution
 
-This plugin creates a live bridge between your notebooks and documentation by:
+nbsync creates a live bridge between your notebooks and markdown documents by:
 
 - **Keeping environments separate** - work in the tool best suited for each task
 - **Maintaining connections** - reference specific figures from notebooks
@@ -86,7 +83,7 @@ This plugin creates a live bridge between your notebooks and documentation by:
 
 - **Automatic Updates**:
   When you modify your notebooks, your documentation updates
-  automatically in MkDocs serve mode.
+  automatically.
 
 - **Clean Source Documents**:
   Your markdown remains readable and focused on content, without
@@ -104,14 +101,27 @@ This plugin creates a live bridge between your notebooks and documentation by:
 pip install nbsync
 ```
 
-### 2. Configuration
+### 2. Basic Usage
 
-Add to your `mkdocs.yml`:
+```python
+from nbsync.sync import Synchronizer
+from nbstore import Store
+
+# Initialize with a notebook store
+store = Store("path/to/notebooks")
+sync = Synchronizer(store)
+
+# Process markdown with notebook references
+markdown_text = """
+# My Document
+
+![Chart description](my-notebook.ipynb){#my-figure}
+"""
 
-```yaml
-plugins:
-  - nbsync:
-      src_dir: ../notebooks
+# Convert markdown with notebook references to final output
+for element in sync.convert(markdown_text):
+    # Process each element (string or Cell objects)
+    print(element)
 ```
 
 ### 3. Mark Figures in Your Notebook
@@ -140,14 +150,14 @@ Creating documentation and developing visualizations involve different
 workflows and timeframes. When building visualizations in Jupyter notebooks,
 you need rapid cycles of execution, verification, and modification.
 
-This plugin is designed specifically to address these separation of
+nbsync is designed specifically to address these separation of
 concerns, allowing you to:
 
 - **Focus on code** in notebooks without documentation distractions
 - **Focus on narrative** in markdown without code interruptions
 - **Maintain powerful connections** between both environments
 
-Each environment is optimized for its purpose, while the plugin
+Each environment is optimized for its purpose, while nbsync
 handles the integration automatically.
 
 ## Contributing

{nbsync-0.1.3 → nbsync-0.2.0}/README.md

@@ -5,11 +5,9 @@
 [![Build Status][GHAction-image]][GHAction-link]
 [![Coverage Status][codecov-image]][codecov-link]
 
-<strong>Connect Jupyter notebooks to your MkDocs documentation</strong>
+<strong>Connect Jupyter notebooks and Markdown documents</strong>
 
-nbsync is a MkDocs plugin that seamlessly embeds Jupyter notebook
-visualizations in your documentation, solving the disconnect between
-code development and documentation.
+nbsync is a core library that seamlessly bridges Jupyter notebooks and Markdown documents, enabling dynamic content synchronization and execution.
 
 ## Why Use nbsync?
 
@@ -23,7 +21,7 @@ Data scientists, researchers, and technical writers face a common dilemma:
 
 ### Our Solution
 
-This plugin creates a live bridge between your notebooks and documentation by:
+nbsync creates a live bridge between your notebooks and markdown documents by:
 
 - **Keeping environments separate** - work in the tool best suited for each task
 - **Maintaining connections** - reference specific figures from notebooks
@@ -41,7 +39,7 @@ This plugin creates a live bridge between your notebooks and documentation by:
 
 - **Automatic Updates**:
   When you modify your notebooks, your documentation updates
-  automatically in MkDocs serve mode.
+  automatically.
 
 - **Clean Source Documents**:
   Your markdown remains readable and focused on content, without
@@ -59,14 +57,27 @@ This plugin creates a live bridge between your notebooks and documentation by:
 pip install nbsync
 ```
 
-### 2. Configuration
+### 2. Basic Usage
 
-Add to your `mkdocs.yml`:
+```python
+from nbsync.sync import Synchronizer
+from nbstore import Store
+
+# Initialize with a notebook store
+store = Store("path/to/notebooks")
+sync = Synchronizer(store)
+
+# Process markdown with notebook references
+markdown_text = """
+# My Document
+
+![Chart description](my-notebook.ipynb){#my-figure}
+"""
 
-```yaml
-plugins:
-  - nbsync:
-      src_dir: ../notebooks
+# Convert markdown with notebook references to final output
+for element in sync.convert(markdown_text):
+    # Process each element (string or Cell objects)
+    print(element)
 ```
 
 ### 3. Mark Figures in Your Notebook
@@ -95,14 +106,14 @@ Creating documentation and developing visualizations involve different
 workflows and timeframes. When building visualizations in Jupyter notebooks,
 you need rapid cycles of execution, verification, and modification.
 
-This plugin is designed specifically to address these separation of
+nbsync is designed specifically to address these separation of
 concerns, allowing you to:
 
 - **Focus on code** in notebooks without documentation distractions
 - **Focus on narrative** in markdown without code interruptions
 - **Maintain powerful connections** between both environments
 
-Each environment is optimized for its purpose, while the plugin
+Each environment is optimized for its purpose, while nbsync
 handles the integration automatically.
 
 ## Contributing

nbsync-0.2.0/docs/index.md

@@ -0,0 +1 @@
+# nbsync

{nbsync-0.1.3 → nbsync-0.2.0}/mkdocs.yaml

@@ -41,10 +41,8 @@ theme:
     - search.suggest
 plugins:
   - search
-  - nbsync:
-      src_dir:
-        - ../notebooks
-        - ../scripts
+  - mkapi:
+      debug: true
 markdown_extensions:
   - admonition
   - pymdownx.emoji:
@@ -60,7 +58,4 @@ markdown_extensions:
       alternate_style: true
 nav:
   - Home: index.md
-  - Getting Started:
-      - getting-started/installation.md
-      - getting-started/configuration.md
-      - getting-started/first-steps.md
+  - API: $api/nbsync.***

{nbsync-0.1.3 → nbsync-0.2.0}/pyproject.toml

@@ -4,15 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nbsync"
-version = "0.1.3"
-description = "MkDocs plugin treating Jupyter notebooks, Python scripts and Markdown files as first-class citizens for documentation with dynamic execution and real-time synchronization"
+version = "0.2.0"
+description = "A core library to synchronize Jupyter notebooks and Markdown documents, enabling seamless integration and dynamic content execution"
 readme = "README.md"
 license = { file = "LICENSE" }
 authors = [{ name = "daizutabi", email = "daizutabi@gmail.com" }]
 keywords = [
   "jupyter",
   "notebook",
-  "mkdocs",
   "documentation",
   "markdown",
   "python",
@@ -32,31 +31,23 @@ classifiers = [
   "Topic :: Text Processing :: Markup :: Markdown",
 ]
 requires-python = ">=3.10"
-dependencies = ["mkdocs>=1.6", "nbstore>=0.4.7"]
+dependencies = ["nbstore>=0.4.11"]
 
 [project.urls]
 Documentation = "https://daizutabi.github.io/nbsync/"
 Source = "https://github.com/daizutabi/nbsync"
 Issues = "https://github.com/daizutabi/nbsync/issues"
 
-[project.entry-points."mkdocs.plugins"]
-nbsync = "nbsync.plugin:Plugin"
-
 [dependency-groups]
 dev = [
   "ipykernel>=6.29.5",
   "matplotlib>=3.10.1",
-  "mkdocs-material>=9.6.11",
   "nbconvert>=7.16.6",
-  "pandas>=2.2",
-  "polars>=1.26",
-  "pytest-clarity>=1.0.1",
   "pytest-cov>=6.1.0",
   "pytest-randomly>=3.16.0",
-  "pytest-xdist>=3.6.1",
   "ruff>=0.11.4",
-  "seaborn>=0.13.2",
 ]
+docs = ["mkapi", "mkdocs-material"]
 
 [tool.pytest.ini_options]
 testpaths = ["src", "tests"]
@@ -81,11 +72,4 @@ unfixable = ["F401"]
 ignore = ["ANN401", "ARG001", "ARG002", "C901", "D", "PLR0911", "S105"]
 
 [tool.ruff.lint.per-file-ignores]
-"**/tests/*" = ["ANN", "ARG", "D", "FBT", "PLR", "RUF", "S", "PGH003"]
-"**/{notebooks,scripts}/*" = ["ANN", "ERA001", "NPY", "T201"]
-
-[tool.pyright]
-include = ["src", "tests"]
-strictDictionaryInference = true
-strictListInference = true
-strictSetInference = true
+"**/tests/*" = ["ANN", "ARG", "D", "FBT", "PGH003", "PLR", "RUF", "S", "SLF"]

{nbsync-0.1.3 → nbsync-0.2.0}/src/nbsync/cell.py

@@ -5,10 +5,9 @@ import uuid
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
+from nbsync import logger
 from nbsync.markdown import is_truelike
 
-from .logger import logger
-
 if TYPE_CHECKING:
     from nbstore.markdown import Image
 

nbsync-0.2.0/src/nbsync/logger.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import logging
+from logging import Logger
+from typing import Any
+
+_logger = logging.getLogger("nbsync")
+
+
+def configure(logger: Logger | None = None) -> Logger:
+    global _logger  # noqa: PLW0603
+
+    if logger:
+        _logger = logger
+
+    return _logger
+
+
+def debug(msg: str, *args: Any, **kwargs: Any) -> None:
+    _logger.debug(msg, *args, **kwargs)
+
+
+def info(msg: str, *args: Any, **kwargs: Any) -> None:
+    _logger.info(msg, *args, **kwargs)
+
+
+def warning(msg: str, *args: Any, **kwargs: Any) -> None:
+    _logger.warning(msg, *args, **kwargs)
+
+
+def error(msg: str, *args: Any, **kwargs: Any) -> None:
+    _logger.error(msg, *args, **kwargs)

{nbsync-0.1.3 → nbsync-0.2.0}/src/nbsync/sync.py

@@ -10,12 +10,11 @@ from nbstore.markdown import CodeBlock, Image
 from nbstore.notebook import get_language, get_mime_content, get_source
 
 import nbsync.markdown
+from nbsync import logger
 from nbsync.cell import Cell
 from nbsync.markdown import is_truelike
 from nbsync.notebook import Notebook
 
-from .logger import logger
-
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
@@ -35,7 +34,7 @@ class Synchronizer:
             yield elem
 
             if isinstance(elem, Image | CodeBlock):
-                update_notebooks(notebooks, elem, self.store)
+                update_notebooks(elem, notebooks, self.store)
 
         for url, notebook in notebooks.items():
             if url not in self.notebooks or not self.notebooks[url].equals(notebook):
@@ -58,17 +57,13 @@ class Synchronizer:
             if isinstance(elem, str):
                 yield elem
 
-            elif elem.identifier not in [".", "_"]:
-                if isinstance(elem, Image):
-                    nb = self.notebooks[elem.url].nb
-                    yield convert_image(elem, nb)
-                elif code_block := convert_code_block(elem):
-                    yield code_block
+            elif cell := convert(elem, self.notebooks):
+                yield cell
 
 
 def update_notebooks(
-    notebooks: dict[str, Notebook],
     elem: Image | CodeBlock,
+    notebooks: dict[str, Notebook],
     store: Store,
 ) -> None:
     url = elem.url
@@ -93,6 +88,24 @@ def update_notebooks(
         notebook.add_cell(elem.identifier, source)
 
 
+def convert(
+    elem: Image | CodeBlock,
+    notebooks: dict[str, Notebook],
+) -> str | Cell:
+    if elem.identifier not in [".", "_"]:
+        if isinstance(elem, Image):
+            if elem.url not in notebooks:
+                logger.warning(f"Notebook not found: {elem.url}")
+                return ""
+
+            nb = notebooks[elem.url].nb
+            return convert_image(elem, nb)
+
+        return convert_code_block(elem)
+
+    return ""
+
+
 def convert_image(image: Image, nb: NotebookNode) -> Cell:
     try:
         image.source = get_source(nb, image.identifier)

nbsync-0.2.0/tests/test_logger.py

@@ -0,0 +1,64 @@
+import logging
+from logging import Logger
+
+import pytest
+
+from nbsync import logger
+
+
+@pytest.fixture
+def reset_logger():
+    original_logger = logger._logger
+
+    yield
+
+    logger._logger = original_logger
+
+
+def test_default_logger():
+    assert isinstance(logger._logger, Logger)
+    assert logger._logger.name == "nbsync"
+
+
+def test_configure(reset_logger):
+    custom_logger = logging.getLogger("custom_logger")
+
+    result = logger.configure(custom_logger)
+
+    assert result is custom_logger
+    assert logger._logger is custom_logger
+    assert logger._logger.name == "custom_logger"
+
+
+def test_configure_no_args(reset_logger):
+    custom_logger = logging.getLogger("custom_logger")
+    logger._logger = custom_logger
+
+    result = logger.configure()
+
+    assert result is custom_logger
+    assert logger._logger is custom_logger
+
+
+def test_logging_methods(reset_logger, caplog):
+    caplog.set_level(logging.DEBUG, logger="nbsync")
+
+    debug_msg = "Debug message"
+    info_msg = "Info message"
+    warning_msg = "Warning message"
+    error_msg = "Error message"
+
+    logger.debug(debug_msg)
+    logger.info(info_msg)
+    logger.warning(warning_msg)
+    logger.error(error_msg)
+
+    assert debug_msg in caplog.text
+    assert info_msg in caplog.text
+    assert warning_msg in caplog.text
+    assert error_msg in caplog.text
+
+    assert (logger._logger.name, logging.DEBUG, debug_msg) in caplog.record_tuples
+    assert (logger._logger.name, logging.INFO, info_msg) in caplog.record_tuples
+    assert (logger._logger.name, logging.WARNING, warning_msg) in caplog.record_tuples
+    assert (logger._logger.name, logging.ERROR, error_msg) in caplog.record_tuples

{nbsync-0.1.3 → nbsync-0.2.0}/tests/test_sync.py

@@ -57,7 +57,7 @@ def test_update_notebooks(store: Store):
     from nbsync.sync import Notebook, update_notebooks
 
     notebooks: dict[str, Notebook] = {}
-    update_notebooks(notebooks, Image("abc", "id", [], {}, "", "a.ipynb"), store)
+    update_notebooks(Image("abc", "id", [], {}, "", "a.ipynb"), notebooks, store)
     assert len(notebooks) == 1
     nb = notebooks["a.ipynb"].nb
     assert nbstore.notebook.get_source(nb, "id") == "print(1+1)"
@@ -68,7 +68,7 @@ def test_update_notebooks_exec(store: Store):
 
     notebooks: dict[str, Notebook] = {}
     image = Image("abc", "id", [], {"exec": "1"}, "", "a.ipynb")
-    update_notebooks(notebooks, image, store)
+    update_notebooks(image, notebooks, store)
     assert len(notebooks) == 1
     assert notebooks["a.ipynb"].execution_needed
 
@@ -78,7 +78,7 @@ def test_update_notebooks_add_cell(store: Store):
 
     notebooks: dict[str, Notebook] = {}
     code_block = CodeBlock("abc", "id2", [], {}, "123", "a.ipynb")
-    update_notebooks(notebooks, code_block, store)
+    update_notebooks(code_block, notebooks, store)
     assert len(notebooks) == 1
     notebook = notebooks["a.ipynb"]
     assert notebook.execution_needed
@@ -91,7 +91,7 @@ def test_update_notebooks_self(store: Store):
 
     notebooks: dict[str, Notebook] = {}
     code_block = CodeBlock("abc", "id2", [], {}, "123", ".md")
-    update_notebooks(notebooks, code_block, store)
+    update_notebooks(code_block, notebooks, store)
     assert len(notebooks) == 1
     notebook = notebooks[".md"]
     assert len(notebook.nb.cells) == 1
@@ -102,7 +102,7 @@ def test_update_notebooks_error(store: Store):
 
     notebooks: dict[str, Notebook] = {}
     code_block = CodeBlock("abc", "id2", [], {}, "123", "invalid.md")
-    update_notebooks(notebooks, code_block, store)
+    update_notebooks(code_block, notebooks, store)
     assert len(notebooks) == 0
 
 
@@ -160,3 +160,17 @@ def test_sync_code_block(sync: Synchronizer):
     x = next(sync.convert("```a b.md#c source=1\nc\n```"))
     assert isinstance(x, str)
     assert x == "```a  \nc\n```"
+
+
+def test_sync_notebook_not_found():
+    from nbsync.sync import convert
+
+    image = Image("abc", "id", [], {}, "", "a.ipynb")
+    assert convert(image, {}) == ""
+
+
+def test_convert_no_id():
+    from nbsync.sync import convert
+
+    image = Image("abc", ".", [], {}, "", "a.ipynb")
+    assert convert(image, {}) == ""

nbsync-0.1.3/docs/getting-started/configuration.md

@@ -1,35 +0,0 @@
-# Configuration
-
-Configuring nbsync for your MkDocs site is simple but powerful, allowing you to
-customize how notebooks and Python files are integrated with your documentation.
-
-## Basic Configuration
-
-To use nbsync with MkDocs, add it to your `mkdocs.yml` file:
-
-```yaml
-plugins:
-  - search
-  - nbsync
-```
-
-This minimal configuration uses all the default settings.
-
-## Source Directory Configuration
-
-Specify where nbsync should look for notebooks and Python files:
-
-```yaml
-plugins:
-  - search
-  - nbsync:
-      src_dir:
-        - ../notebooks # Path to notebooks directory
-        - ../scripts # Path to Python scripts
-```
-
-The `src_dir` option can be:
-
-- A single path as a string
-- A list of paths
-- Relative to your docs directory