Skip to content

Commit 1d7b94b

Browse files
committed
docs: update concept documentation for clarity and improve structure
1 parent 53a80e3 commit 1d7b94b

File tree

1 file changed

+40
-37
lines changed

1 file changed

+40
-37
lines changed

docs/docs/home/concept.md

Lines changed: 40 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,82 +1,85 @@
1-
# TPPTのコンセプト
1+
# TPPT Concept
22

3-
## なぜTPPTなのか?
3+
## Why TPPT?
44

5-
生成AIが普及している現在でも、レポートを pptx で提出してほしい、といった要望は多いものです。
6-
(私たちが取り残されているだけなのだろうか?)
5+
Even in the current era of widespread generative AI, there are still many requests for submitting reports in pptx format.
6+
(Are we the only ones being left behind?)
77

8-
tppt は python-pptx のラッパーであり、スライドマスターの型安全な利用などを提供します。
8+
TPPT is a wrapper for python-pptx that provides type-safe usage of slide masters and more.
99

10-
また、簡単に利用でき、直感的に記述されるためのアイデアを投入したものであり、
11-
皆さんの pptx の生成がより安全に、簡単になることを願っています。
10+
It also incorporates ideas to make it easy to use and intuitive to write,
11+
hoping to make your pptx generation safer and simpler.
1212

13-
## import の削減
14-
もう一度 Quick Start を見てみましょう。
13+
## Reducing Imports
14+
Let's look at the Quick Start again:
1515
```python
1616
--8<-- "codes/quick_start.py"
1717
```
1818

19-
このコードは、TPPTのみをインポートしています。
19+
This code only imports TPPT.
2020

21-
極端に少ない import で、PowerPoint のプレゼンテーションを作成できます。
21+
You can create PowerPoint presentations with an extremely minimal number of imports.
2222

23-
これは、 AI でコード生成をする際、常に tppt を import するだけで済むように配慮することで、
24-
コード生成の成功率を高めることができないか?という実験的なアプローチです。
23+
This is an experimental approach to increase the success rate of code generation by AI,
24+
by ensuring that only importing tppt is sufficient.
2525

26-
これの実現には二つのテクニックが利用されています。
26+
Two techniques are used to achieve this:
2727

28-
### Literal 型の積極的採用
28+
### Active Adoption of Literal Types
2929

30-
例えば、スライドに追加する Shape の形は従来のように次のように書くことができます。
30+
For example, the shape of a Shape to be added to a slide can be written in the traditional way:
3131

3232
```python
3333
--8<-- "codes/quick_start_many_import.py"
3434
```
3535

36-
つまり、 `tppt.types.Inches(1)` と同じことを `(1, "in")` と書くことができます。
36+
In other words, `tppt.types.Inches(1)` can be written as `(1, "in")`.
3737

38-
このように、肩による単位の指定を Literal で表現することで、従来必要であったインポートを減らしています。
38+
By expressing unit specifications with types using Literals in this way,
39+
we have reduced the imports that were previously necessary.
3940

40-
これは、書き込みの話であり、プロパティを読み取るには必ず Inches 型に変換されている状態であるため、加減算や比較ができるようになっています。
41+
This is about writing; when reading properties, they are always converted to the Inches type,
42+
allowing for addition, subtraction, and comparison.
4143

44+
### Type Extraction
4245

43-
### 型の引き出し
46+
There are places where lambda expressions like `lambda slide: slide...` are used.
47+
This is lazy evaluation, where the type is extracted at the time of element initialization,
48+
and the element is completed by adding operations to it.
4449

45-
いくつかの場所で `lambda slide: slide...` のように lambda 式を利用している箇所があります。
46-
これは遅延評価であり、要素を初期化した時点の方を取り出し、それに操作を加えることで要素を完成させます。
50+
The characteristic of this approach is that instead of importing types and passing them to function arguments,
51+
types are extracted from within the function and used.
4752

48-
このアプローチの特徴は、型を import してから関数の引数に渡すのではなく、
49-
関数の中から型を取り出して利用するというものです。
53+
This further reduces imports for code generation.
5054

51-
これにより、コード生成としては import をさらに減らしています。
52-
53-
この方法には別のメリットがあります。
54-
引き出した型に対する操作を関数で切り出すことで、部品を共通化することが容易になります。
55+
This method has another advantage.
56+
By extracting operations on the extracted types into functions,
57+
it becomes easier to share components.
5558

5659
```python
5760
--8<-- "codes/apply_sample.py"
5861
```
5962

60-
あなたは `format_text` のような独自の修飾関数を作成し、それを簡単に再利用できます。
63+
You can create your own modifier functions like `format_text` and easily reuse them.
6164

62-
### 型安全性
63-
このツールはスライドマスターを元に、新規のスライド作成を行うユーザをメインターゲットとしています。
65+
### Type Safety
66+
This tool is mainly targeted at users who create new slides based on slide masters.
6467

65-
さて、あなたが私と同じであれば、 python-pptx のスライドマスターに型を与えることに苦労したはずです。
68+
If you're like me, you've probably struggled with giving types to python-pptx's slide masters.
6669

67-
tppt は、 pydantic のような宣言的な型ヒントを利用してスライドマスターに型を与えることができます。
70+
TPPT allows you to give types to slide masters using declarative type hints like pydantic.
6871

6972
```python
7073
--8<-- "codes/custom_slide_master.py"
7174
```
7275

73-
型定義を自分で書くのは面倒だ?そんな方のために、ささやかなツールも用意しています。
76+
Is writing type definitions yourself tedious? We've prepared a modest tool for you.
7477

7578
```bash
7679
python -m tppt.tool.ppt2template $YOUR_TEMPLATE.pptx -o $OUTPUT_FILE.py
7780
```
7881

79-
スライドレイアウトのコンストラクタでプレースホルダーの設定をした後、
80-
テキストやピクチャ、表などのデータを記述することができます。
82+
After setting placeholders in the slide layout constructor,
83+
you can describe data such as text, pictures, and tables.
8184

82-
これらの操作は全て型安全です!
85+
All these operations are type-safe!

0 commit comments

Comments
 (0)