開発プロセス中にオンライン ドキュメントを読む際の劣悪なエクスペリエンスを改善するために、ローカルで高速なドキュメント アクセスを提供する 10 MB 未満の小さなツール。
また、配布と使用に役立つオフライン ドキュメント ツールキットを迅速に作成する方法も紹介します。
前に書く
AI支援コーディングやチャットボット製品が数多く登場し、コードを書くエクスペリエンスが非常に良くなったとはいえ、日々のコーディングプロセスでは必然的にオープンソース製品のドキュメントを読む必要があります。
GitHub Pages にデプロイされたドキュメントのアクセス エクスペリエンスなど、さまざまな理由から、説明するのは困難です。文書を閲覧していると、ブラウザが時々グルグル回転してしまい、継続的な思考に大きな影響を与え、時間の無駄になってしまいます。
特に「あなたの Web サイトにはフロントエンド構築は必要ないかもしれません (2) 」という記事で、非常に優れたフロントエンド フレームワークとツールをいくつか紹介しましたが、それらのドキュメントはすべて GitHub でホストされています。
さらに、これらのドキュメントは外部 API インターフェイスやインターネット ウィジェットも参照している可能性があるため、これらのドキュメントをローカルにダウンロードするだけでは、アクセスが遅いという問題は完全には解決されません。これらのウィジェットが読み込まれる前に、ページは「ホワイト ページ」になる可能性があります。
したがって、今年初めの記事「 Golang Gin フレームワークの静的ミドルウェアの改善: Gin-Static 」と組み合わせて、開発プロセス中にオンライン ドキュメントを読む際の劣悪なエクスペリエンスを改善するために、ローカルで高速なドキュメント アクセスを提供する小さなツールを作成しました。 . .
このプロジェクトは、soulteary/docker-quick-docsでオープンソース化されており、ワンクリックで接続することも、必要なコードを取得することもできます。
オンラインドキュメントをローカルドキュメントに変換する
baidu/sanによって GitHub Pages にデプロイされたオンライン ドキュメントを例として取り上げ、すぐにアクセスできるローカル ドキュメントに変換します。
文書データの取得
GitHub Pages にデプロイされたこのプロジェクトと同様のコンテンツはgh-pages、通常、プロジェクトのブランチにあるため、ドキュメント コンテンツを取得するには 2 つの方法があります。1 つ目は、プロジェクト ブランチを page に切り替え、gh-pagesボタンをクリックしてコードをダウンロードすることです。 、ソースコードの圧縮パッケージを取得します。
ただし、この方法でコードの内容を更新するのはより面倒なので、git cloneパラメータを渡して指定されたディレクトリのコードをダウンロードし、それをできるだけ少なくする2 番目の方法をお勧めしますclone。
git clone http://github.com/baidu/san --depth 1 --branch=gh-pages
コードが実行されると、更新可能なドキュメント データをウェアハウスから比較的迅速に取得できます。
# git clone http://github.com/baidu/san --depth 1 --branch=gh-pages
Cloning into 'san'...
warning: redirecting to https://github.com/baidu/san/
remote: Enumerating objects: 405, done.
remote: Counting objects: 100% (405/405), done.
remote: Compressing objects: 100% (197/197), done.
remote: Total 405 (delta 154), reused 303 (delta 65), pack-reused 0
Receiving objects: 100% (405/405), 2.17 MiB | 5.18 MiB/s, done.
Resolving deltas: 100% (154/154), done.
後でコードを更新したい場合は、ディレクトリに入って次を実行するだけですgit pull。
# cd san
# git pull
Already up to date.
クイックドキュメントを開始する
Quick Docs の使用方法は 2 つあり、1 つはGitHub のリリースページからシステムに適したバイナリファイルをダウンロードして直接実行する方法です。
./quick-docs
デフォルトでは、ディレクトリ内にディレクトリが自動的に作成されdocs、準備したすべてのドキュメントがこのディレクトリに保存されるため、ローカルでの操作が可能になります。デフォルトのポートは です8080。
ポートを調整したい場合は、コマンドで環境変数を設定できますPORT。たとえば、9000ポート上で実行したい場合は、次のように実行できます。
PORT=9000 ./quick-docs
もちろん、あなたが Docker 愛好家であれば、より「環境に優しい」ソリューションがあります。
# 下载工具
docker pull soulteary/docker-quick-docs:v0.1.2
# 使用工具启动文档
docker run --rm -it -v `pwd`/docs:/app/docs -p 8080:8080 soulteary/docker-quick-docs:v0.1.2
プログラムの実行が完了すると、次のような出力が表示されます。
2024/01/04 11:39:54 Quick Docs v0.1.2
この時点で、アクセスすると、http://localhost:8080どのディレクトリが参照できるかがわかります。
1 つのプロジェクトのドキュメントのみを保存するためsan、ブラウザを開いた後は、当面はこのディレクトリにのみアクセスできます。さらに多くのドキュメントにアクセスしたい場合は、さまざまなドキュメントをdocsディレクトリに入れてプログラムを起動するだけです。
ディレクトリをクリックすると、sanローカル展開ドキュメントが表示されます。
遅い GitHub とは異なり、ローカルに配置されたドキュメントのアクセス速度は大幅に向上しているため、特定のオープン ソース ソフトウェアのドキュメントに頻繁にアクセスする場合、このソリューションは間違いなく大幅な時間を節約できます。
通常の状況では、このステップの後、ドキュメントへのローカライズされたアクセスが完了します。ただし、究極を追求する場合は、ローカル ページをより速く開くことができるか、オフラインでも完全にアクセスできるようにする必要があると思います。そのため、引き続き検討してみましょう。
高度な機能: ドキュメントコンテンツの書き換え
例として のドキュメントを続けてみましょうsan。ネットワーク デバッグ ツールを開いてページを再度更新すると、ロードが遅い 2 つの明らかなリクエストがあることがわかります。
この問題を解決するには、ツールがサポートする「コンテンツ書き換え機能」を利用します。
単純な書き換え
上記の内容を例として挙げると、上記のページ内の遅いリクエスト アドレスは次のとおりです。
https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css
https://ghbtns.com/github-btn.html?user=baidu&repo=san&type=star&count=true&size=large
たとえば、上記のリクエストを「空」として書き換えて、遅いリクエストを回避できます。
[
{
"from": "https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css",
"to": ""
},
{
"from": "https://ghbtns.com/github-btn.html",
"to": "about:blank"
}
]
上記の内容を として保存しますconfig.json。実行可能ファイルを使用してプログラムを実行し、プログラムを再起動すると、プログラムは自動的に設定ファイルをロードして適用します。
Docker ユーザーの場合は、この構成ファイルをコンテナーにマップするようにコマンドを調整する必要があります。
docker run --rm -it -v `pwd`/docs2:/app/docs -v `pwd`/config.json:/app/config.json -p 8080:8080 soulteary/docker-quick-docs:v0.1.2
プログラムの実行が完了すると、次のような出力が表示されます。
2024/01/04 12:06:57 Quick Docs v0.1.2
2024/01/04 12:06:57 未设置环境变量 `PORT`，使用默认端口：8080
2024/01/04 12:06:57 解析配置文件成功，规则数量: 2
この時点で、再度ページを開いて Web ページを更新すると、すべてのリクエストがローカルから送信されていることがわかり、ページのリクエスト速度が速くなっていることがわかります。
docs開発ドキュメントの閲覧エクスペリエンスを向上させるために、必要な数のドキュメントをディレクトリに配置できます。
より高いパフォーマンスの書き換え
ただし、多数のドキュメント ディレクトリと多数の書き換えルールがある場合、プログラム自体が十分に単純で、最新のハードウェアのパフォーマンスが十分に高い場合でも、不必要なパフォーマンスの低下が確実に発生します。
ただし、Quick Docs がバッテリー駆動のラップトップまたはシングルコアの小型ホストで実行されている場合は、可能であれば保存できます。
書き換えルールの有効範囲を制限するには、上記の書き換えルールの下にフィールドを追加するだけですdir。さらに制限したい場合は、書き換えられるコンテンツのタイプを設定することもできますtype。
[
{
"from": "https://ecomfe.github.io/san/",
"to": "/san/",
"type": "html",
"dir": "/san/"
},
{
"from": "https://github.com/baidu/san-router",
"to": "/san-router/"
},
{
"from": "https://ecomfe.github.io/santd/",
"to": "/santd/"
}
]
dirデフォルトでは、またはを設定しない場合type、プログラムはすべてのディレクトリ内のファイルに有効になりますhtml。
現在サポートされているファイル タイプにはhtml、、、、、jsが含まれますがcss、jsonオフライン ドキュメント ステーションにはこれで十分ですよね。十分ではないと思われる場合は、プロジェクトの問題で意見を提出してください。
そうですね、ローカルでホストする必要があるドキュメントがたくさんある場合は、これを見れば十分対処できます。
配布用の単一プログラムのドキュメントを作成する
このドキュメントの冒頭で、配布に便利なオフライン ドキュメント ツールキットの作成方法について説明しました。これは主に、以前の記事「Golang Gin フレームワークの静的ミドルウェアの改善: Gin-Static 」のミドルウェアを再利用する機能に関するものです。
単一ファイルのオフライン ツールキットを作成するには、まずプロジェクト コードをダウンロードする必要があります。
git clone https://github.com/soulteary/docker-quick-docs.git
次に、上記と同様に、プログラムで固めたいドキュメントをdocsディレクトリに配置します。
プログラムのビルド コマンドを実行します。
go build -o quick-docs
プログラムの実行後、現在のディレクトリに「組み込み」ドキュメントを含むプログラムを取得でき、前のdocsディレクトリから実行することもできます。
オフライン ドキュメント プログラムの準備ができました。実行時に、関数をEMBED=onアクティブにするパラメータを指定する必要があります。Embeded
EMBED=on ./quick-docs
上記のプログラムの使用方法に違いはありません。
やっと
さて、これを書いたところで、Quick Docs の使い方はすべて紹介されました。
次の記事でお会いしましょう。
–EOF
この記事は「表示 4.0 インターナショナル (CC BY 4.0)」のライセンス契約を使用していますので、転載、再改変、使用は自由ですが、出典の明示が必要です。表示 4.0 インターナショナル (CC BY 4.0)
この記事の著者: スー・ヤン
作成時期: 2024 年 1 月 4 日
統計ワード数: 4924 ワード
読了時間: 10 分
この記事を読むためのリンク: https://soulteary.com/2024/01/04/improving-the-github-pages-reading- experience-クイック -docs.html