From aab765aac0c50f2f7e74a07668b96f92737a0f60 Mon Sep 17 00:00:00 2001 From: Maki Date: Fri, 14 Jun 2024 23:40:25 +0900 Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=93=9D=20[docs]=20Add=20language=20ba?= =?UTF-8?q?dges=20to=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added Japanese and English documentation badges to enhance accessibility and visibility of language options. --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 62ac115a..9546da2f 100755 --- a/README.md +++ b/README.md @@ -17,6 +17,9 @@ # Jupytext +JA doc +EN doc + Have you always wished Jupyter notebooks were plain text documents? Wished you could edit them in your favorite IDE? And get clear and meaningful diffs when doing version control? Then, Jupytext may well be the tool you're looking for! ## Text Notebooks From de5627e6c00f1d121197e393492322bd9b041b2e Mon Sep 17 00:00:00 2001 From: Maki Date: Fri, 14 Jun 2024 23:40:40 +0900 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=8E=89=20[feat]=20Create=20Japanese?= =?UTF-8?q?=20README=20for=20Jupytext?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Introduced a comprehensive README in Japanese, covering features, installation, and usage of Jupytext. - Added badges for continuous integration, documentation status, and more to align with the main README style. - Provided detailed sections on Jupytext's capabilities, such as notebook pairing and command-line usage, catering to the Japanese-speaking community. --- docs/README_JA.md | 122 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 docs/README_JA.md diff --git a/docs/README_JA.md b/docs/README_JA.md new file mode 100644 index 00000000..f72c2f90 --- /dev/null +++ b/docs/README_JA.md @@ -0,0 +1,122 @@ +![](https://github.com/mwouts/jupytext/blob/17aea37c612f33a4e27eeee4b81966f1506920fd/docs/images/logo_large.png?raw=true) + + + +[![CI](https://github.com/mwouts/jupytext/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mwouts/jupytext/actions) +[![Documentation Status](https://readthedocs.org/projects/jupytext/badge/?version=latest)](https://jupytext.readthedocs.io/en/latest/?badge=latest) +[![codecov.io](https://codecov.io/github/mwouts/jupytext/coverage.svg?branch=main)](https://codecov.io/gh/mwouts/jupytext/branch/main) +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) +[![GitHub language count](https://img.shields.io/github/languages/count/mwouts/jupytext)](docs/languages.md) +[![Conda Version](https://img.shields.io/conda/vn/conda-forge/jupytext.svg)](https://anaconda.org/conda-forge/jupytext) +[![Pypi](https://img.shields.io/pypi/v/jupytext.svg)](https://pypi.python.org/pypi/jupytext) +[![pyversions](https://img.shields.io/pypi/pyversions/jupytext.svg)](https://pypi.python.org/pypi/jupytext) +[![Binder:lab](https://img.shields.io/badge/binder-jupyterlab-0172B2.svg)](https://mybinder.org/v2/gh/mwouts/jupytext/main?urlpath=lab/tree/demo/get_started.ipynb) +[![Binder:notebook](https://img.shields.io/badge/binder-notebook-0172B2.svg)](https://mybinder.org/v2/gh/mwouts/jupytext/main?filepath=demo) +[![launch - renku](https://renkulab.io/renku-badge.svg)](https://renkulab.io/projects/best-practices/jupytext/sessions/new?autostart=1) +[![](https://img.shields.io/badge/YouTube-JupyterCon%202020-red.svg)](https://www.youtube.com/watch?v=SDYdeVfMh48) + +# Jupytext + +JA doc +EN doc + +Jupyter Notebookがプレーンテキストドキュメントだったらいいのに、と思ったことはありませんか？お気に入りのIDEで編集できて、バージョン管理時に明確で意味のある差分が得られたら。そんな時は、Jupytextこそまさにあなたが探し求めているツールかもしれません！ + +## テキストノートブック + +`py:percent` [フォーマット](docs/formats-scripts.md#the-percent-format)でエンコードされたPythonノートブックは、`.py`拡張子を持ち、以下のようになります。 + +``` +# %% [markdown] +# これはマークダウンセルです + +# %% +def f(x): + return 3*x+1 +``` + +ノートブックの入力（とオプションでメタデータ）のみが含まれます。テキストノートブックはバージョン管理に適しています。IDEで編集やリファクタリングも可能です。上記の`.py`ノートブックは通常のPythonファイルです。 + +コードを主に含むノートブックには`percent`フォーマットをお勧めします。`percent`フォーマットは、Julia、Python、Rなど多くの[言語](docs/languages.md)で利用可能です。 + +ノートブックがドキュメント指向の場合は、[Markdownベースのフォーマット](docs/formats-markdown.md)（`.md`拡張子のテキストノートブック）の方が適切かもしれません。ノートブックの用途に応じて、Jupyter Bookとの相互運用性に優れたMyst Markdownフォーマット、Quarto Markdown、さらにはPandoc Markdownを選ぶのも良いでしょう。 + +## インストール + +JupyterのPython環境にJupytextをインストールします。以下のどちらかを使用します。 + + pip install jupytext + +または + + conda install jupytext -c conda-forge + +その後、Jupyter Labサーバーを再起動し、JupyterでJupytextが有効になっていることを確認します。`.py`と`.md`ファイルにはノートブックのアイコンが表示され、Jupyter Labで右クリックしてノートブックとして開くことができます。 + +![](https://github.com/mwouts/jupytext/blob/64b4be818508760116f91bf156342cb4cf724d93/docs/images/jupyterlab_right_click.png?raw=true) + +## ペアノートブック + +`.py`や`.md`拡張子のテキストノートブックはバージョン管理に適しています。IDEで簡単に編集や作成ができます。Jupyter Labで右クリックするとノートブックとして開いて実行できます。ただし、テキストノートブックにはノートブックの入力のみが保存されるため、ノートブックを閉じるとノートブックの出力は失われます。 + +テキストノートブックの便利な代替手段は、[ペアノートブック](docs/paired-notebooks.md)です。これは、`.ipynb`と`.py`のように、同じノートブックを異なるフォーマットで含む2つのファイルのセットです。 + +ペアノートブックの`.py`バージョンを編集し、Jupyterで _reload notebook from disk_ を選択することで、編集内容をJupyterに反映させることができます。`.ipynb`ファイルが存在する場合、出力はそこから再読み込みされます。次にJupyterでノートブックを保存すると、`.ipynb`バージョンが更新または再作成されます。 + +Jupyter Labでノートブックをペアリングするには、コマンドパレットから`Pair Notebook with percent Script`コマンドを使用します。 + +![](https://github.com/mwouts/jupytext/blob/64b4be818508760116f91bf156342cb4cf724d93/docs/images/pair_commands.png?raw=true) + +特定のディレクトリ内のすべてのノートブックをペアリングするには、以下の内容で[設定ファイル](docs/config.md)を作成します。 + +``` +# jupytext.toml ノートブックディレクトリのルートに配置 +formats = "ipynb,py:percent" +``` + +## コマンドライン + +Jupytextは[コマンドライン](docs/using-cli.md)でも利用可能です。以下のことができます。 + +- `jupytext --set-formats ipynb,py:percent notebook.ipynb`でノートブックをペアリングする +- `jupytext --sync notebook.py`でペアファイルを同期する（入力は最新のペアファイルから読み込まれる） +- `jupytext --to ipynb notebook.py`でノートブックを別のフォーマットに変換する（特定の出力ファイルを指定する場合は`-o`を使用） +- `jupytext --pipe black notebook.ipynb`のようにノートブックをリンターにパイプで渡す + +## 使用例 + +### バージョン管理下のノートブック + +手順は以下の通りです。 +- Jupyterで`.ipynb`ノートブックを開き、Jupyter Labの _pair_ コマンドまたはグローバルな[設定ファイル](docs/config.md)を使用して、`.py`ノートブックに[ペアリング](docs/paired-notebooks.md)します +- ノートブックを保存すると、`.py`ノートブックが作成されます +- この`.py`ノートブックをバージョン管理に追加します + +バージョン管理から`.ipynb`ファイルを除外しても構いません（出力もバージョン管理したい場合を除く）。ユーザーが`.py`ノートブックを開いて保存すると、Jupytextがローカルに`.ipynb`ファイルを再作成します。 + +### Gitでノートブックをコラボレーション + +Gitを通じたJupyter Notebookでのコラボレーションが、テキストファイルでのコラボレーションと同じくらい簡単になります。 + +`.py`ノートブックをバージョン管理下に置いているとします（上記参照）。そうすると、 +- コラボレーターが`.py`ノートブックをプルします +- Jupyterでそれを _ノートブックとして_ 開きます（Jupyter Labで右クリック） +- この時点では、ノートブックには出力がありません。ノートブックを実行して保存します。出力が再生成され、ローカルの`.ipynb`ファイルが作成されます +- ノートブックを編集し、更新された`notebook.py`ファイルをプッシュします。差分は、Pythonスクリプトの標準的な差分に他なりません。 +- 更新された`notebook.py`スクリプトをプルし、ブラウザを更新します。入力セルは`notebook.py`の新しい内容に基づいて更新されます。出力はローカルの`.ipynb`ファイルから再読み込みされます。最後に、カーネル変数はそのままなので、新しい出力を得るために変更されたセルのみを実行するオプションがあります。 + +### IDEでのノートブックの編集やリファクタリング + +ノートブックを`.py`ファイルと[ペアリング](docs/paired-notebooks.md)すると、IDEでノートブックの`.py`表現を簡単に編集したりリファクタリングしたりできます。 + +`.py`ノートブックの編集が終わったら、Jupyterでノートブックを _reload_ するだけで、最新の編集内容がそこに反映されます。 + +注：ペアリングされた`.py`ファイルを編集するときは、Jupyterで`.ipynb`ノートブックを閉じておくのがシンプルです。そうする義務はありませんが、そうしないのであれば、ポップアップメッセージを注意深く読む準備が必要です。最後のリロード以降にペアリングされた`.py`ファイルもディスク上で編集されている間にJupyterがノートブックを保存しようとすると、競合が検出され、ノートブックのどのバージョン（メモリ内またはディスク上）が適切かを決定するよう求められます。 + +## その他のリソース + +[ドキュメント](https://jupytext.readthedocs.io)でJupytextについてさらに詳しく読むことができます。 + +Jupytextを初めて使う場合は、[FAQ](docs/faq.md)または[チュートリアル](docs/tutorials.md)から始めるのが良いかもしれません。 + +Jupytextの短い紹介動画もあります。[![](https://img.shields.io/badge/YouTube-JupyterCon%202020-red.svg)](https://www.youtube.com/watch?v=SDYdeVfMh48) \ No newline at end of file From 554fa5c44012dd417d0378715750cab4dd79c647 Mon Sep 17 00:00:00 2001 From: Maki Date: Fri, 14 Jun 2024 23:45:32 +0900 Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=9B=A0=20[chore]=20Update=20.gitignor?= =?UTF-8?q?e=20to=20exclude=20.SourceSageAssets?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added .SourceSageAssets to .gitignore to prevent unnecessary tracking of specific asset files. --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 3cc604b7..a1ed933b 100644 --- a/.gitignore +++ b/.gitignore @@ -39,3 +39,4 @@ node_modules # Ignore jupyter-releaser related stuff .jupyter_releaser_checkout +.SourceSageAssets From 82d0e9e57e43fe5f860bb52793a92cccd4569738 Mon Sep 17 00:00:00 2001 From: Maki Date: Fri, 14 Jun 2024 23:45:37 +0900 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=93=9D=20[docs]=20Update=20internal?= =?UTF-8?q?=20links=20in=20Japanese=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Updated documentation links to use relative paths, enhancing portability and link robustness. - Made changes across several sections to ensure consistency in how resources are referenced within the document. --- docs/README_JA.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/README_JA.md b/docs/README_JA.md index f72c2f90..0afdbf5b 100644 --- a/docs/README_JA.md +++ b/docs/README_JA.md @@ -6,7 +6,7 @@ [![Documentation Status](https://readthedocs.org/projects/jupytext/badge/?version=latest)](https://jupytext.readthedocs.io/en/latest/?badge=latest) [![codecov.io](https://codecov.io/github/mwouts/jupytext/coverage.svg?branch=main)](https://codecov.io/gh/mwouts/jupytext/branch/main) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) -[![GitHub language count](https://img.shields.io/github/languages/count/mwouts/jupytext)](docs/languages.md) +[![GitHub language count](https://img.shields.io/github/languages/count/mwouts/jupytext)](./languages.md) [![Conda Version](https://img.shields.io/conda/vn/conda-forge/jupytext.svg)](https://anaconda.org/conda-forge/jupytext) [![Pypi](https://img.shields.io/pypi/v/jupytext.svg)](https://pypi.python.org/pypi/jupytext) [![pyversions](https://img.shields.io/pypi/pyversions/jupytext.svg)](https://pypi.python.org/pypi/jupytext) @@ -24,7 +24,7 @@ Jupyter Notebookがプレーンテキストドキュメントだったらいい ## テキストノートブック -`py:percent` [フォーマット](docs/formats-scripts.md#the-percent-format)でエンコードされたPythonノートブックは、`.py`拡張子を持ち、以下のようになります。 +`py:percent` [フォーマット](./formats-scripts.md#the-percent-format)でエンコードされたPythonノートブックは、`.py`拡張子を持ち、以下のようになります。 ``` # %% [markdown] @@ -37,9 +37,9 @@ def f(x): ノートブックの入力（とオプションでメタデータ）のみが含まれます。テキストノートブックはバージョン管理に適しています。IDEで編集やリファクタリングも可能です。上記の`.py`ノートブックは通常のPythonファイルです。 -コードを主に含むノートブックには`percent`フォーマットをお勧めします。`percent`フォーマットは、Julia、Python、Rなど多くの[言語](docs/languages.md)で利用可能です。 +コードを主に含むノートブックには`percent`フォーマットをお勧めします。`percent`フォーマットは、Julia、Python、Rなど多くの[言語](./languages.md)で利用可能です。 -ノートブックがドキュメント指向の場合は、[Markdownベースのフォーマット](docs/formats-markdown.md)（`.md`拡張子のテキストノートブック）の方が適切かもしれません。ノートブックの用途に応じて、Jupyter Bookとの相互運用性に優れたMyst Markdownフォーマット、Quarto Markdown、さらにはPandoc Markdownを選ぶのも良いでしょう。 +ノートブックがドキュメント指向の場合は、[Markdownベースのフォーマット](./formats-markdown.md)（`.md`拡張子のテキストノートブック）の方が適切かもしれません。ノートブックの用途に応じて、Jupyter Bookとの相互運用性に優れたMyst Markdownフォーマット、Quarto Markdown、さらにはPandoc Markdownを選ぶのも良いでしょう。 ## インストール @@ -59,7 +59,7 @@ JupyterのPython環境にJupytextをインストールします。以下のど `.py`や`.md`拡張子のテキストノートブックはバージョン管理に適しています。IDEで簡単に編集や作成ができます。Jupyter Labで右クリックするとノートブックとして開いて実行できます。ただし、テキストノートブックにはノートブックの入力のみが保存されるため、ノートブックを閉じるとノートブックの出力は失われます。 -テキストノートブックの便利な代替手段は、[ペアノートブック](docs/paired-notebooks.md)です。これは、`.ipynb`と`.py`のように、同じノートブックを異なるフォーマットで含む2つのファイルのセットです。 +テキストノートブックの便利な代替手段は、[ペアノートブック](./paired-notebooks.md)です。これは、`.ipynb`と`.py`のように、同じノートブックを異なるフォーマットで含む2つのファイルのセットです。 ペアノートブックの`.py`バージョンを編集し、Jupyterで _reload notebook from disk_ を選択することで、編集内容をJupyterに反映させることができます。`.ipynb`ファイルが存在する場合、出力はそこから再読み込みされます。次にJupyterでノートブックを保存すると、`.ipynb`バージョンが更新または再作成されます。 @@ -67,7 +67,7 @@ Jupyter Labでノートブックをペアリングするには、コマンドパ ![](https://github.com/mwouts/jupytext/blob/64b4be818508760116f91bf156342cb4cf724d93/docs/images/pair_commands.png?raw=true) -特定のディレクトリ内のすべてのノートブックをペアリングするには、以下の内容で[設定ファイル](docs/config.md)を作成します。 +特定のディレクトリ内のすべてのノートブックをペアリングするには、以下の内容で[設定ファイル](./config.md)を作成します。 ``` # jupytext.toml ノートブックディレクトリのルートに配置 @@ -76,7 +76,7 @@ formats = "ipynb,py:percent" ## コマンドライン -Jupytextは[コマンドライン](docs/using-cli.md)でも利用可能です。以下のことができます。 +Jupytextは[コマンドライン](./using-cli.md)でも利用可能です。以下のことができます。 - `jupytext --set-formats ipynb,py:percent notebook.ipynb`でノートブックをペアリングする - `jupytext --sync notebook.py`でペアファイルを同期する（入力は最新のペアファイルから読み込まれる） @@ -88,7 +88,7 @@ Jupytextは[コマンドライン](docs/using-cli.md)でも利用可能です。 ### バージョン管理下のノートブック 手順は以下の通りです。 -- Jupyterで`.ipynb`ノートブックを開き、Jupyter Labの _pair_ コマンドまたはグローバルな[設定ファイル](docs/config.md)を使用して、`.py`ノートブックに[ペアリング](docs/paired-notebooks.md)します +- Jupyterで`.ipynb`ノートブックを開き、Jupyter Labの _pair_ コマンドまたはグローバルな[設定ファイル](./config.md)を使用して、`.py`ノートブックに[ペアリング](./paired-notebooks.md)します - ノートブックを保存すると、`.py`ノートブックが作成されます - この`.py`ノートブックをバージョン管理に追加します @@ -107,7 +107,7 @@ Gitを通じたJupyter Notebookでのコラボレーションが、テキスト ### IDEでのノートブックの編集やリファクタリング -ノートブックを`.py`ファイルと[ペアリング](docs/paired-notebooks.md)すると、IDEでノートブックの`.py`表現を簡単に編集したりリファクタリングしたりできます。 +ノートブックを`.py`ファイルと[ペアリング](./paired-notebooks.md)すると、IDEでノートブックの`.py`表現を簡単に編集したりリファクタリングしたりできます。 `.py`ノートブックの編集が終わったら、Jupyterでノートブックを _reload_ するだけで、最新の編集内容がそこに反映されます。 @@ -117,6 +117,6 @@ Gitを通じたJupyter Notebookでのコラボレーションが、テキスト [ドキュメント](https://jupytext.readthedocs.io)でJupytextについてさらに詳しく読むことができます。 -Jupytextを初めて使う場合は、[FAQ](docs/faq.md)または[チュートリアル](docs/tutorials.md)から始めるのが良いかもしれません。 +Jupytextを初めて使う場合は、[FAQ](./faq.md)または[チュートリアル](./tutorials.md)から始めるのが良いかもしれません。 Jupytextの短い紹介動画もあります。[![](https://img.shields.io/badge/YouTube-JupyterCon%202020-red.svg)](https://www.youtube.com/watch?v=SDYdeVfMh48) \ No newline at end of file