From d7d5c6c360c136fb35fbdb78c856d741682dcc6b Mon Sep 17 00:00:00 2001
From: Jonas Pleyer <59249415+jonaspleyer@users.noreply.github.com>
Date: Sun, 4 Feb 2024 00:06:23 +0100
Subject: [PATCH 1/3] add information about packaging crate

---
 README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README.md b/README.md
index d50777109..8d5959afd 100644
--- a/README.md
+++ b/README.md
@@ -207,6 +207,9 @@ 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.
 cargo run -- build crate --local /path/to/source
 ```
 

From ee7934b46e2524451b91c456c7ba1c5a18d98784 Mon Sep 17 00:00:00 2001
From: Jonas Pleyer <jonas.pleyer@fdm.uni-freiburg.de>
Date: Thu, 29 Feb 2024 01:17:41 +0100
Subject: [PATCH 2/3] add snippet to explain in more detail how to package
 crate

---
 README.md                |  1 +
 docs/build-workspaces.md | 23 +++++++++++++++++++++++
 2 files changed, 24 insertions(+)
 create mode 100644 docs/build-workspaces.md

diff --git a/README.md b/README.md
index 8d5959afd..4d59dc5e7 100644
--- a/README.md
+++ b/README.md
@@ -210,6 +210,7 @@ cargo run -- build world
 # 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
 ```
 
diff --git a/docs/build-workspaces.md b/docs/build-workspaces.md
new file mode 100644
index 000000000..488ad38a8
--- /dev/null
+++ b/docs/build-workspaces.md
@@ -0,0 +1,23 @@
+# Build Workspaces
+## When do we need this?
+Many workspace packages do not need manual intervention and can be built simply by executing the commands listed in the main [Readme.md](../Readme.md) file.
+However, some workspaces require an additional step.
+This is the case when values such as 
+```toml
+version.workspace = true
+```
+are inherited from the workspaces `Cargo.toml` configuration file.
+
+## Fix
+To build documentation, rustdoc requires a fully specified package but rustdoc does not understand workspaces which are only defined in cargo.
+Thus our crate needs to be packaged by cargo before running the documentation.
+This step will replace all of the `value.workspace = true` statements with their respective values.
+```
+cargo package
+```
+This will emit a packaged  crate into the `target/package/your_crate_name-version` folder.
+Now the commands specified in [Readme.md](../Readme.md) can be executed targeting this folder.
+```
+cargo run -- build crate --local /path/to/source/target/package/your_crate_name-version/
+```
+

From 5483674c1da7c03e6c1db66bbec6a07d47674990 Mon Sep 17 00:00:00 2001
From: Jonas Pleyer <jonas.pleyer@fdm.uni-freiburg.de>
Date: Thu, 29 Feb 2024 01:34:08 +0100
Subject: [PATCH 3/3] add MWE for problematic workspace package when building
 locally

---
 docs/build-workspaces.md | 70 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/docs/build-workspaces.md b/docs/build-workspaces.md
index 488ad38a8..66d6717d0 100644
--- a/docs/build-workspaces.md
+++ b/docs/build-workspaces.md
@@ -21,3 +21,73 @@ Now the commands specified in [Readme.md](../Readme.md) can be executed targetin
 cargo run -- build crate --local /path/to/source/target/package/your_crate_name-version/
 ```
 
+## Full MWE
+To showcase when such problems can occur, take a look at the following example.
+### Structure
+```bash
+$ tree
+.
+├── Cargo.toml
+├── my_lib
+│   ├── Cargo.toml
+│   └── src
+│       └── lib.rs
+└── README.md
+
+3 directories, 4 files
+```
+The actual contents of `my_lib` do not matter, only the two configuration files.
+```
+$ cat Cargo.toml
+[workspace]
+members = [
+        "my_lib",
+]
+
+[workspace.package]
+version = "0.1.0"
+```
+and
+```bash
+$ cat my_lib/Cargo.toml
+[package]
+name = "my_lib"
+version.workspace = true
+
+[dependencies]
+```
+
+### Building
+
+The build command
+```bash
+cargo run -- build crate -l path/to/docs_rs_workspace_package/my_lib
+```
+fails with
+```bash
+Error: Building documentation failed
+
+Caused by:
+    Building documentation failed
+
+Caused by:
+    invalid Cargo.toml syntax
+```
+which makes sense due to
+```toml
+version.workspace = true
+```
+
+### Fix
+However when running the following sequence of commands
+```bash
+# Run this in the directory of docs_rs_workspace_package
+cargo package -p my_lib
+```
+and then building again
+```bash
+# Run this from the docs.rs repo
+cargo run -- build crate -l path/to/docs_rs_workspace_package/target/package/my_lib-0.1.0
+```
+then the build succeeds.
+