Zenn
🌱

技術記事を書く時に必要な「検証環境」の項目について

2024/03/21に公開
Python
VS Code
shell
技術記事
tech

はじめに

新しい技術の紹介を行う上で、その記事がOSやライブラリのどのバーションで実行された結果をもとに書かれたかを読者に共有することはとても重要なことだと考えています。
特にバージョンに依存するエラー踏んでしまった状況を打開するのに必要な情報です。

いままでの書き方

いままでは、下記のような書き方をしていたが、例えばmacOSのバージョンがGUI上でどのボタン遷移で確認できるか初学者には優しくないなとふと思ったしだいです。

  • 検証環境
    • macOS： 13.3.1
    • Python： 3.9.5

これからの書き方

  • Python のライブラリ紹介の例

検証環境

  • コマンドも併記することで、GUI上のどこに遷移したら確認できるかレクチャーする行為を省ける気がしますし、自分も忘れている時があるので、コマンドあると良い。
# 作業前
$ system_profiler SPSoftwareDataType | grep "System Version" # OSのバージョン
System Version: macOS 13.3 (22E252)

$ code --version # VSCodeのバージョン
1.87.2

$ python --version　# Pythonのバージョン
Python 3.10.13

# 作業後
$ pip show pygwalker | grep "Version"
Version: 0.4.7

$ pip show streamlit | grep "Version"
Version: 1.32.2

$ tree
.
├── data
│   └── sales.csv
├── gw_config.json
└── src
    └── streamlit_app.py

その他

システム情報一覧

  • 一部マスク（***********）しています
$ system_profiler SPSoftwareDataType # OSバージョン以外にも
Software:

    System Software Overview:

      System Version: ***********
      Kernel Version: ***********
      Boot Volume: ***********
      Boot Mode: ***********
      Computer Name: ***********
      User Name: ***********
      Secure Virtual Memory: ***********
      System Integrity Protection: ***********
      Time since boot: ***********

Python ライブラリ情報一覧

  • 一部マスク（***********）しています
$ pip show pygwalker
Name: pygwalker
Version: 0.4.7
Summary: pygwalker: Combining Jupyter Notebook with a Tableau-like UI
Home-page: 
Author: 
Author-email: kanaries <support@kanaries.net>
License: 
Location: ***********
Requires: appdirs, arrow, astor, cachetools, duckdb, gw-dsl-parser, ipython, ipywidgets, jinja2, kanaries-track, pandas, psutil, pyarrow, pydantic, pytz, requests, segment-analytics-python, sqlalchemy, sqlglot, typing-extensions
Required-by:

VSCode拡張機能の情報一覧

# 一覧を取得する
$ code --list-extensions --show-versions 

# 個別指定
$ code --list-extensions --show-versions | grep "github.github-vscode-theme"
github.github-vscode-theme@6.3.4

https://qiita.com/yoshi_yast/items/b0170158ed477cbe2476

おわりに

初学者に優しく？しつつ毎回記事書く時にGUI上でバージョン確認どこだっけってならないようにコマンドも併記すると、結果自分にも優しくなります。

Discussion