nbsync 0.0.1__tar.gz → 0.1.0__tar.gz

nbsync-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,19 @@
+{
+  "image": "mcr.microsoft.com/vscode/devcontainers/base:ubuntu24.04",
+  "features": {
+    "ghcr.io/devcontainers-contrib/features/starship:1": {}
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "charliermarsh.ruff",
+        "fill-labs.dependi",
+        "markis.code-coverage",
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "tamasfe.even-better-toml"
+      ]
+    }
+  },
+  "postCreateCommand": ".devcontainer/postCreate.sh"
+}

nbsync-0.1.0/.devcontainer/postCreate.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+echo 'eval "$(starship init bash)"' >> ~/.bashrc
+mkdir -p ~/.config
+cp .devcontainer/starship.toml ~/.config
+
+curl -LsSf https://astral.sh/uv/install.sh | sh
+echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

nbsync-0.1.0/.devcontainer/starship.toml

@@ -0,0 +1,29 @@
+"$schema" = 'https://starship.rs/config-schema.json'
+
+add_newline = true
+
+[username]
+disabled = true
+
+[hostname]
+disabled = true
+
+[package]
+format = '[$symbol$version]($style) '
+symbol = "󰏗 "
+style = 'bold blue'
+
+[git_branch]
+format = '[$symbol$branch(:$remote_branch)]($style)'
+symbol = ' '
+style = 'bold green'
+
+[git_status]
+style = 'red'
+modified = '*'
+format = '([$modified]($style)) '
+
+[python]
+format = '[${symbol}${pyenv_prefix}(${version} )(\($virtualenv\) )]($style)'
+symbol = ' '
+style = 'yellow'

nbsync-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+**/notebooks/* linguist-vendored
+.devcontainer/* linguist-vendored
+*.ipynb linguist-vendored

nbsync-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: test-${{ github.head_ref }}
+  cancel-in-progress: true
+
+env:
+  PYTHONUNBUFFERED: "1"
+  FORCE_COLOR: "1"
+
+jobs:
+  run:
+    name: Python ${{ matrix.python-version }} on ${{ startsWith(matrix.os, 'macos-') && 'macOS' || startsWith(matrix.os, 'windows-') && 'Windows' || 'Linux' }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+      - name: Install uv and ruff
+        run: pip install uv ruff
+      - name: Install the project
+        run: uv sync
+      - name: Ruff check
+        run: ruff check
+      - name: Run test
+        run: uv run pytest -v --junitxml=junit.xml
+      - name: Upload Codecov Results
+        if: success()
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: lcov.info
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() }}
+        uses: codecov/test-results-action@v1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

nbsync-0.1.0/.github/workflows/docs.yaml

@@ -0,0 +1,29 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.13
+      - name: Install uv
+        run: pip install uv
+      - name: Install the project
+        run: uv sync
+      - name: Deploy documentation
+        run: uv run mkdocs gh-deploy --force

nbsync-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,37 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify version match
+        run: |
+          TAG=${GITHUB_REF#refs/tags/}
+          PYPROJECT_VERSION=$(grep -m 1 "version = " pyproject.toml | cut -d'"' -f2)
+          if [ "$TAG" != "$PYPROJECT_VERSION" ]; then
+            echo "Error: Git tag ($TAG) does not match pyproject.toml version ($PYPROJECT_VERSION)"
+            exit 1
+          fi
+          echo "Version verified: $TAG"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.13
+      - name: Install uv
+        run: pip install uv
+      - name: Install the project
+        run: uv sync
+      - name: Build the project
+        run: uv build --no-sources
+      - name: Upload the project to PyPI
+        run: uv publish

nbsync-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Daizu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nbsync-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: nbsync
+Version: 0.1.0
+Summary: MkDocs plugin treating Jupyter notebooks, Python scripts and Markdown files as first-class citizens for documentation with dynamic execution and real-time synchronization
+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
+Author-email: daizutabi <daizutabi@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Daizu
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        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
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+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
+Description-Content-Type: text/markdown
+
+# nbsync
+
+[![PyPI Version][pypi-v-image]][pypi-v-link]
+[![Python Version][python-v-image]][python-v-link]
+[![Build Status][GHAction-image]][GHAction-link]
+[![Coverage Status][codecov-image]][codecov-link]
+
+<strong>Connect Jupyter notebooks to your MkDocs documentation</strong>
+
+nbsync is a MkDocs plugin that seamlessly embeds Jupyter notebook
+visualizations in your documentation, solving the disconnect between
+code development and documentation.
+
+## Why Use nbsync?
+
+### The Documentation Challenge
+
+Data scientists, researchers, and technical writers face a common dilemma:
+
+- **Development happens in notebooks** - ideal for experimentation and visualization
+- **Documentation lives in markdown** - perfect for narrative and explanation
+- **Connecting the two is painful** - screenshots break, exports get outdated
+
+### Our Solution
+
+This plugin creates a live bridge between your notebooks and documentation by:
+
+- **Keeping environments separate** - work in the tool best suited for each task
+- **Maintaining connections** - reference specific figures from notebooks
+- **Automating updates** - changes to notebooks reflect in documentation
+
+## Key Benefits
+
+- **True Separation of Concerns**:
+  Develop visualizations in Jupyter notebooks and write documentation
+  in markdown files, with each tool optimized for its purpose.
+
+- **Intuitive Markdown Syntax**:
+  Use standard image syntax with a simple extension to reference
+  notebook figures: `![alt text](notebook.ipynb){#figure-id}`
+
+- **Automatic Updates**:
+  When you modify your notebooks, your documentation updates
+  automatically in MkDocs serve mode.
+
+- **Clean Source Documents**:
+  Your markdown remains readable and focused on content, without
+  code distractions or complex embedding techniques.
+
+- **Enhanced Development Experience**:
+  Take advantage of IDE features like code completion and syntax
+  highlighting in the appropriate environment.
+
+## Quick Start
+
+### 1. Installation
+
+```bash
+pip install nbsync
+```
+
+### 2. Configuration
+
+Add to your `mkdocs.yml`:
+
+```yaml
+plugins:
+  - nbsync:
+      src_dir: ../notebooks
+```
+
+### 3. Mark Figures in Your Notebook
+
+In your Jupyter notebook, identify figures with a comment:
+
+```python
+# #my-figure
+import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots(figsize=(8, 4))
+ax.plot([1, 2, 3, 4], [10, 20, 25, 30])
+```
+
+### 4. Reference in Markdown
+
+Use standard Markdown image syntax with the figure identifier:
+
+```markdown
+![Chart description](my-notebook.ipynb){#my-figure}
+```
+
+## Advanced Usage
+
+For more detailed information on how to use nbsync, see:
+
+- [Notebook Configuration](usage/notebook.md) - Setting up notebook directories
+- [Class Options](usage/class.md) - Control how notebook content is displayed
+<!-- - [Workflow Tips](usage/workflow.md) - Best practices for documentation -->
+
+## The Power of Separation
+
+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
+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
+handles the integration automatically.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## License
+
+This project is licensed under the MIT License.
+
+<!-- Badges -->
+[pypi-v-image]: https://img.shields.io/pypi/v/nbsync.svg
+[pypi-v-link]: https://pypi.org/project/nbsync/
+[python-v-image]: https://img.shields.io/pypi/pyversions/nbsync.svg
+[python-v-link]: https://pypi.org/project/nbsync
+[GHAction-image]: https://github.com/daizutabi/nbsync/actions/workflows/ci.yaml/badge.svg?branch=main&event=push
+[GHAction-link]: https://github.com/daizutabi/nbsync/actions?query=event%3Apush+branch%3Amain
+[codecov-image]: https://codecov.io/github/daizutabi/nbsync/coverage.svg?branch=main
+[codecov-link]: https://codecov.io/github/daizutabi/nbsync?branch=main

nbsync-0.1.0/README.md

@@ -0,0 +1,132 @@
+# nbsync
+
+[![PyPI Version][pypi-v-image]][pypi-v-link]
+[![Python Version][python-v-image]][python-v-link]
+[![Build Status][GHAction-image]][GHAction-link]
+[![Coverage Status][codecov-image]][codecov-link]
+
+<strong>Connect Jupyter notebooks to your MkDocs documentation</strong>
+
+nbsync is a MkDocs plugin that seamlessly embeds Jupyter notebook
+visualizations in your documentation, solving the disconnect between
+code development and documentation.
+
+## Why Use nbsync?
+
+### The Documentation Challenge
+
+Data scientists, researchers, and technical writers face a common dilemma:
+
+- **Development happens in notebooks** - ideal for experimentation and visualization
+- **Documentation lives in markdown** - perfect for narrative and explanation
+- **Connecting the two is painful** - screenshots break, exports get outdated
+
+### Our Solution
+
+This plugin creates a live bridge between your notebooks and documentation by:
+
+- **Keeping environments separate** - work in the tool best suited for each task
+- **Maintaining connections** - reference specific figures from notebooks
+- **Automating updates** - changes to notebooks reflect in documentation
+
+## Key Benefits
+
+- **True Separation of Concerns**:
+  Develop visualizations in Jupyter notebooks and write documentation
+  in markdown files, with each tool optimized for its purpose.
+
+- **Intuitive Markdown Syntax**:
+  Use standard image syntax with a simple extension to reference
+  notebook figures: `![alt text](notebook.ipynb){#figure-id}`
+
+- **Automatic Updates**:
+  When you modify your notebooks, your documentation updates
+  automatically in MkDocs serve mode.
+
+- **Clean Source Documents**:
+  Your markdown remains readable and focused on content, without
+  code distractions or complex embedding techniques.
+
+- **Enhanced Development Experience**:
+  Take advantage of IDE features like code completion and syntax
+  highlighting in the appropriate environment.
+
+## Quick Start
+
+### 1. Installation
+
+```bash
+pip install nbsync
+```
+
+### 2. Configuration
+
+Add to your `mkdocs.yml`:
+
+```yaml
+plugins:
+  - nbsync:
+      src_dir: ../notebooks
+```
+
+### 3. Mark Figures in Your Notebook
+
+In your Jupyter notebook, identify figures with a comment:
+
+```python
+# #my-figure
+import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots(figsize=(8, 4))
+ax.plot([1, 2, 3, 4], [10, 20, 25, 30])
+```
+
+### 4. Reference in Markdown
+
+Use standard Markdown image syntax with the figure identifier:
+
+```markdown
+![Chart description](my-notebook.ipynb){#my-figure}
+```
+
+## Advanced Usage
+
+For more detailed information on how to use nbsync, see:
+
+- [Notebook Configuration](usage/notebook.md) - Setting up notebook directories
+- [Class Options](usage/class.md) - Control how notebook content is displayed
+<!-- - [Workflow Tips](usage/workflow.md) - Best practices for documentation -->
+
+## The Power of Separation
+
+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
+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
+handles the integration automatically.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## License
+
+This project is licensed under the MIT License.
+
+<!-- Badges -->
+[pypi-v-image]: https://img.shields.io/pypi/v/nbsync.svg
+[pypi-v-link]: https://pypi.org/project/nbsync/
+[python-v-image]: https://img.shields.io/pypi/pyversions/nbsync.svg
+[python-v-link]: https://pypi.org/project/nbsync
+[GHAction-image]: https://github.com/daizutabi/nbsync/actions/workflows/ci.yaml/badge.svg?branch=main&event=push
+[GHAction-link]: https://github.com/daizutabi/nbsync/actions?query=event%3Apush+branch%3Amain
+[codecov-image]: https://codecov.io/github/daizutabi/nbsync/coverage.svg?branch=main
+[codecov-link]: https://codecov.io/github/daizutabi/nbsync?branch=main

nbsync-0.1.0/docs/index.md

@@ -0,0 +1,101 @@
+# nbsync
+
+<div class="grid cards" markdown>
+
+- :material-notebook-edit: **Notebooks from Markdown**
+  Extend standard markdown syntax to automatically generate notebooks from
+  documentation
+  [:octicons-arrow-right-24: Markdown Features](#notebooks-from-markdown)
+
+- :material-language-python: **Python File Integration**
+  Directly reference external Python files and reuse functions or classes
+  [:octicons-arrow-right-24: Python Integration](#python-file-integration)
+
+- :material-image-edit: **Code Execution in Images**
+  Execute code within image notation for dynamic visualizations
+  [:octicons-arrow-right-24: Dynamic Visualization](#code-execution-in-images)
+
+- :material-refresh-auto: **Dynamic Updates**
+  Real-time synchronization between notebooks and documentation
+  [:octicons-arrow-right-24: Dynamic Updates](#dynamic-updates-and-execution)
+
+</div>
+
+## What is nbsync?
+
+nbsync is an innovative plugin that seamlessly connects Jupyter notebooks with
+MkDocs documentation. Going beyond traditional notebook integration, it provides
+functionality to generate and execute notebooks directly from markdown (.md)
+files and Python (.py) files.
+
+It solves common challenges faced by data scientists, researchers, and technical
+writers:
+
+- **Development happens in notebooks** - ideal for experimentation and visualization
+- **Documentation lives in markdown** - perfect for narrative and explanation
+- **Traditional integration is challenging** - screenshots break, exports get outdated
+
+## Key Features
+
+### Notebooks from Markdown
+
+Extend standard markdown syntax to define notebook cells within your
+documentation. Present code and its output results concisely with tabbed
+display.
+
+````markdown source="tabbed-nbsync"
+```python .md#plot source="on"
+import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots(figsize=(2, 1))
+ax.plot([1, 3, 3, 4])
+```
+
+![Plot result](){#plot source="on"}
+````
+
+### Python File Integration
+
+Directly reference external Python files and reuse defined functions or classes.
+Avoid code duplication and improve maintainability.
+
+```python title="plot.py"
+--8<-- "scripts/plot.py"
+```
+
+```markdown source="tabbed-nbsync"
+![Plot result](plot.py){#sqrt source="on"}
+```
+
+### Code Execution in Images
+
+Execute Python code directly within image notation and display the results.
+This enables easy placement of dynamic visualizations in tables or complex
+layouts.
+
+```markdown source="tabbed-nbsync"
+|         Sine          |        Cosine         |
+| :-------------------: | :-------------------: |
+| ![](){`plot(np.sin)`} | ![](){`plot(np.cos)`} |
+```
+
+### Dynamic Updates and Execution
+
+Automatic synchronization between notebooks and documentation ensures code
+changes are reflected in real-time. View changes instantly in MkDocs serve mode.
+
+## Getting Started
+
+Follow these steps to get started with nbsync:
+
+1. [Installation](getting-started/installation.md)
+2. [Configuration](getting-started/configuration.md)
+3. [First Steps](getting-started/first-steps.md)
+
+## Examples
+
+Explore the possibilities of nbsync through practical examples:
+
+- [Basic Usage](examples/basic.md)
+- [Visualizations in Tables](examples/tables.md)
+- [Advanced Examples](examples/advanced.md)