rabbit-slide-znz-docs-r-l-o-ja-202406 2024.6.13.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ec77d5bf3f3ad9ec498dfa6063933df0363c0ea8d270a0072e7f89ab50dee726
+  data.tar.gz: '0183634f023d18f04c51389e44e72ee699c94003e4c3102af4e0ec847a560949'
+SHA512:
+  metadata.gz: acc45aef608d0a3b55f6d3b4af5b5269d6b8923ec976ae69e0110f962e7def2ef3f8ade0cea52636ab7e5e9aa562427285696fc9d3ec545f63ffdd20bd24049b
+  data.tar.gz: 4bca7904fa2c000397f920b58f8a0d8432f59d34f3e53b880a3ff63fe295753c9e757408df469a12ea471c1335dc0663fab7695d59d7c3cdf8808473fc02faa4

data/.rabbit

@@ -0,0 +1,2 @@
+--size 800,600
+docs-ruby-lang-org-ja.md

data/README.md

@@ -0,0 +1,23 @@
+# docs.ruby-lang.org/ja/ の生成方法を変えた
+
+[【大阪オフライン開催】RubyKaigi 2024 KaigiEffect発表会](https://kyobashirb.connpass.com/event/320687/) の発表資料です。
+
+## 作者向け
+
+### 表示
+
+    rake
+
+### 公開
+
+    rake publish
+
+## 閲覧者向け
+
+### インストール
+
+    gem install rabbit-slide-znz-docs-r-l-o-ja-202406
+
+### 表示
+
+    rabbit rabbit-slide-znz-docs-r-l-o-ja-202406.gem

data/README.md~

@@ -0,0 +1,24 @@
+# docs.ruby-lang.org/ja/ の生成方法を変えた
+
+TODO: スライドの説明
+
+## 作者向け
+
+### 表示
+
+    rake
+
+### 公開
+
+    rake publish
+
+## 閲覧者向け
+
+### インストール
+
+    gem install rabbit-slide-znz-docs-r-l-o-ja-202406
+
+### 表示
+
+    rabbit rabbit-slide-znz-docs-r-l-o-ja-202406.gem
+

data/Rakefile

@@ -0,0 +1,17 @@
+require "rabbit/task/slide"
+
+# Edit ./config.yaml to customize meta data
+
+spec = nil
+Rabbit::Task::Slide.new do |task|
+  spec = task.spec
+  # spec.files += Dir.glob("doc/**/*.*")
+  # spec.files -= Dir.glob("private/**/*.*")
+  # spec.add_runtime_dependency("rabbit-theme-YOUR-THEME")
+end
+
+desc "Tag #{spec.version}"
+task :tag do
+  sh("git", "tag", "-a", spec.version.to_s, "-m", "Publish #{spec.version}")
+  sh("git", "push", "--tags")
+end

data/config.yaml

@@ -0,0 +1,24 @@
+---
+id: docs-r-l-o-ja-202406
+base_name: docs-ruby-lang-org-ja
+tags:
+- ruby
+presentation_date: '2024-06-13'
+presentation_start_time:
+presentation_end_time:
+version: 2024.6.13.0
+licenses: []
+slideshare_id: docs-ruby-lang-org-ja-github-actions
+speaker_deck_id: nosheng-cheng-fang-fa-wobian-eta
+vimeo_id:
+youtube_id:
+width: 800
+height: 600
+source_code_uri:
+author:
+  markup_language: :markdown
+  name: Kazuhiro NISHIYAMA
+  email: zn@mbf.nifty.com
+  rubygems_user: znz
+  slideshare_user: znzjp
+  speaker_deck_user: znz

data/docs-ruby-lang-org-ja.md

@@ -0,0 +1,141 @@
+# docs.ruby-lang.org/ja/ の生成方法を変えた
+
+author
+:   Kazuhiro NISHIYAMA
+
+content-source
+:   【大阪オフライン開催】RubyKaigi 2024 KaigiEffect発表会
+
+date
+:   2024-06-13
+
+allotted-time
+:   15m
+
+theme
+:   lightning-simple
+
+# self.introduction
+
+- 西山 和広
+- Ruby のコミッター
+- github など: `@znz`
+- 株式会社Ruby開発 www.ruby-dev.jp
+
+# 前の方法
+
+- `docs.ruby-lang.org` で生成
+- `bc-setup-all` で `bitclust` の `db-*` を生成
+- `bc-static-all` で static html を生成 (`/ja/バージョン/` の内容)
+- `update-rurema-index` で `rurema-search` のインデックスを更新 (`/ja/search/` の内容)
+
+# 問題発生
+
+- パターンマッチのドキュメントを ruby/ruby の rdoc を翻訳する形で追加 <https://github.com/rurema/doctree/pull/2773>
+  のマージで問題発生
+- CI はサポートバージョンでしか動いていなかった
+
+```
+% curl -s 'https://cache.ruby-lang.org/pub/misc/ci_versions/cruby.json' | jq -c '. + []'
+["3.1","3.2","3.3","head"]
+```
+
+# docs の ruby
+
+- Debian GNU/Linux 11 (bullseye) の `/usr/bin/ruby` だと
+  `ruby 2.7.4p191 (2021-07-07 revision a21a3b7d23) [x86_64-linux-gnu]`
+- <https://snapcraft.io/ruby> の最新安定版を使っていたこともあったが
+  `rurema-search` との兼ね合いで `/usr/bin/ruby` に戻していた
+
+# HTML 生成の Docker 化
+
+- 生成された db と html を入れても `.git` は 140M ぐらい
+- [GitHub のリポジトリサイズ制限](https://docs.github.com/ja/repositories/working-with-files/managing-large-files/about-large-files-on-github#repository-size-limits)
+  > リポジトリは小さく保ち、理想としては 1GB 未満、および 5GB 未満にすることを強くお勧めします。
+- 生成したファイルもリポジトリ管理に
+
+# rurema-search の Docker 化
+
+- rurema-search のインデックス作成も Docker 化
+- インデックスはバイナリで git 管理には向かなさそう
+- かつ毎回再生成すれば良さそう
+- リポジトリ管理にはせず
+
+# 古いドキュメントの保存
+
+- HTML ファイルは `ja/1.8.7` から残っていた
+- `https://github.com/rurema/generated-documents` に保存
+- `db-*` は EC2 を今の docs-2020 に移行したときに残していなかった
+- `db-2.4.0` 以降のみ現存
+- rurema-search には `db-*` が必要だったが 2.3 以前はないまま
+- <https://docs.ruby-lang.org/ja/search/> は現状維持
+
+# GitHub Actions で生成
+
+- `github.com/ruby` ではなく `github.com/rurema` に作成
+- 権限がなくて S3 へ置けない
+- リポジトリに置くことにした
+- 更新は [生成して pull request を作成して自動マージする](https://github.com/rurema/generated-documents/blob/902da064105c1949907204d4bb5ca0ea40c83e17/.github/workflows/generate.yml) workflow
+
+# docs 側の更新方法変更
+
+- pull してきて反映
+- `bc-setup-all` で `rurema/generated-documents` をとってきて `db-*` の symlink 作成
+- `bc-static-all` は static html を `rsync` で反映
+- `update-rurema-index` は今まで通り
+
+# 今後の予定
+
+- `rurema/generated-documents` の生成済ファイルは埋め込まれているタグなどの関係で docs.ruby-lang.org 専用 → うまく分離したい
+- `docs.ruby-lang.org` の環境軽量化
+  - HTML 生成部分は完了
+  - `rurema-search` は生成されるインデックスだけで 600M 越え (heroku の slug の 500M 制限超過) で静的ファイルのホスティング + Heroku への移行は無理そう
+- <https://github.com/ruby/docs.ruby-lang.org>
+  にある ansible の playbook も現状と合わないので EC2 インスタンス作り直し?
+
+# 残作業
+
+- bitclust への型付けをしつつコードリーディングの続き
+- kramdown への型付け (まだなければ)
+- 開発環境の devcontainer 化 (bitclust 開発者向けと doctree 執筆者向け)
+- bitclust の markdown 対応
+
+# rurema の markdown 対応
+
+- bitclust に markdown 対応機能追加
+- markdown 移行前に doctree の pull request 一掃
+- doctree で markdown に一部書き換え
+- doctree の書き換えでわかった bitclust で markdown 対応の問題点修正
+- rurema-search の markdown 対応
+
+# rurema の markdown 対応
+
+- doctree で全面的に markdown 対応
+- doctree の RDベース記法のドキュメント削除
+- bitclust から RD 対応を削除
+
+# その他のやりたいこと
+
+- irb でのドキュメント表示対応
+- ドキュメント内部での ruby.wasm での実行対応
+- ドキュメント執筆補助ツール (bitclust の tools) の再整備
+
+# docs.ruby-lang.org関連
+
+- (済) rdoc 生成のコンテナ化
+- 脆弱性のある古い js の対処(?) (古い jquery などが残っているかどうかなどの確認から)
+- (済) ja html 生成のコンテナ化
+- GA の削除? (共通 js ファイルにして docs.ruby-lang.org 以外だと空ファイルとかできると良さそう?)
+- (済) 更新しない古いバージョンをアーカイブファイルでも保存・配布
+
+# docs.ruby-lang.org関連
+
+- (済) 新しいバージョンも rurema-search で必要ならアーカイブでも配布
+- 古いバージョンの `db-*` の再生成
+- HTML 配信元を EC2 から S3 バックエンドか何かに移行(?)
+- (途中まで済) rurema-search のコンテナ化かサーバーレス化か何か
+
+# 直近
+
+- (済) rurema-search で master が 3.4 のようにバージョンで出てきてリンク切れになる問題の対策
+- <https://docs.ruby-lang.org/ja/> と <https://docs.ruby-lang.org/en/> のサポート終了バージョンの更新

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: rabbit-slide-znz-docs-r-l-o-ja-202406
+version: !ruby/object:Gem::Version
+  version: 2024.6.13.0
+platform: ruby
+authors:
+- Kazuhiro NISHIYAMA
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-06-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rabbit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.2
+description: "[【大阪オフライン開催】RubyKaigi 2024 KaigiEffect発表会](https://kyobashirb.connpass.com/event/320687/)
+  の発表資料です。"
+email:
+- zn@mbf.nifty.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rabbit"
+- README.md
+- README.md~
+- Rakefile
+- config.yaml
+- docs-ruby-lang-org-ja.md
+- pdf/docs-r-l-o-ja-202406-docs-ruby-lang-org-ja.pdf
+homepage: https://slide.rabbit-shocker.org/authors/znz/docs-r-l-o-ja-202406/
+licenses: []
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: docs.ruby-lang.org/ja/ の生成方法を変えた
+test_files: []