Metadata-Version: 2.4
Name: jupyter-lecture-studio
Version: 0.2.0
Summary: Animated lecture slides, teaching notebooks and offline HTML for Jupyter, with Arabic RTL support
Author: aoos101
License-Expression: MIT AND OFL-1.1 AND BSD-2-Clause
Project-URL: Homepage, https://pypi.org/project/jupyter-lecture-studio/
Project-URL: Documentation, https://pypi.org/project/jupyter-lecture-studio/#description
Project-URL: Maintainer, https://pypi.org/user/aoos101/
Keywords: jupyter,jupyterlab,lecture,slides,presentation,teaching,education,notebook,arabic,rtl,html,animation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Arabic
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Education
Classifier: Topic :: Multimedia :: Graphics :: Presentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: src/lecture_studio/assets/fonts/cairo-OFL.txt
License-File: src/lecture_studio/assets/fonts/jetbrainsmono-OFL.txt
License-File: docs/_static/licenses/Furo-LICENSE.txt
License-File: docs/_static/licenses/Gumshoe-LICENSE.txt
License-File: docs/_static/licenses/Sphinx-LICENSE.txt
Provides-Extra: notebook
Requires-Dist: ipython>=8; extra == "notebook"
Provides-Extra: highlight
Requires-Dist: pygments>=2.15; extra == "highlight"
Provides-Extra: docs
Requires-Dist: sphinx<10,>=8; extra == "docs"
Requires-Dist: myst-parser<6,>=4; extra == "docs"
Requires-Dist: furo>=2024; extra == "docs"
Dynamic: license-file

# Jupyter Lecture Studio

**Animated Jupyter lecture slides, reusable teaching components, and offline HTML — with Arabic RTL support.**

Create polished lecture covers, explanation cards, syntax-highlighted code, concept diagrams, reveal activities and comparison tables from Python or JSON. Keep one visual identity across programming, AI, databases and other subjects.

## Install

Requires **Python 3.10 or newer**. Install in the same environment as your Jupyter kernel:

```bash
python -m pip install "jupyter-lecture-studio[notebook,highlight]"
```

For HTML generation and the command-line interface without notebook display:

```bash
python -m pip install jupyter-lecture-studio
```

The core renderer has no required dependencies. `notebook` adds IPython; `highlight` adds Pygments for languages beyond the built-in Python highlighter. The package does not install Jupyter itself.

## Your first lecture

Run this in a Jupyter notebook:

```python
from jupyter_lecture_studio import LectureDeck

deck = LectureDeck(
    course="Python Programming", series="PROGRAMMING LAB",
    lesson="01", direction="ltr", theme="gold",
)

deck.cover(
    "Names and values",
    "Connect familiar programming ideas to Python.\nPredict, run, explain.",
    tags=["Understand", "Experiment", "Explain"],
    hero_code="value = 10\nvalue = 'ten'",
    hero_result="A name can refer to a different object.",
)

deck.slide(
    "Rebinding a name",
    cards=[
        {"title": "Observe", "code": "value = 10\nvalue = 'ten'"},
        {"title": "Explain", "explanation": "Assignment binds a name to an object."},
    ],
    activity={
        "question": "What does value refer to after the second assignment?",
        "answer": "The string 'ten'. The name has been rebound.",
        "label": "Predict first", "reveal": "Show explanation",
    },
)

deck.export("lecture.html")
```

Use `show=False` on component methods when generating HTML from a Python script. Each component is collected for export. Re-run the notebook in order before exporting; repeated component calls append another copy. Code inside cards is displayed; executable student practice belongs in normal notebook code cells.

## What you get

| Feature | Teaching use |
|---|---|
| Animated covers and cards | Introduce a topic and build an explanation in readable steps |
| Arabic RTL and English LTR | Mix Arabic explanations with correctly aligned code |
| Concept diagrams | Supply your own nodes or choose 11 Python concept presets |
| Reveal activities | Ask students to predict before opening the explanation |
| Three themes and custom colors | Reuse a consistent course identity |
| Embedded Cairo and JetBrains Mono | Preserve Arabic and code typography offline |
| Standalone HTML and print styles | Share a lecture or print from a browser |
| Python, dataclasses and JSON | Author content in the workflow you prefer |
| Reduced-motion support | Respect system preferences or disable motion explicitly |
| Bundled documentation | Search and read English/Arabic guides without an internet connection |

## Reuse the design

```python
from jupyter_lecture_studio import Brand, Theme, LectureDeck

deck = LectureDeck(
    brand=Brand(course="Database Systems", series="DATABASE LAB", language="sql"),
    theme=Theme(preset="ocean", direction="ltr", motion=True),
)

deck.slide("From query to result", diagram={
    "title": "Query pipeline", "direction": "ltr",
    "nodes": [
        {"value": "SQL", "note": "Describe the result"},
        {"value": "Plan", "note": "Choose operations"},
        {"value": "Rows", "note": "Inspect the output", "selected": True},
    ],
}, show=False)

deck.export("database-lecture.html")
```

Set `Theme(motion=False)` to disable animation. Embedded fonts are the default; `external_fonts=True` opts into Google Fonts and requires network access. Notebook-wide styling is opt-in through `notebook_style=True`; default styles are scoped to the rendered components.

## CLI and JSON workflow

```bash
jupyter-lecture-studio init my-lecture --course "Artificial Intelligence"
jupyter-lecture-studio export my-lecture/lecture.json my-lecture/lecture.html
jupyter-lecture-studio docs
```

`init` creates a JSON content file, a starter notebook and a short guide. It refuses to overwrite an existing folder. `export` replaces its destination HTML file. `docs` prints the path of the complete bundled documentation; open that file in your browser.

```python
from jupyter_lecture_studio import documentation_path
print(documentation_path())
```

The documentation includes installation, a first lecture, every component, theme settings, classroom recipes, JSON/CLI usage, the API reference, migration and troubleshooting. HTML exports contain the deck components; unrelated notebook code cells are not exported. For PDF, use your browser's Print function.

## التوثيق العربي — بداية سريعة

مكتبة لبناء محاضرات Jupyter بتصميم موحد، أغلفة وبطاقات متحركة، رسومات تعليمية، وأسئلة بإجابات قابلة للكشف. مناسبة لإعادة استخدام التصميم مع جميع المواد، مع دعم العربية واتجاه الكتابة من اليمين إلى اليسار.

```python
from jupyter_lecture_studio import LectureDeck

deck = LectureDeck(course="الذكاء الاصطناعي", lesson="01")
deck.cover(
    "من البيانات إلى القرار",
    "نفهم الفكرة من مثال واضح.\nثم نجرّب ونفسّر النتيجة.",
    tags=["افهم", "توقّع", "جرّب"],
)
deck.slide("الفكرة الأساسية", cards=[
    {"title": "نفهم", "explanation": "نربط المفهوم بخبرة الطالب السابقة."},
    {"title": "نطبّق", "code": "print('Hello')"},
], activity={
    "question": "ما النتيجة المتوقعة؟",
    "answer": "تظهر كلمة Hello؛ اشرح لماذا قبل التنفيذ.",
})
deck.export("lecture.html")
```

الخط الأصلي **Cairo** للعربية و**JetBrains Mono** للكود مضمّن داخل الحزمة وملف HTML افتراضيًا. لا تظهر أوقات الأقسام للطلاب. استخدم `jupyter-lecture-studio docs` لفتح دليل عربي مفصل ومرجع الواجهة؛ التوثيق كامل ومرفق مع التثبيت.

غيّر `course` و`series` و`lesson` لهوية المادة، وأعد استخدام المكونات نفسها. يمكنك تعديل المحتوى في `lecture.json` دون إعادة كتابة الدفتر. أكواد البطاقات للعرض، والتجارب التنفيذية توضع في خلايا Jupyter العادية.

## Compatibility and limitations

Existing `from lecture_studio import LectureDeck` imports and the `lecture-studio` command remain available. The legacy `LuxurySlideDeck` adapter is available from `jupyter_lecture_studio.compat`.

Tested workflows target JupyterLab and modern browsers. Other notebook hosts may restrict HTML/CSS; do not assume identical animation or styling in every host. Reveal answers remain in the HTML source and are intended for learning activities. Plain text is escaped by default; `RichText` explicitly accepts trusted author HTML without sanitization.

## License and project

Library code is **MIT**. Bundled fonts are **SIL Open Font License 1.1**; their original licenses and asset manifest are included. Bundled documentation assets retain their upstream notices. See the documentation's licensing page for details.

Maintained by [aoos101](https://pypi.org/user/aoos101/). Project and release files: [Jupyter Lecture Studio on PyPI](https://pypi.org/project/jupyter-lecture-studio/).
