Sphinx で textlint を利用するためのメモ

この資料は Sphinx の reStructuredText で textlint を利用するためにやる事のメモです。

なぜ Sphinx なのか

• Sphinx 開発者が知り合いだから
• reStructuredText に慣れているから
• オンラインドキュメントでは Sphinx が優れていると思うから
• Meilisearch を利用して全文検索を実現可能にしたから

なぜ textlint なのか

• 複数人でドキュメントを書く際に気軽にしたい
• ルールを統一したい

Sphinx を使って、textlint を採用している例

ドキュメントの継続的な開発方法 | IIJ Engineers Blog

これを書かれた人が作られたライブラリがもうメンテされていない。

• jimo1001/textlint-plugin-rst: reStructuredText support for textlint
• jimo1001/docutils-ast-writer: AST Writer for docutils

辛い。

フォークした

会社でメンテすることにした。メンテな募集。興味ある人は Twitter でご連絡を。

shiguredo/textlint-plugin-rst: reStructuredText support for textlint

• esbuild でビルドするようにした
• TypeScript 化した
• Prettier 導入した
• バッファを増やした

shiguredo/docutils-ast-writer: AST Writer for docutils

• Python 3.10 以降向けに変更した

html ではだめなのか

• わざわざ生成された HTML を解析するのはあほくさい
• HTML 解析は遅すぎる 15 分以上かかる

動作するようになった

利用方法

git 経由で docutils-ast-writer をインストールする

$ pip install -e git+https://github.com/shiguredo/docutils-ast-writer@shiguredo#egg=docutils-ast-writer

git 経由で textlint-plugin-rst をインストールする

  "scripts": {
    "lint": "npx textlint --plugin rst source/*rst"
  },
  "devDependencies": {
    "textlint-plugin-rst": "git+https://github.com/shiguredo/textlint-plugin-rst#shiguredo",

実行

$ npm run lint

課題

• rst の label まで置き換え対象になってしまっている
• `` リテラルが使われていると解析結果がおかしくなる
  • 対応済み
• URL が置き換え対象になってしまってる