やってみる

アウトプットすべく己を導くためのブログ。その試行錯誤すらたれ流す。

📌 ？
トップ > ワークフロー > README自動作成できないか考えてみた

README自動作成できないか考えてみた

ワークフロー

　難しそう。

READMEの項目

  • languages (transrate, link)
  • badge
  • created/published (<time>, copyright year)
  • name
  • description
  • image
  • demo
  • feature
  • requirement
  • installation
  • usage
  • note
  • author
    • name
    • link
  • license
    • logo
    • url
    • sentence
    • SPDX license expression
    • license file link
    • copyright

languages (transrate, link)

  • 任意の自然言語における翻訳文を用意する
  • 翻訳READMEへのリンクを用意する
  • 国コード
  • 国旗画像
  • transコマンドによる自動翻訳
    • <code>内は翻訳しない

翻訳

　特に翻訳が大変。英語のREADMEさえ用意しておけば、あとは環境に応じてブラウザが自動翻訳してくれるかもしれない。最悪はそれでもかまわない。

　でも、英語のREADMEを作るとき、日本語から翻訳せねばならない。私は英語がわからないから。

　日本語で書いたMarkdownテキストをGoogle翻訳して英語にするとき、以下のような問題がある。

  • 翻訳する箇所の選択
    • 英語のままであってほしい箇所もある
  • 翻訳サイトを開いて翻訳操作が必要
  • MarkdownテキストをGoogle翻訳にかけるとメタ文字の前後に不要なスペースが挿入されてしまう
    • スペース削除せねばならない

　翻訳のせいで非常に手間がかかる。そしてこの翻訳こそ、最も対応が難しい。翻訳処理を自作しているわけではないため、Google翻訳システムの出力結果に依存してしまうのが難点。非現実的。

コードとの整合性

　実際のソースコードとREADMEの整合性を保ちたい。だがコード解析までせねばならない。非現実的。

　そもそもそのコードをどうやって自然言語に翻訳するというのか。それができるなら自然言語からプログラミング言語へ変換してプログラミング自体を自動化したほうがいい。AIでできるらしいが、いつ庶民の元で無料で簡単に実現できるのか。

　「アレやって」と言っただけでやってくれるのが理想。「アレ」を定義すれば今でも不可能ではない。だが代名詞であるように何を指すかは状況で変わる。自分に都合よく忖度してくれるAIでなければならない。そんな自分こそアレだと思う。

badge

　環境のバージョンとかテストクリアなどの状態を示す。

created/published (<time>, copyright year)

　作成日時（公開日時）。copyright文言と一致させたい。

name

　ソフトウェアの代表名。リポジトリ名と同じなのが好ましい。

description

　ソフトウェアの説明文。一文で表す。GitHubリポジトリのメタデータdescriptionと一致させたい。

image

　ソフトウェアの象徴画像。どうせならソーシャル・プレビューと共用にしたい。

demo

　CLIならasciinema+svg-termを使いたい。元データであるjsonファイルを簡単に編集できるツールが欲しい。

feature

　ソフトウェアの特徴。他とは差別化されたところ。

requirement

　必須環境。

installation

　必須環境と自身のインストール方法。

usage

　ソフトウェアの使い方。ソフトウェア自体のアップデートと連動すべき。ただし細かいことは別ファイルにまかせてREADMEでは最小限の記載にするほうがいいかも？

note

　注意点。

author

　著者。名前と連絡先。連絡にはWEBサービスを使う。WEBサービスのアイコン画像・名前・URL・著者のアカウント名。

  • name
  • link
Author name. [![service1][service1_img]][service1] [![service2][service2_img]][service2]

[service1_img]:http:// "title"
[service2_img]:http:// "title"
[service1]:http://
[service2]:http://

license

  • logo
  • url
  • sentence
  • SPDX license expression
  • license file link
  • copyright

　色々と面倒が多そう。

  • 各ライセンスサイトから画像をかき集めねばならない
  • 決めねばならない
    • ライセンスは？
    • 表示名は？ SPDXのフルネーム？ それとも公式名？ git名？ それっぽい適当？ あるいはSPDX_ID？
    • 一文は？「このソフトウェアは????ライセンスである」
    • 画像形式は？ SVG/PNG
    • 表示サイズは？
    • ファイルサイズは？
    • 配置場所は？　直リン？　リポジトリ内のどこか？
    • URLは？ SPDX？ 各ライセンスの公式？ 両方？
    • コピーライト文言は？　©,(c),(C),Copyright (C),© {発行年} {著者名}...
  • マルチライセンスのときはどうするの？
    • 必要なファイルは？
      • LICENSE.md, LICENSE-{ID}
    • ライセンスの検出は？: licensee
    • LICENSE.md
      • 一文は？「このソフトウェアはAAAA OR BBBBライセンスである。いずれかを選択すること。」
      • 標準ライセンスヘッダを適用したライセンスの分だけ複数書く
      • SPDX license expressionを示す
        • OR, AND等

所感

　これは厳しい。README.mdファイルだけでこれらを適切に編集するのは不可能だろう。

　コードとの整合性は諦めるとして、一番どうにかしたい翻訳も難しそう。

　それぞれの項目を個別のツールで作ることになってしまいそう。

  • social-preview画像が設定されていたら![]()で挿入してほしい
  • asciinemaのjsonファイル編集ツールが欲しい asciinema-edit
  • asciinemaのjson→svg-termで出力したSVGを![]()で挿入してほしい
  • nameはリポジトリ名をそのままセットしたい
  • descriptionはgithubのリポジトリ生成時にWebAPIで引数としてセットしたい
  • requirementはOSなど他プロジェクト間で共通するテンプレートを用意してもいいかも？
    • マシン名やOS名などを取得するコマンドを使えば自動化できる？
  • feature, installation, usage, noteはプロジェクト間で独自になる。自動化不能
  • authorはgithubのユーザごとにテンプレを作って挿入すればいいか？
  • licenseはlicenseeで検出したライセンスIDに応じて適切な形式をセットしたい
  • 翻訳はtransコマンドでできるが問題多数のため不可能
    • READMEのどこに挿入するか
      • 英文READMEをコピーして丸ごと翻訳すればいい？
    • 英語のままにしたい箇所が指定できない
      • 特定の用語、<code>内、メタ文字等

　README自体を半自動化するツールもあるようだ。

　これらのツール、ことごとくNode.js製だな。

対象環境

$ uname -a
Linux raspberrypi 4.19.75-v7l+ #1270 SMP Tue Sep 24 18:51:41 BST 2019 armv7l GNU/Linux