Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Redo "内部リンクを相対リンクで生成する機能 with settings.USE_RELATIVE_LINK = True" #81

Merged
merged 3 commits into from
Jun 11, 2024

Conversation

akinomyoga
Copy link
Member

@akinomyoga akinomyoga commented Jun 30, 2022

#80 で一旦 revert された #78 をやり直し。

cpprefjp/site#917 (comment) で言及されたものです。これも複数のリポジトリに変更があります。cpprefjp/site#977 のデモとして御覧頂いた https://akinomyoga.github.io/cpprefjp-site/ はこの PR の実証も兼ねていました (従来だとそもそも cpprefjp はサイトのトップレベル以外に配置できなかったことに注意)。取り敢えずのところ私的に一通り気になるところは対応しました。

背景

現状では site_generator で生成されるコンテンツはトップレベル / に置かれるという想定でリンクが生成されています。このためローカルで閲覧しようとすると毎回新しいWebサーバーを立ち上げる必要が出てきます (特にリモートのマシン上で変換しているとファイヤーウォールやSELinuxやプロキシなどの設定もしなければならずとても面倒)。

内部のリンクを相対リンクにすればローカルで単にブラウザで開いて閲覧することができるので便利。また、単に設定済みの Web サーバーのサブディレクトリに配置すれば閲覧できるようになることを期待。未だ簡単なテストのみしかしていません。

変更 (2022-10-10 更新)

現状の課題

対応済: navbar.cssbackground-image: url(.../cpprefjp-icon-v1.1-transparent.png)

→ data スキームによる埋込に対応しました。cpprefjp/static/static/original-icons/cpprefjp-icon-v1.1.svgにSVGがあったので、それを data スキームで埋め込んでみました。

対応済: ローカルで閲覧しようとすると crsearch.json の読み込みで CORS (Cross-origin resource sharing) エラー

今は file:// の時に (JSON through XHR の代わりに) JSONP through <script> を使うようにしています。

対応済: crsearch.json/run.py にハードコードされている base_url を何とかする

→現状は取り敢えずハードコートされている base_url はデフォルトの base_url と思うことにして、それとは別に CRSearch の初期化オプションで base_url を動的に指定できるように拡張しています (d1eb6a47 @ crsearch, 852c5074 @ kunai)。

対応済: raw.githubusercontent.com/cpprefjp/image にあるデータもサイトの中に含めるべきでは

これでインターネットに繋がっていない環境でもローカルの cpprefjp で図が見られます。
あと、images の中の図に対するリンクの指定も標準化しています。

対応済: manifest.json の位置指定が変

これは元々あった問題ですがリンク関係ということでこのPRに含めてしまっています b99a8c2

@yumetodo
Copy link
Member

改めまして

現状 site, kunai, crsearch の出力結果を cpprefjp.github.io に全部くっつけて入れているのだから、image のデータも deploy 時に cpprefjp.github.io の中に入れて良いのではないかということです (実際 Web ページの画像を開発用 repository の一つである cpprefjp/image から raw.githubusercontent.com を通して直接持ってくるのは何か変な感じがする)。

これ改めて考えるとrepoの肥大化を防ごうとした説ないですかね

で、今となってはsubmoduleとして画像置けばいいのではないかって思います。
GitHub PagesにSubmoduleを使う時の注意点 - Qiita

@akinomyoga
Copy link
Member Author

akinomyoga commented Jun 30, 2022

コメントありがとうございます。

改めまして

現状 site, kunai, crsearch の出力結果を cpprefjp.github.io に全部くっつけて入れているのだから、image のデータも deploy 時に cpprefjp.github.io の中に入れて良いのではないかということです (実際 Web ページの画像を開発用 repository の一つである cpprefjp/image から raw.githubusercontent.com を通して直接持ってくるのは何か変な感じがする)。

これ改めて考えるとrepoの肥大化を防ごうとした説ないですかね

そう。その説は私も頭を過ったのですが、実際のところ画像は一回追加したら基本的に変更されないし、それよりはキャッシュ防止の為の URL hash (cachebust) の方が断然サイズを食っている (例えば cpprefjp/cpprefjp.github.io@b06298b を見て下さい! (フリーズ注意。スマホでは開かない方が良いかも)) ので、画像サイズ程度は気にすることではないなぁと思いました。

で、今となってはsubmoduleとして画像置けばいいのではないかって思います。
GitHub PagesにSubmoduleを使う時の注意点 - Qiita

うーん。今の話は生成結果に images のデータを含めるということであって、site などのリポジトリの中に画像を含めるという話ではない…と思うのですがそういうことではない? 別の言い方をすれば、現状ではユーザーがページを閲覧した時に https://cpprefjp.github.io/ のサイト外から画像を読み込む形になっているが、画像も https://cpprefjp.github.io/ の下に配置したいという話です。


GitHub PagesにSubmoduleを使う時の注意点 - Qiita

追記 あぁ。なるほど。GitHub Pages で submodule を使うことができるんですね。。

でも今回はローカルで生成した時にも反映させたいので gh-pages 特有の効果には頼りたくないというのと、GitHub のリポジトリの内容が含まれる .zip のリンク (例 https://github.com/akinomyoga/cpprefjp-site/archive/refs/heads/gh-pages.zip) からダウンロードしたものを直接閲覧できたらいいな、というのもあるのでやはり cpprefjp.github.io に含めたいなぁと思っています。

@yumetodo
Copy link
Member

yumetodo commented Oct 9, 2022

だいぶ塩漬けにしてしまいました。これなんだっけと思い出すところから・・・

毎回新しいWebサーバーを立ち上げる必要が出てきます

そもそもWebさーばーごとき、立ち上げればいいし、リモートのものをっていうならssh portforwardingないしはVSCode Serverのport forwardで間に合ってるのでうーんってなったんですが、

GitHub のリポジトリの内容が含まれる .zip のリンクからダウンロードしたものを直接閲覧できたらいいな

これ言われてなるほどなと思いました。 cpprefjp/site#917 でそういう需要は言われてましたもんね・・・。とかいたところで、そもそもこの話が cpprefjp/site#917 から来ていたことを思い出しました。

モチベーションについては理解しました。同時に

image のデータも deploy 時に cpprefjp.github.io の中に入れて良いのではないか

に対する懸念点もなくなりました。

@yumetodo
Copy link
Member

yumetodo commented Oct 9, 2022

@akinomyoga あと課題点ってなんでしたっけ

@akinomyoga
Copy link
Member Author

@akinomyoga あと課題点ってなんでしたっけ

特に個人的に残っている課題点はなくもう満足してます。

@yumetodo
Copy link
Member

yumetodo commented Oct 9, 2022

それでは自分は基本設計としては異論ないので実装を眺めることにします

@akinomyoga
Copy link
Member Author

ありがとうございます

@yumetodo
Copy link
Member

yumetodo commented Oct 9, 2022

@akinomyoga 説明欄のdiffのリンク先にキーワード自動リンクの差分が混ざっていたり、レビュー記録が残し辛いので各repoでPRを切っていただきたいです。

@akinomyoga
Copy link
Member Author

OK. これは diff のリンクが昔の commit との比較になっているからですね。元々完全に棄却されるかもしれないと思ってPRを無駄に開かないようにしてましたが、それぞれ PR にします

@yumetodo
Copy link
Member

yumetodo commented Oct 10, 2022

image

手元にDockerがいなかったので適当なLinux VPS環境で実施しました。
crsearchはnpm packしてkunaiでnpm install <npm packでできたtarball>して差し替えて動かしました。sudo ./docker.sh run settings.cpprefjp_relativeしてビルドが通り、成果物をrsyncで手元に取ってきて手元のFirefoxにD&Dしたところ、ひとまず動いていそうです。

この後デグレがないか、boostjpの動作確認など検査することになります。

確認した観点は以下です。他の検証観点があれば教えてください。

  • cpp exampleと記載されたコードブロックの実行機能が動作すること
  • imagesにおいている画像が埋め込まれていること
  • 検索が動作すること
  • google検索への遷移機能が動作すること
    • <keyword> site:に展開されるので正しく検索できない。ただしそういうものといえばそうとみなすこともできる
    • ただ、kunaiでせっかく document.querySelector('meta[name="twitter:url"]') || document.querySelector('meta[property="og:url"]');とかしているのだから惜しい気はする
  • 定義語自動リンク: プロセッサ markdown_to_html.defined_words を追加 #79 が動作すること

@akinomyoga
Copy link
Member Author

  • google検索への遷移機能が動作すること
    • <keyword> site:に展開されるので正しく検索できない。ただしそういうものといえばそうとみなすこともできる
    • ただ、kunaiでせっかく document.querySelector('meta[name="twitter:url"]') || document.querySelector('meta[property="og:url"]');とかしているのだから惜しい気はする

御指摘ありがとうございます。これは対応いたします。ただ、今忙しいので2週間程待っていただくことになるかもしれません。

This reverts commit e4597df, which was
actually the reverse commit for the change
61156b4 made to
af55908.
@akinomyoga
Copy link
Member Author

akinomyoga commented May 17, 2024

[ ] google検索への遷移機能が動作すること

  • <keyword> site:に展開されるので正しく検索できない。ただしそういうものといえばそうとみなすこともできる
  • ただ、kunaiでせっかく document.querySelector('meta[name="twitter:url"]') || document.querySelector('meta[property="og:url"]');とかしているのだから惜しい気はする

@yumetodo 2週間ではなく2年間経ちましたが (すみません)… akinomyoga/cpprefjp-kunai@5fc7babakinomyoga/cpprefjp-crsearch@91b3583 で対応しました。

追記: もし手元に以前の環境を未だお持ちでしたら差分更新は "たぶん" ↓で行けます (駄目だったらすみません)。もし以前の環境がなければ site_generator の README にある説明を一から。

$ cd /path/to/crsearch
$ npm pack
$ cd /path/to/site_generator/kunai
$ npm install <path/to/cresarch-3.0.23.tar.gz generated by the above npm pack>
$ cd /path/to/site_generator
$ ./kunai/docker.sh install
$ ./kunai/docker.sh dist
$ ./crsearch.json/docker.sh run
$ ./docker.sh run settings.cpprefjp_relative
$ ls cpprefjp/cpprefjp.relative

追記: 一から構築する時は README に追記している追加手順 が必要でした。

@akinomyoga
Copy link
Member Author

akinomyoga commented May 18, 2024

テストする側で生成環境を整えるのも大変だと思いますので、生成結果を以下に添付します。Zip を使う場合はローカルで展開して index.html をブラウザで開いていただければそのまま御覧になれます。

留意事項

上で既に言及していますが今来た人のために。

  • この変更によって 相対リンクで生成する機能を off にしていても、cpprefjp/image 内部の画像ファイル (.png, .jpg, .svg) も (raw.githubusercontent.com の外部リンクではなく) Web サイトの中に含める様に変更しています。但しそれ以外のファイル (.tsv.tsv.7z) は外部リンクのままです。つまり、cpprefjp/cpprefjp.github.ioimage 由来の画像が追加されます。

@faithandbrave
Copy link
Member

ありがとうございます。いい感じですね。
こちら残タスクはまだありますか?

@akinomyoga
Copy link
Member Author

akinomyoga commented May 24, 2024

取り敢えず一区切りはついています! ただし、 @yumetodo さんが今週末に見たいということを Twitter で言及されていました。

あと、この機能は機能として実装しただけで、既存の settings.cpprefjp を置き換えるものではありません。使うにはそれぞれ site_generator を走らせる時に settings.cpprefjp の代わりに settings.cpprefjp_relative を指定する必要があります。

cpprefjp/site#917 にあるような物を提供するには、更に CI の生成を settings.cpprefjp_relative に置き換えるか、別枠で CI を走らせて Zip に固めるか、誰かが手元で生成して手動でアップロードするかなどが必要です。それはそれで (そもそも提供するかも含めて) また議論が必要になるような気がするので、分けておきたいと思っています。

@akinomyoga
Copy link
Member Author

Google 検索の site: 対応のために新しく追加した変更について、変数名は project_url ではなくて online_url の方がいいかもしれないと思われてきました。

@faithandbrave
Copy link
Member

とくに不都合がなければcpprefjp_relativeをデフォルトにしてもいい気がしますが、問題ありそうでしょうか?
リリース物を自動で作れるかと、最新リリースのzipへのリンクを取得できるかなど (バージョン指定ではなくlatestみたいなの)、一旦調べないとですね。

@faithandbrave
Copy link
Member

yumetodoさんの確認待ちです。

@yumetodo
Copy link
Member

yumetodo commented Jun 9, 2024

うーん、なぜか手元で動かすと↓になってしまう・・・。

Note: You can create /reference/cstdio/printf.md for lang/cpp11/variadic_macros.md.
module/std
Traceback (most recent call last):
  File "./run.py", line 634, in <module>
    main()
  File "./run.py", line 620, in main
    f.write(make_sitemap(pageinfos))
  File "./run.py", line 412, in make_sitemap
    return sitemap.GitSitemap(get_loc, get_priority, get_default_datetime).git_to_sitemap(settings.INPUT_DIR, pageinfos)
  File "/var/src/sitemap.py", line 106, in git_to_sitemap
    times = self._get_last_commit_times()
  File "/var/src/sitemap.py", line 70, in _get_last_commit_times
    _, logs, _ = run_with_output(['git', 'log', '-m', '-r', '--name-only', '--format=' + prefix + '%ai'], shell=False)
  File "/var/src/sitemap.py", line 57, in run_with_output
    raise Exception('return code is non-zero: {}'.format(p.returncode))
Exception: return code is non-zero: 128
remove: cpprefjp/cpprefjp.github.io/rss.xml

@akinomyoga
Copy link
Member Author

わからないですが、直接 git log -m -r --name-only --format='---- %ai' を実行した時には動きますか

[site_generator]$ (cd cpprefjp/site; git log -m -r --name-only --format='---- %ai' > a.tmp); echo $?

関係あるかわからないですが exit status 128 で検索したら以下のような記事がありました。

https://zenn.dev/unsoluble_sugar/articles/a0ecf5ca90a5c4

@yumetodo
Copy link
Member

あー理解しました。手癖でcpprefjp/siteをcloneするときに--filter=blob:noneをつけてたのが良くなかったぽいです。


で、もともとの指摘内容であった、Google検索への遷移の問題を見てみました。

cpprefjp公式の結果↓

image

手元の生成結果↓

image

結果としては意図したとおりになっていそうです(ようはただのgoogle検索にフォールバックしている)。

@yumetodo
Copy link
Member

というわけでレビューに時間が割けず大変長らくおまたせしましたが、approveしました。関連MRも改めて目を通しましたが問題ないと思います(全部approveつけたはず)。

自分にはマージ権限がないので、権限お持ちの方にマージをお任せしたいです。

@akinomyoga
Copy link
Member Author

手元の生成結果↓

あれ。すみません。お待ち下さい。意図した通りに動いていませんね…。

@akinomyoga
Copy link
Member Author

akinomyoga commented Jun 10, 2024

意図としてはローカルで実行した場合には site:cpprefjp.github.io になるつもりだったのですが、今こちらの手元で実行してもsite: で空になってしまっていますね。バージョンを巻き戻して試してみましたがそれでも動いていません。テストした気になっていたのですが、テストの仕方を間違えていた気がします…。改めて動作確認します。

@yumetodo
Copy link
Member

あれっ、自分の仕様理解が足りてなかったですか・・・(そもそも仕様どれというのはおいておいて)

@akinomyoga
Copy link
Member Author

やっぱり初めにテストしていた時は動いていて、その後の変更で壊してました。7776c3c..9cdc87d@cpprefjp/crsearch で変数名を project_url から online_base_url に変更したのですが、それの変更漏れでした…。 9cdc87d..0fab6a0@cpprefjp/crsearchcrsearch 追加修正しました。手元で動作確認しました。

$ cd /path/to/crsearch
$ git checkout relative_link # ※手元に変更があればコミットしてタグか別ブランチでバックアップする
$ git fetch
$ git reset --hard <akinomyoga>/relative_link     # ※<akinomyoga> は git@github.com:akinomyoga/cpprefjp-crsearch.git のリモート名
$ npm pack
$ cd /path/to/site_generator/kunai
$ npm install <path/to/cresarch-3.0.23.tar.gz generated by the above npm pack>
$ cd /path/to/site_generator
$ ./kunai/docker.sh install
$ ./kunai/docker.sh dist
$ ./crsearch.json/docker.sh run
$ ./docker.sh run settings.cpprefjp

@faithandbrave
Copy link
Member

それじゃマージしていきますね

faithandbrave added a commit to cpprefjp/crsearch that referenced this pull request Jun 11, 2024
内部リンクを相対リンクで生成する機能 (cpprefjp/site_generator#81)
faithandbrave added a commit to cpprefjp/kunai that referenced this pull request Jun 11, 2024
内部リンクを相対リンクで生成する機能 (cpprefjp/site_generator#81)
faithandbrave added a commit to cpprefjp/markdown_to_html that referenced this pull request Jun 11, 2024
内部リンクを相対リンクで生成する機能 (cpprefjp/site_generator#81)
faithandbrave added a commit to cpprefjp/image that referenced this pull request Jun 11, 2024
内部リンクを相対リンクで生成する機能 (cpprefjp/site_generator#81)
faithandbrave added a commit to boostjp/image that referenced this pull request Jun 11, 2024
内部リンクを相対リンクで生成する機能 (cpprefjp/site_generator#81)
@faithandbrave faithandbrave merged commit c398125 into cpprefjp:master Jun 11, 2024
faithandbrave added a commit to cpprefjp/site that referenced this pull request Jun 11, 2024
内部リンクを相対リンクで生成する機能 (cpprefjp/site_generator#81)
faithandbrave added a commit to boostjp/site that referenced this pull request Jun 11, 2024
内部リンクを相対リンクで生成する機能 (cpprefjp/site_generator#81)
@akinomyoga akinomyoga deleted the relative_link branch June 11, 2024 04:13
@faithandbrave
Copy link
Member

全部マージしました。
ビルド・デプロイ中です。

@akinomyoga
Copy link
Member Author

ありがとうございます!

@faithandbrave
Copy link
Member

デプロイ完了しました。問題なく動作してるようです!
@akinomyoga 非常に大きな作業だったと思いますが、対応ありがとうございます!

@faithandbrave
Copy link
Member

cpprefjpとboostjpのトップページ (index.md) に、HTMLのダウンロードリンクを記載しました

@akinomyoga
Copy link
Member Author

akinomyoga commented Jun 11, 2024

ありがとうございます! こちらの手元でも .zip をダウンロードして確認しようとしたのですが、差分ビルドになっていてフルビルドになっていませんね、と思ったら新しい commit が入ったのに今気づきました。(Windows で見ようとすると Microsoft Defender が 100% になってしまってダウンロード+展開で 10 分もかかりました…今からまたダウンロード+展開して確認します。)

@akinomyoga
Copy link
Member Author

.zip でダウンロードしたものはローカルで動いていないみたいです。自分で生成したものは動くのですが…。

@akinomyoga
Copy link
Member Author

akinomyoga commented Jun 11, 2024

README.md のビルド手順に追加したのと同じものを site の build.sh にも反映させなくては駄目ですね…。すみません、当たり前ですね…。後で対処します

@faithandbrave
Copy link
Member

動くようになりましたね!対応ありがとうございます!

@akinomyoga
Copy link
Member Author

ありがとうございます! こちらの手元でも確認しました。

@yumetodo @faithandbrave 色々とありがとうございました! (そして長らく PR を放置してすみませんでした…)

@yumetodo
Copy link
Member

一応リンク踏んでzip落としてみましたが、大丈夫そうですね!

image

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants