cargo doc works but cargo publish fails due to include_str! in lib.rs with relative path

[softstream-link]

Problem

I have multi module project with following members
Cargo.toml

[workspace]
members = ["core", "nonblocking", "blocking", "bindings/python"]
....

Which includes readme's in the rust doc like so
nonblocking/src/lib.rs

#![doc = include_str!("./../../readme.md")]
....

I am able to run cargo doc --open which creates the website and opens the documentation correctly, however then trying to publish the nonblocking crate it fails saying.
Error from `cargo publish -p links_nonblocking --dry-run

error: couldn't read src/./../../readme.md: No such file or directory (os error 2)
 --> src/lib.rs:1:10
  |
1 | #![doc = include_str!("./../../readme.md")]

Steps

1. git clone from this branch - https://github.com/softstream-link/links/tree/v2
2. try

• PASSES : cargo doc ; # will have the readme.md successfully included
• FAILS : cargo publish -p links_nonblocking --dry-run ; # will fails saying it can't find the include_str path.

Possible Solution(s)

Do these two commands use two different cwd when running for each modules? if so what is the workaround this?

Notes

na

Version

cargo 1.75.0 (1d8b05cdd 2023-11-20)
release: 1.75.0
commit-hash: 1d8b05cdd1287c64467306cf3ca2c8ac60c11eb0
commit-date: 2023-11-20
host: aarch64-apple-darwin
libgit2: 1.7.1 (sys:0.18.1 vendored)
libcurl: 7.87.0 (sys:0.4.68+curl-8.4.0 system ssl:(SecureTransport) LibreSSL/3.3.6)
ssl: OpenSSL 1.1.1u  30 May 2023
os: Mac OS 13.3.0 [64-bit]

[weihanglo]

@softstream-link, does CARGO_PKG_README help? #11645 (comment)

[epage]

To add to what was said, iirc if you set package.readme to that file in the root, cargo publish will move that file to be within your .crate, ensuring cargo publish works

[epage]

Do these two commands use two different cwd when running for each modules? if so what is the workaround this?

cargo doc, cargo build, etc run directly on your file system and can look up files anywhere (maybe we can restrict that with #5720).

When you run cargo publish / cargo package, they grab all of the files from within the directory that contains your Cargo.toml, according to package.include and package.exclude. The verification build takes your .crate file. expand it into a separate location and build it to make sure what you upload will work, regardless of machines. So if the file doesn't get included (e.g. its outside of the directory tree) then its not available for the verification build.

[softstream-link]

My problem is that I include a dozen different readmes which are otherwise chapters in a different context and some are in root and some are elsewhere. Is there a consistent way of including them all in a way that makes both docs and publish work correctly?

[epage]

At this time, there is not a way to remap repo paths outside of your package root to be within your package root during publish.

Potential options

• Have all of the readmes in their chapter location and have package.readme reach into those packages
• (might work) Have the package that contains the chapters in the root of your repo so it can pull in files from the different packages. Might require use of package.include. Unsure if we do anything extra that prevents this.

[weihanglo]

If symlink is an option, you could also symlink all content to the directory of the member package to make them package-local accessible.

[softstream-link]

At this time, there is not a way to remap repo paths outside of your package root to be within your package root during publish.

Potential options

1. Have all of the readmes in their chapter location and have package.readme reach into those packages
2. (might work) Have the package that contains the chapters in the root of your repo so it can pull in files from the different packages. Might require use of package.include. Unsure if we do anything extra that prevents this.

I have tried playing around with the package include, your second option, however unsuccessfully. I think it is due to the fact that include can only be used in a format that is relative to the Cargo.toml being package and not the virtual "parent" module's manifest.

My structure is as follows:

root
|- module1 - Cargo.toml # module manifest
|- module2 - Cargo.toml # module manifest ---> I am trying to publish this module and include readme using include_str! from the root.
|- readme/src/**/*.md $ all the readme files
|- Cargo.toml # workspace manifest

I have tried specifying package.include in the workspace or the module manifest but it just does not seem to match any content outside of the module's Cargo.toml

I did not quite understood your first option. Are you saying that I can specify more than one readme using package.readme ? I read the docs but could not figure out how to do that.

[softstream-link]

tent to the directory of the member package to make th

This seems to be the only option for me since all the readme is in the root of the repo and I can symlink readme content to the necessary module.