ruby / docs.ruby-lang.org Goto Github PK

View Code? Open in Web Editor NEW

48.0 13.0 23.0 511 KB

Source of the docs.ruby-lang.org site

Home Page: https://docs.ruby-lang.org

Ruby 58.65% HTML 26.85% Shell 14.50%

ruby

docs.ruby-lang.org's Introduction

docs.ruby-lang.org

WARNING

This repository is inconsistent with production.
Use only bundle exec cap production deploy. Do not use ansible-playbook.

Platform Environment

We use capistrano for deployments.
Currently hosted on AWS EC2 Tokyo region
- All applications run as rurema user.
Periodic tasks run in systemd timer (systemctl list-timers)

Files and Directories

rurema-search: /var/rubydoc
docs.ruby-lang.org: /var/www/docs.ruby-lang.org
nginx configuration: /etc/nginx/sites-available/docs.ruby-lang.org

Files need to backup

old statically generated contents (old versions need to copy from old server): /var/www/docs.ruby-lang.org/shared/public/{en,ja}/*
- Versioned contents of ja are from https://github.com/rurema/generated-documents since 2024-06-06.
Fastly API Key: /home/rurema/.docs-fastly
Slack webhook URL: /etc/systemd/system/notify-to-slack.env
Mackerel API Key and plugin configurations: /etc/mackerel-agent/mackerel-agent.conf

Related repos

Production Environment

Capstrano

cap production deploy

/etc/nginx/sites-available/docs.ruby-lang.org

Manual sync with conf/docs.ruby-lang.org. Because ansible playbooks are outdated.

/etc/mackerel-agent/mackerel-agent.conf

Install mackerel-check-plugins too.

Add/Modified:

[filesystems]
ignore = "/dev/loop*"

[plugin.checks.fileage-bc-setup-all]
command = ["check-file-age", "-i", "-w", "90000", "-c", "172800", "-f", "/run/docs.ruby-lang.org/bc-setup-all.updated"]
[plugin.checks.fileage-bc-static-all]
command = ["check-file-age", "-i", "-w", "90000", "-c", "172800", "-f", "/run/docs.ruby-lang.org/bc-static-all.updated"]
[plugin.checks.fileage-rdoc-static-all]
command = ["check-file-age", "-i", "-w", "90000", "-c", "172800", "-f", "/run/docs.ruby-lang.org/rdoc-static-all.updated"]
[plugin.checks.fileage-update-rurema-index]
command = ["check-file-age", "-i", "-w", "90000", "-c", "172800", "-f", "/run/docs.ruby-lang.org/update-rurema-index.updated"]

docs.ruby-lang.org's People

Contributors

Stargazers

Watchers

docs.ruby-lang.org's Issues

Codeblock red is too dark

Let's take an example: https://docs.ruby-lang.org/en/master/Method.html#method-i-to_s
Is it just me or is the red "output" not so easy to read when one dims down the brightness of the screen?

class Symbol のドキュメントが別のclassのものになっている

ruby/rdoc の不備なのか、 docs.ruby-lang.org の不備なのかわからなかったので、とりあえずこちらに報告します。

問題点

class Symbol のドキュメントが別の class のものになっており、正しいドキュメントが表示されない。

https://docs.ruby-lang.org/en/2.4.0/Symbol.html → Bignumのドキュメント
https://docs.ruby-lang.org/en/trunk/Symbol.html → Integerのドキュメント

他の症状

検索時に２つ候補が出てくる。どちらをクリックしても、間違ったドキュメントの文面が出てくる

原因？

class Symbol のドキュメントは symbol.c ではなく string.c に記述されている。

https://github.com/ruby/ruby/blob/5d12e826475b859649f113638066b42f21b7784f/string.c#L9962

他のドキュメントサイト

ruby-docでは正しいドキュメントが表示できている
http://ruby-doc.org/core-2.4.2/Symbol.html

手元の Dash for macOS では正しいドキュメントが表示できている

jaの更新が止まっている

public以下をls -lすると Sep 26 02:50 の更新が最後のようです。

group method index by visibility

currently the method index (methods column on the left on a class/module page) is grouped by class vs instance, it would also be useful if it were grouped by visibility

最近のbitclustの更新が反映されていなさそう

マージされたPRの変更がぱっとみ反映されてなさそうに見えます。

たとえばこちらではmetaタグでviewportを追加したのですが
rurema/bitclust#76

HTMLにはviewportが含まれておらず

$ curl -s https://docs.ruby-lang.org/ja/latest/doc/index.html | grep viewport

こちらではタイトルの末尾にリファレンスマニュアルと明記しましたが

rurema/bitclust#78

付け加えられていないように見えます

$ curl -s https://docs.ruby-lang.org/ja/latest/doc/index.html | grep title
  <title>オブジェクト指向スクリプト言語 Ruby リファレンスマニュアル (Ruby 2.6.0)</title>

rdocがファイル名を誤解して間違った内容のファイルを生成する場合がある問題の一次対応

#40 の問題で Symbol.html 以外に該当するファイルがないか確認、rdocが直るまでの一次対応を行う。

RDoc::Storeの@classes_hashのキーと値.nameが一致しないものをdarkfish.rbでも上書きして調べる事ができるだろう。該当するものがあれば #40 のように直接置き換える。

Documentation needs backporting

docs.ruby-lang.org renders docs only for major versions: there is docs for 2.7.0, but not for 2.7.1 -- which implies that https://docs.ruby-lang.org/en/2.7.0/ actually contains "Generic 2.7 docs". At the same time, documentation is frequently fixed after the release. This way, documentation that is relevant for version x.y.*, but was NOT there at x.y.0 will NEVER be rendered. Some examples:

What's the pattern matching syntax for 2.7? The PM docs were written after the release, so they are accessible by https://docs.ruby-lang.org/en/3.0.0/doc/syntax/pattern_matching_rdoc.html (it is 3.0's PM!), or https://docs.ruby-lang.org/en/master/doc/syntax/pattern_matching_rdoc.html (was 2.7's before 3.0's release, now it is 3.0's too).
My method definition docs update was merged AFTER the 3.0 release. So endless methods and ... argument forwarding are documented here: https://docs.ruby-lang.org/en/master/doc/syntax/methods_rdoc.html, but not here: https://docs.ruby-lang.org/en/3.0.0/doc/syntax/methods_rdoc.html (implying they aren't in 3.0 at all)

I believe that something should be done about it, probably at least on releasing 3.0.1 its docs should be merged into 3.0.0 URL, or maybe rendered separately at https://docs.ruby-lang.org/en/3.0.1. Or, maybe, the docs should actually be backported into 3.0.0? Because if the Ruby installed with the local docs, 3.0.0 would forever lack them.

Let's Encrypt の cron を入れた

VM 移設時に忘れていました。

@monthly certbot renew --quiet && systemctl reload nginx

というのを root の crontab に入れたので共有します。 /cc @okkez @sho-h

メンテナンス中はメンテナンスページを表示してほしい

以下のようなものを見かけたりしましたので、メンテナンスの際は簡単なメンテナンス中ページでも表示してもらえるとありがたいのですが、可能でしょうか？

Accessibility issues

Hey,

I find docs.ruby-lang.org quite hard on the eyes whenever I need to read documentation. I had a look at WAVE (Web Accessibility Evaluation Tool) and here's the report for the Hash page:

https://wave.webaim.org/report#/https://docs.ruby-lang.org/en/3.1/Hash.html

navigation broken

It has been a while (since the naming convention was changed I think), just follow these steps:

go to http://www.ruby-doc.com/ and then:

click on "Core" link at the top => 404
click on "2.2.0 core" => 404
(this only fails for the latest release, the others work fine)

The issue is that it tries to redirect to "/core-2.0" where the correct path is "/core-2.2.0"

Change of documentation paths in 2022

I can't identify the exact change that caused this, but

for many years, and as recent as of Jan 26, 2022, all files in doc/ folder of the Ruby repository produced paths looking like doc/syntax/methods_rdoc.html
as of now, they became just 3.1/syntax/methods_rdoc.html (no doc/ prefix)

I am afraid that might've broken a lot of links on the Internet. I noticed because all the links to generic language docs in my Ruby Changelog became 404.

I wonder can this change be reverted, or, alternatively, can redirects be introduced between the old and new scheme?..

en/1.8.7、en/1.9.3が403になる

https://docs.ruby-lang.org/en/ からは 1.8.7と1.9.3がリンクされてますが、クリックすると403になります。

system/rdoc-static-allが以下だからかもしれません。public以下にsymlinkはあるのですが、指してる先にファイルがなかったです。再生成してVERSIONSは今のままにするか、リンクを消すかした方がいいかもしれません。(前者？

VERSIONS = %w[
  2.2.0
  2.3.0
  2.4.0
  2.5.0
  trunk
]

Use HTTPS

HTTPS is useful for SEO.
But I'm not sure about SEO.

インデックスが更新されていないのを調査する

最近の更新が反映されてないぽいので確認する。

るりまサーチから 2.8.0 が消えない

https://docs.ruby-lang.org/ja/search/ から 2.8.0 が消えないので調査中。

/var/www/docs.ruby-lang.org/shared/public から 2.8.0 を削除しても変わらず
system/update-rurema-index で見ているのは /var/rubydoc/doctree/refm/db-* だったので db-2.8.0 を削除して次回の更新を待ち中

生成をやめたバージョンの静的ファイルのバックアップ

docs.ruby-lang.org上のるりまサーチが重い

docs.ruby-lang.orgの方のるりまサーチが重いみたいです。

https://twitter.com/smbd/status/558434657662824448

以下は確認しましたが原因はわかっていません。

RubyのプロセスがCPUを食ってる
nginxのerror.log的には気になるものはない
access.logが4.5Gあってrotateされてないのは気になる

最後のものについては以下を確認しましたが、今日重くなる理由には該当しにくい気もします。

logrotateのpostrotateに失敗している(おそらくnginx.pidがないため)
- nginx自体は生きている
- access.log-<最後の日付>に追記が続いているのでシグナルをその日以来受け取らずにずっと動いている？
- logrotate.d/nginxはnotifemptyなので、それ以降はrotateもされていない
- crondは動いおり、cronのログも残っていたのでnginxだけの問題に見える

原因としてはアクセスが多くて単に重いか上記が理由でじわじわ重くなっていたかくらいしか思いつきませんでした。どちらも判断材料がないですが...

一度サービスを再起動してみるのがいいかもしれません。

るりまサーチでja/2.8.0が出てくる

https では開発版のドキュメントも ja/master (だけ) でみえるように追加したのですが、るりまサーチのインデックス対象に 2.8.0 も入ってしまっていて、存在しない URL が検索結果として出てしまっているようです。

show including modules/classes and subclasses for a given module/class

It's helpful to know what classes/modules include/extend a given module/class.

ja以下にtrunkディレクトリができる

deploy:symlink:linked_dirsのログを見ていたらja以下でもtrunkができてしまっているようです。

$ bundle exec cap production deploy
...
00:05 deploy:symlink:linked_dirs
    ...
      20 ln -s /var/www/docs.ruby-lang.org/shared/public/en/trunk /var/www/docs.ruby…
    ✔ 20 [email protected] 0.121s
      21 ln -s /var/www/docs.ruby-lang.org/shared/public/ja/trunk /var/www/docs.ruby…
    ✔ 21 [email protected] 0.124s
...

$ ls -l /var/www/docs.ruby-lang.org/current/public/ja/
...
lrwxrwxrwx 1 rurema rurema   51 Jan  1 14:31 latest -> /var/www/docs.ruby-lang.org/shared/public/ja/latest
lrwxrwxrwx 1 rurema rurema   50 Jan  1 14:31 trunk -> /var/www/docs.ruby-lang.org/shared/public/ja/trunk

$ ls -l /var/www/docs.ruby-lang.org/shared/public/ja/
...
lrwxrwxrwx 1 rurema rurema    5 Jan  1 14:37 latest -> 2.5.0
drwxr-xr-x 2 rurema rurema 4096 Aug 15 11:09 trunk

外からアクセスできないと思われるため、実害はなさそうです。

Guides project

We want to provide developer guides that are current and easy to contribute to.

They should separate from ruby source, and version specific api reference documentation.

Our goal is to build a jekyll site in this repository under ./guides that will house all of the important developer related documentation for CRuby.

system/*から呼ばれるbitclustを1.0.0にする

以下を使いたいため。既に更新されていればcloseする。

rurema/bitclust#32

Japanese document page has "http" URL image

index.html:110 Mixed Content: The page at 'https://docs.ruby-lang.org/ja/latest/doc/index.html' was loaded over HTTPS, but requested an insecure image 'http://i.creativecommons.org/l/by/3.0/88x31.png'. This content should also be served over HTTPS.

It is redirected to HTTPS URL https://licensebuttons.net/l/by/3.0/88x31.png, directly use HTTPS version is better.

脆弱性のある古い rdoc で作成されたものは削除する?

参考:
#51 (comment)
https://www.ruby-lang.org/ja/news/2019/08/28/multiple-jquery-vulnerabilities-in-rdoc/

古い rdoc で生成されたドキュメントには XSS 脆弱性があるようなので、削除するか js ファイルの差し替えをした方が良さそうです。

How do we contribute docs changes?

Hi. I was running some code samples from the docs today and noticed that the output I got didn't match what the docs showed (version 3.1.2). I was going to do a quick PR to correct them but I can't find the docs contents anywhere in this repo. The README for the repo doesn't mention how to contribute to docs, and skimming over the page https://www.ruby-lang.org/en/documentation/ I also can't find any instructions there for how to contribute.

Thanks!

$ date
Tue Aug 29 13:24:22 UTC 2017 # 22:24に実行

Redirect /trunk to /master

Due to Ruby Issue 15843, the latest docs URL changed from https://docs.ruby-lang.org/en/trunk/ to https://docs.ruby-lang.org/en/master/. However, there are links in various third-party docs and online articles which point to pages in /trunk. These links now return a 404.

Is it possible to redirect /trunk to /master to fix them?

En: Cannot find marshal_rdoc file while searching with "Marshal"

Actual

I couldn't find marshal_rdoc content while I was searching with "Marshal" query.

Expected

I could find the marshal_rdoc in search result.

A guide for upgrading ruby

1.8 -> 1.9
1.9 -> 2.0
2.0 -> 2.1

るりまサーチのAPIの返すURLがおかしい？

るりまサーチのAPIを試していたのですが、返してくるURLがおかしいようです。

次のようにcurlとjqをつかってURLを取り出してみると、https://docs.ruby-lang.org/ja/search/の後に、本来の検索結果のURLがついてきているようにみえます。また、検索結果のURLのスキーマがhttpsではなくhttpになっているので、httpsの方がより良さそうです。
$ curl -s 'https://docs.ruby-lang.org/ja/search/api:v1/query:open/' | jq '.entries[0].documents[0].url' 
"https://docs.ruby-lang.org/ja/search/http://docs.ruby-lang.org/ja/2.3.0/library/open=2duri.html"
期待するURL: https://docs.ruby-lang.org/ja/2.3.0/library/open=2duri.html
実際のURL: https://docs.ruby-lang.org/ja/search/http://docs.ruby-lang.org/ja/2.3.0/library/open=2duri.html

From clear-code/rurema-search#29

上のIssueをclear-code/rurema-searchに開いたところ、アプリケーションコードよりもデプロイの仕方に原因がありそうとコメントをもらったのでこちらにIssueをオープンします。

上のIssueを作った後にコードを眺めていたところ、このリポジトリの次のコードの当たりでオプションを設定しているようでした。

docs.ruby-lang.org/system/ruby-lang.org.ru

Line 75 in a3d7253

load_searcher_option.call(:document, "document.yaml")

ここで設定したbase_urlオプションが、APIが返すURLに関わってくるので、この設定が原因で意図しない表示になっていると思います。

https://github.com/clear-code/rurema-search/blob/7d5858ab4ab0d9c9eb5e91e14c54bd67e081c73a/lib/rurema_search/groonga_searcher.rb#L334-L341

503でみれないページがある

以下など。

https://twitter.com/sunaot/status/1061453522489602053