PythonでMarkdownを扱う -README.mdから実験メモ作成まで-

こんにちは。

現役エンジニアの”はやぶさ”@Cpp_Learningです。README.mdから簡単なメモまで、Markdownで書くことが多いです。またPythonで色んなコードを書いてます。

本記事ではPythonでMarkdownを扱い、README.mdや実験メモを作成する方法を紹介します。

Contents

1 Markdownとは？READMEとは？
2 実践！PythonでMarkdownを扱う
3 実践！PythonとMarkdownでREADME.mdを作成する
- 3.1 設定ファイル -info.json-
- 3.2 PythonでREADME.mdとhtmlファイルを作成
4 実践！Pythonと実験メモを作成する
- 4.1 設定ファイル -penguin_info.json-
- 4.2 Pythonで実験メモ（Markdown）を作成
5 まとめ

Markdownとは？READMEとは？

Markdownについては以下の記事で説明済みなので、本記事では割愛します。

【仕事効率化】Visual Studio Code で Markdown を使いこなす【仕事効率化】Visual Studio Code(VSCode) で Markdown を使い自分用のメモやチートシート・Tips集などのドキュメント作成をキーボード１つで効率的に実施しよう！...

個人的にはMarkdownを使ってシンプルなREADME.mdを書くのが好きです。

【GitHub】シンプルなREADME.mdの書き方 -コピペで使えるテンプレート付き-こんにちは。現役エンジニアの”はやぶさ”@Cpp_Learningです。仕事でもプライベートでもREADME.mdを書く機会が多...

実践！PythonでMarkdownを扱う

PythonでMarkdownを扱う…といっても特に難しいことはありません。

下記 text のようにMarkdownで書いた文字列を *.md で保存するだけです。

text =  '''
# 見出し1
## 見出し2
### 見出し3

**太字**

*斜字*

~~削除します~~

***
線を引く
---

* 箇条書き1
* 箇条書き2
  * 箇条書き2.1
  * 箇条書き2.2
* 箇条書き3
    * 箇条書き3.1

1. 数字付き1
1. 数字付き2

ソースコードも書ける。実行はできない。

【Python】
```python
# コメント
import numpy
import pandas

print('Hello World')
```

【C言語】
```c
// コメント
#include

int main(){
    printf("Hello World")
}
```

'''

file_path = "./test.md"

with open(file_path, 'w') as file:
        file.write(text)

text = '''

# 見出し1

## 見出し2

### 見出し3

**太字**

*斜字*

~~削除します~~

***

線を引く

---

* 箇条書き1

* 箇条書き2

* 箇条書き2.1

* 箇条書き2.2

* 箇条書き3

* 箇条書き3.1

1. 数字付き1

1. 数字付き2

ソースコードも書ける。実行はできない。

【Python】

```python

# コメント

import numpy

import pandas

print('Hello World')

```

【C言語】

```c

// コメント

#include

int main(){

printf("Hello World")

}

```

'''

file_path = "./test.md"

with open(file_path, 'w') as file:

file.write(text)

まぁこれだとPython使うメリットが全くありませんが…

『プログラムの処理結果をMarkdownで書いて *.md で保存できる』と考えれば、色んなことに応用できます。

実践！PythonとMarkdownでREADME.mdを作成する

*.mdをHTMLファイルに変換して展開したいケースもあるので、以下のコマンドで事前にライブラリをインストールしておきます。

pip install markdown

以降からコード書いていきます。

設定ファイル -info.json-

README.md テンプレートを参考に、”Name”や”Summary”などの情報を書いた設定ファイルを作成します。

{
    "Name": "Physics_Sim_Py",
    "Summary": "Physics_Sim_Py is a tutorial of physics simulations with Python.",
    "Demo": "You can learn how to making cute physics simulations (looks retro game).",
    "Image_path": "./img/game.gif",
    "Features": "Please read [document](https://cpp-learning.com/readme/)."
}

{

"Name": "Physics_Sim_Py",

"Summary": "Physics_Sim_Py is a tutorial of physics simulations with Python.",

"Demo": "You can learn how to making cute physics simulations (looks retro game).",

"Image_path": "./img/game.gif",

"Features": "Please read [document](https://cpp-learning.com/readme/)."

}

この設定ファイルを本記事では info.json と名付けます。

作成したいREADMEに応じて、”Image_path”などを変更して下さい

PythonでREADME.mdとhtmlファイルを作成

README.md テンプレートの中でも頻繁に変更しない箇所なら、下記 TEMPLE のようにコードにべた書きするのもOKです。

import markdown
import json

TEMPLE = '''
# Author

* Hayabusa
* R&D Center
* Twitter : https://twitter.com/Cpp_Learning

# License

[MIT license](https://en.wikipedia.org/wiki/MIT_License).

Enjoy programming!

Thank you!
'''

def create_text(info: dict, temple : str='Thank you!') -> str:
    '''create markdown text from dict'''

    # get values of dict
    Name = info.get('Name', 'No name')
    Summary = info.get('Summary', 'unknown')
    Demo = info.get('Demo', 'unknown')
    Image_path = info.get('Image_path', 'No image')
    Features = info.get('Features', 'unknown')
    Note = info.get('Note', 'Nothing')

    # template
    nl =  '\n\n'
    # temple = 'Thank you!'
    
    # markdown text
    text = '# ' + Name + nl + \
            Summary + nl + \
            '# DEMO' + nl + \
            Demo + nl + \
            '![](' + Image_path + ')' + nl + \
            '# Features' + nl + \
            Features + nl + \
            '# Note' + nl + \
            Note + nl + \
            temple

    return text

def save_text(text: str, file_name: str="report"):
    '''save text with markdown and HTML file'''
    # markdown to html
    md = markdown.Markdown()
    html = md.convert(text)
    # print(html)

    # file name
    md_file_name = file_name + ".md"
    html_file_name = file_name + ".html"
    
    # path
    md_file_path = "./" + md_file_name
    html_file_path = "./" + html_file_name

    # save markdown
    with open(md_file_path, 'w') as file:
        file.write(text)

    # save html
    with open(html_file_path, 'w') as file:
        file.write(html)

if __name__ == '__main__':
    # load json
    file_path = './info.json'
    with open(file_path, "r") as file:
        info_dict = json.load(file)
        '''
        info_dict = {
            "Name": "Physics_Sim_Py",
            "Summary": "Physics_Sim_Py is a tutorial of physics simulations with Python.",
            "Demo": "You can learn how to making cute physics simulations (looks retro game).",
            "Image_path": "./img/game.gif",
            "Features": "Please read [document](https://cpp-learning.com/readme/)."
        }
        '''

    # create markdown text from dict
    text = create_text(info=info_dict, temple=TEMPLE)

    # save text with markdown and HTML file
    save_text(text=text, file_name="README")

import markdown

import json

TEMPLE = '''

# Author

* Hayabusa

* R&D Center

* Twitter : https://twitter.com/Cpp_Learning

# License

[MIT license](https://en.wikipedia.org/wiki/MIT_License).

Enjoy programming!

Thank you!

'''

def create_text(info: dict, temple : str='Thank you!') -> str:

'''create markdown text from dict'''

# get values of dict

Name = info.get('Name', 'No name')

Summary = info.get('Summary', 'unknown')

Demo = info.get('Demo', 'unknown')

Image_path = info.get('Image_path', 'No image')

Features = info.get('Features', 'unknown')

Note = info.get('Note', 'Nothing')

# template

nl = '\n\n'

# temple = 'Thank you!'

# markdown text

text = '# ' + Name + nl + \

Summary + nl + \

'# DEMO' + nl + \

Demo + nl + \

'![](' + Image_path + ')' + nl + \

'# Features' + nl + \

Features + nl + \

'# Note' + nl + \

Note + nl + \

temple

return text

def save_text(text: str, file_name: str="report"):

'''save text with markdown and HTML file'''

# markdown to html

md = markdown.Markdown()

html = md.convert(text)

# print(html)

# file name

md_file_name = file_name + ".md"

html_file_name = file_name + ".html"

# path

md_file_path = "./" + md_file_name

html_file_path = "./" + html_file_name

# save markdown

with open(md_file_path, 'w') as file:

file.write(text)

# save html

with open(html_file_path, 'w') as file:

file.write(html)

if __name__ == '__main__':

# load json

file_path = './info.json'

with open(file_path, "r") as file:

info_dict = json.load(file)

'''

info_dict = {

"Name": "Physics_Sim_Py",

"Summary": "Physics_Sim_Py is a tutorial of physics simulations with Python.",

"Demo": "You can learn how to making cute physics simulations (looks retro game).",

"Image_path": "./img/game.gif",

"Features": "Please read [document](https://cpp-learning.com/readme/)."

}

'''

# create markdown text from dict

text = create_text(info=info_dict, temple=TEMPLE)

# save text with markdown and HTML file

save_text(text=text, file_name="README")

このコードを実行すれば、 info.json や TEMPLE に書いた情報を参照して、README.md と README.html を作成できます。

README.html

Pythonで作成した README.html を公開するので、自由に閲覧してください。htmlファイルなら、専用エディタ不要（ブラウザのみ）で情報共有できるのが嬉しいですね。

辞書から情報を参照するときは get を活用し、指定したkeyが存在しない場合にデフォルト値を返すようにしています。今回の場合、info.json に”Note”の情報が無いので、デフォルト値の”Nothing”をREADME.mdに書いています。

実践！Pythonと実験メモを作成する

続いてPythonで実験メモ（*.md）を作成します。今回は palmerpenguins（ペンギンデータセット）を使いたいので、以下のコマンドでインストールします。

pip install palmerpenguins

以降からコード書いていきます。

設定ファイル -penguin_info.json-

先ほどと同様に設定ファイルを作成します。今回は penguin_info.json と名付けます。

{
    "Name": "Visualize palmerpenguins dataset",
    "Summary": "Flipper Length [mm] vs. Body Mass [g]",
    "Image_path": "./penguins.png",
    "Note": "[palmerpenguins|GitHub](https://github.com/allisonhorst/palmerpenguins)"
}

{

"Name": "Visualize palmerpenguins dataset",

"Summary": "Flipper Length [mm] vs. Body Mass [g]",

"Image_path": "./penguins.png",

"Note": "[palmerpenguins|GitHub](https://github.com/allisonhorst/palmerpenguins)"

}

Pythonで実験メモ（Markdown）を作成

pandasでデータを読込んで、基本統計量の演算など任意の処理をしたり、matplotlibでデータを可視化した画像を保存します。

その処理結果や可視化画像をMarkdownで書き起こして、実験メモ（今回は penguin-visualization.md と名付ける）を作成するところまでを、Pythonコードのみで実施します。

import pandas as pd
from matplotlib import pyplot as plt
import json
# import markdown
from palmerpenguins import load_penguins

def create_text(info: dict, table: dict, temple : str='END') -> str:
    '''create markdown text from dict'''

    # get values of dict
    Name = info.get('Name', 'No name')
    Summary = info.get('Summary', 'unknown')
    Image_path = info.get('Image_path', 'No image')
    Note = info.get('Note', 'Nothing')

    # template
    nl =  '\n\n'
    # temple = 'Thank you!'
    
    # markdown text
    text = '# ' + Name + nl + \
            Summary + nl + \
            '![](' + Image_path + ')' + nl + \
            table + nl + \
            '# Note' + nl + \
            Note + nl + \
            temple

    return text

def save_text(text: str, file_path: str="./memo.md"):
    '''save text with markdown and HTML file'''
    # save markdown
    with open(file_path, 'w') as file:
        file.write(text)

def create_figure(x, y, xlabel: str, ylabel: str, fig_title: str, file_path: str):
    '''create figure and save png'''
    # 図のサイズ設定
    fig = plt.figure(figsize=(8,4), dpi=100)
    ax = fig.add_subplot(1,1,1)

    # プロット設定
    ax.scatter(x, y, s=100, alpha=0.5, linewidths='2', c='#55C500', edgecolors='g')

    # 目盛りの文字サイズ設定
    ax.xaxis.set_tick_params(direction="out", labelsize=16, width=3, pad=10)
    ax.yaxis.set_tick_params(direction="out", labelsize=16, width=3, pad=10)

    # 軸のラベル設定
    ax.set_xlabel(xlabel, fontsize=16, labelpad=10, weight='bold')
    ax.set_ylabel(ylabel, color='tab:green', fontsize=16, labelpad=10, weight='bold')

    # グラフのタイトル
    ax.set_title(fig_title, fontsize=16, fontweight=16, weight='bold')

    # グリッド設定
    ax.grid(True);

    # pngで保存
    plt.savefig(file_path, bbox_inches='tight')


if __name__ == '__main__':
    # json取得
    file_path = './penguin_info.json'
    file = open(file_path, 'r')
    info_dict = json.load(file)
    
    # ペンギン データセット取得
    df_penguins = load_penguins()
    print(df_penguins.head())
    
    # 可視化したいデータ x, y
    df_Chinstrap = df_penguins[df_penguins["species"]=="Chinstrap"]
    y = df_Chinstrap["body_mass_g"]
    x = df_Chinstrap["flipper_length_mm"]

    # 軸のラベル設定
    xlabel = "Flipper Length [mm]"
    ylabel = "Body Mass [g]"
    fig_title = "Chinstrap"
    img_path = "./penguins.png"

    # グラフをpngで保存
    create_figure(x, y, xlabel, ylabel, fig_title, img_path)

    # 表をmarkdownで出力
    df_describe = df_Chinstrap.describe()
    table = df_describe.to_markdown()
    # table = df_Chinstrap.to_markdown()
    print(table)

    # create markdown text from dict
    text = create_text(info=info_dict, table=table)

    # save text with markdown file
    save_text(text=text, file_path="./penguin-visualization.md")

import pandas as pd

from matplotlib import pyplot as plt

import json

# import markdown

from palmerpenguins import load_penguins

def create_text(info: dict, table: dict, temple : str='END') -> str:

'''create markdown text from dict'''

# get values of dict

Name = info.get('Name', 'No name')

Summary = info.get('Summary', 'unknown')

Image_path = info.get('Image_path', 'No image')

Note = info.get('Note', 'Nothing')

# template

nl = '\n\n'

# temple = 'Thank you!'

# markdown text

text = '# ' + Name + nl + \

Summary + nl + \

'![](' + Image_path + ')' + nl + \

table + nl + \

'# Note' + nl + \

Note + nl + \

temple

return text

def save_text(text: str, file_path: str="./memo.md"):

'''save text with markdown and HTML file'''

# save markdown

with open(file_path, 'w') as file:

file.write(text)

def create_figure(x, y, xlabel: str, ylabel: str, fig_title: str, file_path: str):

'''create figure and save png'''

# 図のサイズ設定

fig = plt.figure(figsize=(8,4), dpi=100)

ax = fig.add_subplot(1,1,1)

# プロット設定

ax.scatter(x, y, s=100, alpha=0.5, linewidths='2', c='#55C500', edgecolors='g')

# 目盛りの文字サイズ設定

ax.xaxis.set_tick_params(direction="out", labelsize=16, width=3, pad=10)

ax.yaxis.set_tick_params(direction="out", labelsize=16, width=3, pad=10)

# 軸のラベル設定

ax.set_xlabel(xlabel, fontsize=16, labelpad=10, weight='bold')

ax.set_ylabel(ylabel, color='tab:green', fontsize=16, labelpad=10, weight='bold')

# グラフのタイトル

ax.set_title(fig_title, fontsize=16, fontweight=16, weight='bold')

# グリッド設定

ax.grid(True);

# pngで保存

plt.savefig(file_path, bbox_inches='tight')

if __name__ == '__main__':

# json取得

file_path = './penguin_info.json'

file = open(file_path, 'r')

info_dict = json.load(file)

# ペンギンデータセット取得

df_penguins = load_penguins()

print(df_penguins.head())

# 可視化したいデータ x, y

df_Chinstrap = df_penguins[df_penguins["species"]=="Chinstrap"]

y = df_Chinstrap["body_mass_g"]

x = df_Chinstrap["flipper_length_mm"]

# 軸のラベル設定

xlabel = "Flipper Length [mm]"

ylabel = "Body Mass [g]"

fig_title = "Chinstrap"

img_path = "./penguins.png"

# グラフをpngで保存

create_figure(x, y, xlabel, ylabel, fig_title, img_path)

# 表をmarkdownで出力

df_describe = df_Chinstrap.describe()

table = df_describe.to_markdown()

# table = df_Chinstrap.to_markdown()

print(table)

# create markdown text from dict

text = create_text(info=info_dict, table=table)

# save text with markdown file

save_text(text=text, file_path="./penguin-visualization.md")

ペンギンデータセットを可視化

設定ファイルの情報・上図・基本統計量を算出した表などをMarkdownで書き起こして作成した実験メモが以下です。

penguin-visualization

上記の実験メモですが、README.html 同様にライブラリでMarkdown ⇒ html変換したところ、表が上手く変換できなかったので、エディタ（VSCode）を活用して手動で変換させました。

pandas.DataFrame.to_markdownを使って、データフレームをMarkdownに変換

まとめ

PythonでMarkdownを扱う方法を紹介しました。

また応用として Pythonコードで、README.mdや実験メモを作成する方法も紹介しました。

プログラミングの面白さや便利さが少しでも伝わると嬉しいです。

はやぶさ

役立つアプリや便利なライブラリを自作したり、使っている人は情報共有して頂けると嬉しいです。よろしくお願いします。

最後に『Pythonプログラミングを勉強したい！』という人のために、以下の記事を紹介します。

『ゼロから学ぶPythonプログラミング』の感想文こんにちは。現役エンジニアの”はやぶさ”@Cpp_Learningです。今回は『ゼロから学ぶPythonプログラミング』という本...

PythonでMarkdownを扱う -README.mdから実験メモ作成まで-

Markdownとは？READMEとは？

実践！PythonでMarkdownを扱う

実践！PythonとMarkdownでREADME.mdを作成する

設定ファイル -info.json-

PythonでREADME.mdとhtmlファイルを作成

実践！Pythonと実験メモを作成する

設定ファイル -penguin_info.json-

Pythonで実験メモ（Markdown）を作成

まとめ

プライム感謝祭セールを完全攻略！事前準備やお得キャンペーンを徹底解説

【アマゾンプライムデー2023年】完全攻略！事前準備やお得キャンペーンを徹底解説

【2023年版】アマゾンプライム会員のメリット・デメリットを紹介！

Golang × WebAssembly（wasm）入門

【Python】最適化フレームワークのCodable Model Optimizerで回帰モデルのパラメータ調整を自動化する

【GitHub】シンプルなREADME.mdの書き方 -コピペで使えるテンプレート付き-

【Pyxel】Pythonでレトロゲームを作ろう！総集編 -まるっと1週間でゲーム開発入門-

【仕事効率化】Visual Studio Code で Markdown を使いこなす

【深層学習入門】画像処理の基礎(画素操作)からCNN設計まで

【Pyxel】Pythonでレトロゲームを作ろう！ Day 1 -画像の扱い方-

Markdownとは？READMEとは？

実践！PythonでMarkdownを扱う

実践！PythonとMarkdownでREADME.mdを作成する

設定ファイル -info.json-

PythonでREADME.mdとhtmlファイルを作成

実践！Pythonと実験メモを作成する

設定ファイル -penguin_info.json-

Pythonで実験メモ（Markdown）を作成

まとめ

プライム感謝祭セールを完全攻略！事前準備やお得キャンペーンを徹底解説

【アマゾンプライムデー2023年】完全攻略！事前準備やお得キャンペーンを徹底解説

【2023年版】アマゾンプライム会員のメリット・デメリットを紹介！

Golang × WebAssembly（wasm）入門

【Python】最適化フレームワークのCodable Model Optimizerで回帰モデルのパラメータ調整を自動化する

【GitHub】シンプルなREADME.mdの書き方 -コピペで使えるテンプレート付き-

【Pyxel】Pythonでレトロゲームを作ろう！ 総集編 -まるっと1週間でゲーム開発入門-

【仕事効率化】Visual Studio Code で Markdown を使いこなす

【深層学習入門】画像処理の基礎(画素操作)からCNN設計まで

【Pyxel】Pythonでレトロゲームを作ろう！ Day 1 -画像の扱い方-

【Pyxel】Pythonでレトロゲームを作ろう！総集編 -まるっと1週間でゲーム開発入門-