Docs.rs (formerly cratesfyi) is an open source project to host documentation of crates for the Rust Programming Language.
Docs.rs automatically builds crates' documentation released on crates.io using the nightly release of the Rust compiler.
The README of a crate is taken from the readme field defined in Cargo.toml. If a crate doesn't have this field, no README will be displayed.
Docs.rs is using semver to parse URLs. You can use this feature to access
crates' documentation easily. Example of URL redirections for
|URL||Redirects to documentation of|
|https://docs.rs/clap||Latest version of clap|
|https://docs.rs/clap/2.9.3||2.9.3 version (you don't need = unlike semver)|
|https://docs.rs/clap/*/clap/struct.App.html||Latest version of this page (if it still exists).|
You can use badges to show state of your documentation to your users.
The default badge will be pointed at the latest version of a crate.
You can use
version parameter to show status of documentation for
any version you want.
Badge will display in blue if docs.rs is successfully hosting your crate documentation, and red if building documentation failing.
Example badges for
|Latest version: https://docs.rs/mio/badge.svg|
|Version 0.4.4: https://docs.rs/mio/badge.svg?version=0.4.4|
|Version 0.1.0: https://docs.rs/mio/badge.svg?version=0.1.0|
We strongly recommend using docker-compose, which will make it easier to get started without adding new users and packages to your host machine.
Make sure you have docker-compose and are able to download ~10GB data on the first run.
git clone https://github.com/rust-lang/docs.rs.git docs.rs cd docs.rs cp .env.sample .env docker-compose build # This builds the docs.rs binary # Build a sample crate to make sure it works # This sets up the docs.rs build environment, including installing the nightly # Rust toolchain. This will take a while the first time but will be cached afterwards. docker-compose run web build crate regex 1.3.1 # This starts the web server but does not build any crates. # If you want to build crates, see below under `build` subcommand. # It should print a link to the website once it finishes initializing. docker-compose up
If you need to store big files in the repository's directory it's recommended to
put them in the
ignored/ subdirectory, which is ignored both by git and
Tests are run outside of the docker-compose environment, and can be run with:
Some tests require access to the database. To run them, set the
CRATESFYI_DATABASE_URL to the url of a PostgreSQL database. You don't have to
run the migrations on it or ensure it's empty, as all the tests use temporary
tables to prevent conflicts with each other or existing data. See the wiki
page on developing outside docker-compose for more
information on how to setup this environment.
The services started by Docker-Compose are defined in docker-compose.yml. Three services are defined:
|web||http://localhost:3000||N/A||A container running the docs.rs binary|
|db||/||N/A||Postgres database used by web|
||Minio (simulates AWS S3) used by web|
To rebuild the site, run
Note that docker-compose caches the build even if you change the source code,
so this will be necessary anytime you make changes.
I keep getting the error
standard_init_linux.go:211: exec user process caused "no such file or directory" when I use docker-compose.
You probably have CRLF line endings.
This causes the hashbang in the docker-entrypoint to be
/bin/sh\r instead of
This is probably because you have
git.autocrlf set to true,
set it to
Starting web server
# This command will start web interface of docs.rs and you can access it from # http://localhost:3000/` docker-compose up
# 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` docker-compose run web build crate <CRATE_NAME> <CRATE_VERSION> # Builds every crate and adds them into database # (beware: this may take months to finish) docker-compose run web 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. docker-compose run -v "$(realpath <SOURCE>)":/build web build crate --local /build
# Adds a directory into database to serve with `staticfile` crate. docker-compose run web database add-directory <DIRECTORY> [PREFIX] # Updates github stats for crates. # You need to set CRATESFYI_GITHUB_USERNAME, CRATESFYI_GITHUB_ACCESSTOKEN # environment variables in order to run this command. # You can set this environment variables in ~/.cratesfyi.env file. docker-compose run web database update-github-fields
If you want to explore or edit database manually, you can connect to the database
# this will print the name of the container it starts docker-compose run -d db docker exec -it <the container name goes here> psql -U cratesfyi
The database contains a blacklist of crates that should not be built.
# List the crates on the blacklist docker-compose run web database blacklist list # Adds <CRATE_NAME> to the blacklist docker-compose run web database blacklist add <CRATE_NAME> # Removes <CRATE_NAME> from the blacklist docker-compose run web database blacklist remove <CRATE_NAME>
# Run a persistent daemon which queues builds and starts a web server. # Warning: This will try to queue hundreds of packages on crates.io, only start it # if you have enough resources! docker-compose run -p 3000:3000 web daemon --foreground