Docs.rs

Docs.rs（原名cratesfyi）是Rust编程语言的crate文档托管的开源项目。

Docs.rs使用Rust编译器的nightly版本自动构建crates.io上发布的crate的文档。

此README是为开发docs.rs而编写。有关面向用户的文档，请参阅关于页面。

文档的生成方式

docs.rs使用rustdoc为crates.io上的每个crate版本生成文档。有关更多详细信息，请参阅rustdoc书籍。

更改构建环境

要更改构建环境并在docs.rs上测试其是否正常工作，请参阅Wiki。

开发

开发docs.rs的推荐方式是结合使用主二进制文件的cargo run以及外部服务的docker-compose。这可以在不向主机机器添加新用户和软件包的情况下，为您提供合理的增量构建时间。

Git 插件

为了便于使用，git_hooks目录包含一些有用的git hooks，以便使您的开发更加容易。

# Unix
cd .git/hooks && ln -s ../../.git_hooks/* . && cd ../..
# Powershell
cd .git/hooks && New-Item -Path ../../.git_hooks/* -ItemType SymbolicLink -Value . && cd ../..

依赖项

Docs.rs 至少需要以下本机 C 依赖。

• gcc
• g++
• pkg-config
• git
• make
• cmake
• zlib
• openssl（包含开发包）-- Ubuntu 示例 sudo apt install libssl-dev

可能存在尚未记录的其他依赖项。

入门指南

请确保您已安装 docker-compose，并且能够首次运行时下载 ~10GB 数据。还请确保已安装 docker 并运行了服务。

git clone https://github.com/rust-lang/docs.rs.git docs.rs
cd docs.rs
git submodule update --init
# Configure the default settings for external services
cp .env.sample .env
# Create the DOCSRS_PREFIX directory
mkdir -p ignored/cratesfyi-prefix/crates.io-index
# Builds the docs.rs binary
SQLX_OFFLINE=1 cargo build
# Start the external services.
# It may be `docker compose` in newer versions
docker-compose up -d db s3
# anything that doesn't run via docker-compose needs the settings defined in
# .env. Either via `. ./.env` as below, or via any dotenv shell integration.
. ./.env
# allow downloads from the s3 container to support the /crate/.../download endpoint
mcli policy set download docsrs/rust-docs-rs
# Setup the database you just created
cargo run -- database migrate
# Update the currently used toolchain to the latest nightly
# This also sets up the docs.rs build environment.
# This will take a while the first time but will be cached afterwards.
cargo run -- build update-toolchain
# Build a sample crate to make sure it works
cargo run -- build crate regex 1.3.1
# This starts the web server but does not build any crates.
# It does not automatically run the migrations, so you need to do that manually (see above).
cargo run -- start-web-server
# If you want the server to automatically restart when code or templates change
# you can use `cargo-watch`:
cargo watch -x "run -- start-web-server"

如果您需要在存储库目录中存储大文件，建议将它们放在 ignored/ 子目录中，该目录既被 git 也被 Docker 忽略。

在 docker-compose 之外运行数据库和 S3 服务器是可能的，但既不推荐也不受支持。请注意，无论什么情况，您都需要安装 docker，因为它用于 Rustwide 沙盒。

运行测试

cargo test

要运行 GUI 测试

./dockerfiles/run-gui-tests.sh

它们使用 browser-ui-test 框架。您可以在这里查看其文档。

纯 docker-compose

如果您在上面的命令中遇到问题，请考虑使用 docker-compose up --build，它使用 docker-compose 作为 Web 服务器。这将不会缓存依赖项 - 特别是，每当锁文件更改时，您将必须重建所有 400 - 但确保您处于已知环境，因此您应该遇到更少的问题。

您还可以使用 web 容器在不支持直接运行构建的系统上运行构建（主要是在 Mac OS 或 Windows 上）

# run a build for a single crate
docker-compose run web build crate regex 1.3.1
# or build essential files
docker-compose run web build add-essential-files
# rebuild the web container when you changed code.
docker-compose build web

请注意，当使用纯 docker-compose 时，不支持运行测试。

请为运行 docs.rs 时遇到的任何问题提交错误报告！

Docker-Compose

Docker-Compose 启动的服务定义在 docker-compose.yml 中。定义了三个服务

重建容器

要重建网站，请运行 docker-compose build。请注意，即使更改了源代码，docker-compose 也会缓存构建，因此每次您进行更改时都将是必要的。

如果您想完全清理数据库，别忘了删除卷

$ docker-compose down --volumes

常见问题解答

当我使用 docker-compose 时，我看到了错误 standard_init_linux.go:211: exec user process caused "no such file or directory"

您可能具有 CRLF 行结束符。这导致 docker-entrypoint 中的 hashbang 变为 /bin/sh\r 而不是 /bin/sh。这可能是由于您将 git.autocrlf 设置为 true，将其设置为 input。

在运行构建时，我看到了错误 /opt/rustwide/cargo-home/bin/cargo: 无法执行二进制文件: 执行格式错误。

你很可能不在Linux平台上。直接运行构建只支持在 x86_64-unknown-linux-gnu 上。在其他平台上，你可以使用上面描述的 docker-compose run web build [...] 工具。

有关直接支持更多平台的信息，请参阅 rustwide#41。

所有测试均失败或超时

我们的测试设置需要一定数量的文件描述符。

至少需要4096个，您可以通过以下方式设置

$ ulimit -n 4096

命令行界面

有关完整命令列表，请参阅 cargo run -- --help。

启动网络服务器

# This command will start web interface of docs.rs on https://127.0.0.1:3000
cargo run -- start-web-server

build 子命令

# Builds <CRATE_NAME> <CRATE_VERSION> and adds it into database
# This is the main command to build and add a documentation into docs.rs.
# For example, `docker-compose run web build crate regex 1.1.6`
cargo run -- build crate <CRATE_NAME> <CRATE_VERSION>

# alternatively, via the web container
docker-compose run web build crate <CRATE_NAME> <CRATE_VERSION>

# Builds every crate on crates.io and adds them into database
# (beware: this may take months to finish)
cargo run -- build world

# Builds a local package you have at <SOURCE> and adds it to the database.
# The package does not have to be on crates.io.
# The package must be on the local filesystem, git urls are not allowed.
# Usually this command can be applied directly to a crate root
# In certain scenarios it might be necessary to first package the respective
# crate by using the `cargo package` command.
# See also /docs/build-workspaces.md
cargo run -- build crate --local /path/to/source

database 子命令

# Adds a directory into database to serve with `staticfile` crate.
cargo run -- database add-directory <DIRECTORY> [PREFIX]

# Updates repository stats for crates.
# You need to set the DOCSRS_GITHUB_ACCESSTOKEN
# environment variable in order to run this command.
# Set DOCSRS_GITLAB_ACCESSTOKEN to raise the rate limit for GitLab repositories,
# or leave it blank to fetch repositories at a slower rate.
cargo run -- database update-repository-fields

如果您想手动探索或编辑数据库，可以使用 psql 命令连接到数据库。

. ./.env
psql $DOCSRS_DATABASE_URL

数据库包含不应构建的crate的黑名单。

# List the crates on the blacklist
cargo run -- database blacklist list

# Adds <CRATE_NAME> to the blacklist
cargo run -- database blacklist add <CRATE_NAME>

# Removes <CRATE_NAME> from the blacklist
cargo run -- database blacklist remove <CRATE_NAME>

如果您想回滚到精确的迁移，可以运行

cargo run -- database migrate <migration number>

daemon 子命令

# Run a persistent daemon which queues builds and starts a web server.
cargo run -- daemon --registry-watcher=disabled
# Add crates to the queue
cargo run -- queue add <CRATE> <VERSION>

更新依赖源

有关更新Font Awesome的说明和链接可以在他们的网站上找到 这里。同样，Pure-CSS 也在其网站上进行了说明 这里。

在更新Font Awesome时，请确保将 $fa-font-path 在 scss/_variables.scss （它应该在文件顶部）更改为 ../-/static。这将指向正确的路径，从该路径请求字体和图标资源。

联系信息

docs.rs 由 docs.rs 团队 运行和维护。您可以在 zulip 上的 #t-docs-rs 找到我们。