ipynb-pdf 0.1.7

Intelligent IPYNB to HTML/PDF exporter with cell-level preprocessing.

📄 ipynb-pdf

Transformez vos Notebooks Jupyter en documents PDF professionnels et académiques.

ipynb-pdf est un outil de conversion avancé conçu pour les scientifiques, les chercheurs et les data scientists qui souhaitent produire des rapports, des articles ou des thèses directement depuis Jupyter, sans passer par LaTeX manuellement.

---

🚀 Pourquoi utiliser ipynb-pdf ?

• 📚 Gestion Intelligente des Références : Centralise automatiquement vos citations, dédoublonne les entrées et génère une bibliographie propre en fin de document.
• 🎨 Typographie Premium : Utilise des polices de haute qualité (Charter, Lato, Fira Code) et une mise en page soignée (marges, interlignage, césure).
• 🙈 Contrôle Granulaire : Masquez le code, les sorties ou certaines cellules spécifiques grâce à un système de tags simple (hide_code, internal, remove_input).
• ➗ Support Mathématique : Rendu impeccable des équations LaTeX.
• ⚙️ 100% Configurable : Adaptez tout via un simple fichier YAML (marges, polices, comportements).

---

📦 Installation

Prérequis

Ce projet utilise weasyprint pour la génération PDF.

• Windows : Vous devez installer GTK3 séparément. pip install ne suffit pas.

  1. Téléchargez l'installateur gtk3-runtime-x.x.x-x-x-x-ts-win64.exe depuis ce lien.
  2. Lors de l'installation, cochez "Set up PATH environment variable".
  3. Redémarrez votre terminal.

  Sans cela, vous aurez l'erreur : OSError: cannot load library 'libgobject-2.0-0'.

• Linux/macOS : Installez les librairies graphiques nécessaires (ex: pango, gdk-pixbuf).

🚀 Installation rapide (PyPI)

C'est la méthode recommandée. Ouvrez votre terminal et lancez :

pip install ipynb-pdf

Une fois installé, la commande ipynb-pdf est disponible partout dans votre système.

🔧 Installation depuis les sources (Développement)

Si vous souhaitez contribuer ou tester la dernière version non publiée :

git clone https://github.com/KpihX/ipynb-pdf.git
cd ipynb-pdf
pip install .

---

❓ Dépannage & Problèmes fréquents

1. "La commande 'ipynb-pdf' n'est pas reconnue"

Si vous obtenez une erreur indiquant que la commande est introuvable après l'installation, c'est probablement que le dossier des scripts Python n'est pas dans votre PATH.

Solutions :

• Option A (Recommandée) : Ajoutez le dossier Scripts de Python à votre PATH Windows (recherchez "Variables d'environnement" dans Windows).

• Option B (Alternative) : Utilisez la commande via le module Python directement (notez l'underscore _) :

  python -m ipynb_pdf mon_notebook.ipynb
  

2. Erreur "OSError: cannot load library 'libgobject-2.0-0'"

Ceci indique que GTK3 n'est pas installé ou mal configuré.

• Assurez-vous d'avoir installé GTK3 (voir section Prérequis ci-dessus).
• Vérifiez que vous avez bien coché "Set up PATH environment variable" lors de l'installation de GTK3.
• Redémarrez votre ordinateur si le redémarrage du terminal ne suffit pas.

---

🛠️ Utilisation

Commande de base

Convertissez un notebook en une seule ligne de commande :

ipynb-pdf mon_notebook.ipynb

Avec configuration personnalisée

Pour un contrôle total sur le rendu, utilisez un fichier de configuration :

ipynb-pdf mon_notebook.ipynb --config config.yaml --output rapport_final.pdf

---

📂 Exemples

Le dossier examples/ contient tout ce qu'il faut pour démarrer :

1. Cas Simple (examples/simple_case/)

Une démonstration des fonctionnalités de base : masquage de code, tags, et formatage simple.

ipynb-pdf examples/simple_case/feature_demo.ipynb --config examples/simple_case/config.yaml

2. Cas Complexe (examples/complex_case/)

Un exemple réel de papier académique ("Algorithmes Randomisés") avec :

• Formules mathématiques complexes
• Figures et graphiques
• Bibliographie et citations croisées
• Mise en page stricte

ipynb-pdf examples/complex_case/RandomAlgorithms.ipynb --config examples/complex_case/config_RandomAlgorithms.yaml

---

⚙️ Configuration

Créez un fichier config.yaml pour surcharger les paramètres par défaut. Voici les options principales :

# === Apparence ===
pdf_margin_top: 2.5cm
pdf_margin_bottom: 2.5cm
text_font_family: "Charter, serif"
code_font_size: 9pt

# === Comportement ===
hide_code_by_default: false       # Masquer tout le code par défaut ?
hide_execution_count: true        # Masquer les [1]: ?
reflow_markdown: true             # Reformater le texte Markdown ?

# === Tags Spéciaux ===
remove_cells_with_tag: ['remove', 'internal']
hide_code_with_tag: ['hide_code', 'secret']
partial_code_with_tag: ['partial'] # Montre seulement le début/fin du code

# === Bibliographie ===
centralize_references: true       # Regrouper les références à la fin ?

---

🏗️ Structure du Projet

ipynb-pdf/
├── ipynb_pdf/              # 🐍 Code source du package
│   ├── css/                # 🎨 Feuilles de style CSS (Base, Typo, Code)
│   ├── templates/          # 📝 Templates HTML (Jinja2)
│   ├── utils/              # 🔧 Utilitaires (Preprocessing, Refs, Logs)
│   ├── cli.py              # 💻 Point d'entrée ligne de commande
│   └── config.py           # ⚙️ Gestion de la configuration
├── examples/               # 💡 Exemples (Simple & Complexe)
├── tests/                  # 🧪 Tests unitaires (Pytest)
├── pyproject.toml          # 📦 Métadonnées du projet
└── README.md               # 📖 Ce fichier

---

🧪 Développement

Pour lancer la suite de tests et vous assurer que tout fonctionne :

pytest tests/

---

👤 Auteur

KpihX

• GitHub Profile

📄 Licence

Ce projet est sous licence MIT. Vous êtes libre de l'utiliser, le modifier et le distribuer.