Merge pull request #10293 from Turbo87/package-docs

Add `README.md` files to subpackages

Author: Turbo87

crates/crates_io_database/README.md

@@ -0,0 +1,26 @@
+# crates_io_database
+
+This package contains the crates.io database schema as derived by `diesel print-schema`
+from the database after all the migrations have been applied.
+
+After creating new migrations (via `diesel migration generate`), you can update
+the schema by running:
+
+```sh
+diesel print-schema > crates/crates_io_database/src/schema.rs
+```
+
+## `schema.patch`
+
+Note that there is also a `schema.patch` file in this package, since the output
+of `diesel-cli` needs to be tweaked a little for our purposes. For example,
+it currently does not support printing materialized views in the same way as
+regular tables, so we have to manually add them to the schema file.
+
+If you need to update the patch file, you can do so by following these steps:
+
+1. prefix `patch_file = "src/schema.patch"` in `diesel.toml` with a `#` to comment it out.
+2. use `diesel print-schema` and save the output to `src/schema.rs.orig`
+3. use `patch -o src/schema.rs src/schema.rs.orig src/schema.patch` to apply the patch file and solve remaining issues in the `src/schema.rs` file
+4. use `diff -Naur src/schema.rs.orig src/schema.rs` to generate the new content for the `src/schema.patch` file
+5. enable the `patch_file` option in the `diesel.toml` file again.

crates/crates_io_database/src/lib.rs

@@ -1 +1,3 @@
+#![doc = include_str!("../README.md")]
+
 pub mod schema;

crates/crates_io_database_dump/README.md

@@ -0,0 +1,10 @@
+# crates_io_database_dump
+
+This package contains the code and data to create a database dump for the
+crates.io database.
+
+The most important file in this package is the `dump-db.toml` file, which
+defines how the database tables are serialized into CSV files. Specifically,
+it can be used to skip certain columns for privacy reasons, it can declare the
+serialization order of the tables, and it can declare filters, if not all rows
+should be dumped.

crates/crates_io_database_dump/src/lib.rs

@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 use anyhow::{anyhow, Context};
 use serde::Serialize;
 use std::fs;

crates/crates_io_env_vars/README.md

@@ -0,0 +1,14 @@
+# crates_io_env_vars
+
+This package contains convenient wrappers for the `std::env::var()` function.
+
+These functions use the `dotenvy` crate to automatically load environment
+variables from a `.env` file, if it exists. This is useful for development
+environments, where you don't want to set all environment variables manually.
+
+There are also variants of the functions that make use of the `FromStr` trait to
+automatically parse the environment variables into the desired types or fail
+with corresponding error messages.
+
+Finally, there are `list()` functions that allow parsing of comma-separated
+lists of values.

crates/crates_io_env_vars/src/lib.rs

@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 use anyhow::{anyhow, Context};
 use std::error::Error;
 use std::str::FromStr;

crates/crates_io_github/README.md

@@ -0,0 +1,12 @@
+# crates_io_github
+
+This package implements functionality for interacting with the GitHub API.
+
+It contains a `GitHubClient` trait that defines the supported operations, that
+the crates.io codebase needs to interact with GitHub. The `RealGitHubClient`
+struct is an implementation of this trait that uses the `reqwest` crate to
+perform the actual HTTP requests.
+
+If the `mock` feature is enabled, a `MockGitHubClient` struct is available,
+which can be used for testing purposes. This struct is generated automatically
+by the [`mockall`](https://docs.rs/mockall) crate.

crates/crates_io_github/src/lib.rs

@@ -1,4 +1,4 @@
-//! This module implements functionality for interacting with GitHub.
+#![doc = include_str!("../README.md")]
 
 #[macro_use]
 extern crate tracing;

crates/crates_io_index/README.md

@@ -0,0 +1,11 @@
+# crates_io_index
+
+This package contains the code necessary to interact with the
+[crates.io-index repository](https://github.com/rust-lang/crates.io-index).
+
+Specifically, it contains:
+
+- the data structures used to serialize and deserialize the files in the index
+- a `Repository` abstraction to perform various operations on the index
+- and, for testing purposes, an `UpstreamIndex` struct that can be used to
+  create a fake index locally.

crates/crates_io_index/lib.rs

@@ -1,3 +1,5 @@
+#![doc = include_str!("README.md")]
+
 #[macro_use]
 extern crate serde;
 #[macro_use]