feat: update quick start examples and enhance documentation with new concepts and layout customization

Author: ya7010

docs/docs/codes/apply_sample.py

@@ -0,0 +1,34 @@
+import tppt
+
+
+def format_text(
+    text_obj: tppt.Text, text: str, *, bold: bool = False, italic: bool = False
+) -> tppt.Text:
+    paragraph = text_obj.text_frame.add_paragraph()
+    run = paragraph.add_run()
+    run.text = text
+    font = run.font
+    if bold:
+        font.bold = True
+    if italic:
+        font.italic = True
+
+    return text_obj
+
+
+(
+    tppt.Presentation.builder()
+    .slide(
+        lambda slide: slide.BlankLayout()
+        .builder()
+        .text(
+            tppt.apply(format_text, "Hello, World!", bold=True, italic=True),
+            left=(1, "in"),
+            top=(1, "in"),
+            width=(5, "in"),
+            height=(2, "in"),
+        )
+    )
+    .build()
+    .save("simple.pptx")
+)

docs/docs/codes/quick-start.py renamed to docs/docs/codes/quick_start.py

@@ -0,0 +1,19 @@
+import tppt
+from tppt.types import Inches
+
+(
+    tppt.Presentation.builder()
+    .slide(
+        lambda slide: slide.BlankLayout()
+        .builder()
+        .text(
+            "Hello, World!",
+            left=Inches(1),
+            top=Inches(1),
+            width=Inches(5),
+            height=Inches(2),
+        )
+    )
+    .build()
+    .save("simple.pptx")
+)

docs/docs/codes/quick_start_many_import.py

@@ -0,0 +1,82 @@
+# TPPTのコンセプト
+
+## なぜTPPTなのか？
+
+生成AIが普及している現在でも、レポートを pptx で提出してほしい、といった要望は多いものです。
+（私たちが取り残されているだけなのだろうか？）
+
+tppt は python-pptx のラッパーであり、スライドマスターの型安全な利用などを提供します。
+
+また、簡単に利用でき、直感的に記述されるためのアイデアを投入したものであり、
+皆さんの pptx の生成がより安全に、簡単になることを願っています。
+
+## import の削減
+もう一度 Quick Start を見てみましょう。
+```python
+--8<-- "codes/quick_start.py"
+```
+
+このコードは、TPPTのみをインポートしています。
+
+極端に少ない import で、PowerPoint のプレゼンテーションを作成できます。
+
+これは、 AI でコード生成をする際、常に tppt を import するだけで済むように配慮することで、
+コード生成の成功率を高めることができないか？という実験的なアプローチです。
+
+これの実現には二つのテクニックが利用されています。
+
+### Literal 型の積極的採用
+
+例えば、スライドに追加する Shape の形は従来のように次のように書くことができます。
+
+```python
+--8<-- "codes/quick_start_many_import.py"
+```
+
+つまり、 `tppt.types.Inches(1)` と同じことを `(1, "in")` と書くことができます。
+
+このように、肩による単位の指定を Literal で表現することで、従来必要であったインポートを減らしています。
+
+これは、書き込みの話であり、プロパティを読み取るには必ず Inches 型に変換されている状態であるため、加減算や比較ができるようになっています。
+
+
+### 型の引き出し
+
+いくつかの場所で `lambda slide: slide...` のように lambda 式を利用している箇所があります。
+これは遅延評価であり、要素を初期化した時点の方を取り出し、それに操作を加えることで要素を完成させます。
+
+このアプローチの特徴は、型を import してから関数の引数に渡すのではなく、
+関数の中から型を取り出して利用するというものです。
+
+これにより、コード生成としては import をさらに減らしています。
+
+この方法には別のメリットがあります。
+引き出した型に対する操作を関数で切り出すことで、部品を共通化することが容易になります。
+
+```python
+--8<-- "codes/apply_sample.py"
+```
+
+あなたは `format_text` のような独自の修飾関数を作成し、それを簡単に再利用できます。
+
+### 型安全性
+このツールはスライドマスターを元に、新規のスライド作成を行うユーザをメインターゲットとしています。
+
+さて、あなたが私と同じであれば、 python-pptx のスライドマスターに型を与えることに苦労したはずです。
+
+tppt は、 pydantic のような宣言的な型ヒントを利用してスライドマスターに型を与えることができます。
+
+```python
+--8<-- "codes/custom_slide_master.py"
+```
+
+型定義を自分で書くのは面倒だ？そんな方のために、ささやかなツールも用意しています。
+
+```bash
+python -m tppt.tool.ppt2template $YOUR_TEMPLATE.pptx -o $OUTPUT_FILE.py
+```
+
+スライドレイアウトのコンストラクタでプレースホルダーの設定をした後、
+テキストやピクチャ、表などのデータを記述することができます。
+
+これらの操作は全て型安全です！

docs/docs/home/concept.md

@@ -7,7 +7,7 @@ A modern Python library for creating beautiful PowerPoint presentations with cod
 ## Quick Start
 
 ```python
---8<-- "codes/quick-start.py"
+--8<-- "codes/quick_start.py"
 ```
 
 ## Features

docs/docs/index.md

@@ -1 +1,87 @@
+# スライドレイアウト
 
+TPPTでは、スライドのレイアウトを柔軟にカスタマイズすることができます。ここでは、基本的なレイアウトの設定方法と、よく使用されるパターンについて説明します。
+
+## 基本的なレイアウト設定
+
+### 1. スライドサイズの設定
+```python
+from tppt import Presentation
+
+# 16:9のワイドスクリーン形式
+presentation = Presentation(slide_width=16, slide_height=9)
+
+# 4:3の標準形式
+presentation = Presentation(slide_width=4, slide_height=3)
+```
+
+### 2. マージンの設定
+```python
+# スライドの余白を設定
+slide = presentation.add_slide()
+slide.set_margins(left=1.0, right=1.0, top=0.5, bottom=0.5)
+```
+
+## 一般的なレイアウトパターン
+
+### 1. タイトルスライド
+```python
+slide = presentation.add_slide()
+slide.add_title("プレゼンテーションのタイトル")
+slide.add_subtitle("サブタイトル")
+```
+
+### 2. 2カラムレイアウト
+```python
+slide = presentation.add_slide()
+left_column = slide.add_column(width=0.5)
+right_column = slide.add_column(width=0.5)
+
+left_column.add_text("左側のコンテンツ")
+right_column.add_text("右側のコンテンツ")
+```
+
+### 3. 画像とテキストの組み合わせ
+```python
+slide = presentation.add_slide()
+slide.add_image("path/to/image.png", width=0.6)
+slide.add_text("画像の説明文", position="bottom")
+```
+
+## レイアウトのカスタマイズ
+
+### 1. グリッドシステムの利用
+```python
+slide = presentation.add_slide()
+grid = slide.add_grid(rows=2, cols=2)
+grid[0, 0].add_text("セル1")
+grid[0, 1].add_text("セル2")
+grid[1, 0].add_text("セル3")
+grid[1, 1].add_text("セル4")
+```
+
+### 2. フレックスボックスレイアウト
+```python
+slide = presentation.add_slide()
+flex = slide.add_flex_container()
+flex.add_item("アイテム1", flex_grow=1)
+flex.add_item("アイテム2", flex_grow=2)
+```
+
+## ベストプラクティス
+
+1. **一貫性の維持**
+   - 同じ種類のスライドでは、常に同じレイアウトを使用する
+   - マージンやパディングの値を統一する
+
+2. **視覚的な階層構造**
+   - 重要な情報は大きく、目立つように配置
+   - 補足情報は小さく、控えめに配置
+
+3. **余白の活用**
+   - 適切な余白を確保し、見やすいレイアウトを心がける
+   - 要素同士の間隔を適切に設定する
+
+4. **レスポンシブ対応**
+   - 異なる画面サイズでも見やすいレイアウトを考慮
+   - コンテンツの自動調整機能を活用する

docs/docs/usage/slide-layout.md

@@ -10,7 +10,7 @@
 
 def main():
     def formatted_text(text: tppt.pptx.shape.text.Text, /) -> tppt.pptx.shape.text.Text:
-        run = text.text_frame().add_paragraph().add_run()
+        run = text.text_frame.add_paragraph().add_run()
         run.text = "Hello, world!"
         font = run.font
         font.color.rgb = "#00FFFF"
@@ -27,7 +27,7 @@ def functional_text(
         italic: bool = False,
         color: tppt.types.Color | tppt.types.LiteralColor | None = None,
     ) -> tppt.pptx.shape.text.Text:
-        run = text_obj.text_frame().add_paragraph().add_run()
+        run = text_obj.text_frame.add_paragraph().add_run()
         run.text = text
         font = run.font
 

examples/formatted_text.py

@@ -3,9 +3,17 @@
 import importlib.metadata
 from typing import Callable, Concatenate, ParamSpec, TypeVar
 
-from tppt.pptx.presentation import Presentation
-from tppt.template.slide_layout import Placeholder, SlideLayout
-from tppt.template.slide_master import Layout, SlideMaster, slide_master
+from tppt.pptx.presentation import Presentation as Presentation
+from tppt.pptx.shape.picture import Picture as Picture
+from tppt.pptx.shape.text import Text as Text
+from tppt.pptx.slide import Slide as Slide
+from tppt.pptx.table import Table as Table
+from tppt.pptx.table import TableCellStyle as TableCellStyle
+from tppt.template.slide_layout import Placeholder as Placeholder
+from tppt.template.slide_layout import SlideLayout as SlideLayout
+from tppt.template.slide_master import Layout as Layout
+from tppt.template.slide_master import SlideMaster as SlideMaster
+from tppt.template.slide_master import slide_master as slide_master
 
 from . import types as types
 
@@ -35,15 +43,3 @@ def wrapper(x: T) -> T:
         return func(x, *args, **kwargs)
 
     return wrapper
-
-
-__all__ = [
-    "Presentation",
-    "SlideLayout",
-    "Placeholder",
-    "SlideLayout",
-    "SlideMaster",
-    "Layout",
-    "slide_master",
-    "apply",
-]

src/tppt/__init__.py

@@ -23,7 +23,7 @@
 from tppt.types._length import (
     CentiMeters,
     EnglishMetricUnits,
-    Inchs,
+    Inches,
     Length,
     LiteralLength,
     MilliMeters,
@@ -61,7 +61,7 @@ def to_pptx_length(length: Length | LiteralLength | None) -> PptxLength | None:
         length = to_length(length)
 
     match length:
-        case Inchs():
+        case Inches():
             return PptxInches(length.value)
         case CentiMeters():
             return PptxCm(length.value)

src/tppt/pptx/converter.py

@@ -70,6 +70,7 @@ def __init__(self, pptx_obj: PptxShape, data: TextData | None = None, /) -> None
 
         self._pptx = pptx_obj
 
+    @property
     def text_frame(self) -> TextFrame:
         return TextFrame(self._pptx.text_frame)