From e00048fea44608d6fd30f055f0b9e7865ae4a502 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] 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.
+