Crates.io: Projects in workspace don't display readme.

[dragostis]

Both openssl and pest don't have their readmes visible on crates.io. It seems like readme = "../README.md" does not work.

[kureuil]

This seems to be pretty hard to handle to me. Because each crate in a workspace is compressed into its own archive (using its Cargo.toml) as the root, I'm not sure about how it could embed a file that is one folder up without putting it at the root at the archive and rewriting the readme path in the manifest.

[dragostis]

@kureuil How does serde do it since it only has a symlink to the README.md, whose path is literally ../README.md?

[kureuil]

I'd say that the symlink is replaced by the actual file when you run cargo
publish.

This way the readme path in the manifest doesn't reference a file that is
not contained in the crate.

Le 21 août 2017 8:21 PM, "Dragoș Tiselice" [e-mail] a
écrit :

@kureuil https://github.com/kureuil How does serde do it since it only
has a symlink to the README.md, whose path is literally ../README.md?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/rust-lang/crates.io/issues/984#issuecomment-323816237,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ABN2R7Ju4u_5C5abHNidbC51QpXB3SWnks5sacqagaJpZM4O8jNz
.

[dragostis]

Then I don't see why it cannot do the same in the other case.

[kureuil]

Because that would involve creating a file outside of the crate folder.

We can render serde's README because their mainfest file references README.md, which is a valid file that happens to be a symlink to ../README.md.
We can't render openssl's README because their manifest file references ../README.md, which is not contained in the crate file and thus cannot be analyzed by crates.io.

See:

• serde's crate file contents: https://docs.rs/crate/serde/1.0.11/source/Cargo.toml
• openssl's crate file contents: https://docs.rs/crate/openssl/0.9.17/source/Cargo.toml

We can see that a README.md file is present in serde's file hierarchy, while there isn't one in openssl's one.

The solution here is to not explicity reference ../README.md in your manifest, and instead create a README.md symlink to ../README.md and reference the symink in your manifest, just like serde.

[dragostis]

@kureuil Of course, but that will make GitHub render it again. Which means I'll have to rename the file. I guess this is a decent solution, but might it be an interesting idea to have a separate directory inside of the crate archive where such files can be stored?

[sfackler]

https://github.com/sfackler/rust-openssl/commit/ca40c2e6a3b4c09698478ff54da8bdf8f857d134

[locks]

Both of the crates mentioned in the original post seem to work nowadays.
Does someone have a reproduction of this problem, or can this issue be closed?

[flying-sheep]

They both circumvented it by symlinking. I think making '../README.md' work would be cleaner. One could e.g.

1. test if the readme is outside the to-be-archived directory
2. check if copying it inside of the to-be-archived directory would overwrite a file (just to be paranoid)
3. copying the readme file into the to-be-archived directory and
4. adapting the path to the readme.

[stanislav-tkach]

As far as I can see, crates.io can now render a readme even if it is located outside of the crate directory. The related issue: https://github.com/rust-lang/cargo/issues/5911

[jtgeibel]

Thanks for linking the cargo issue. As I understand the current status, cargo now sends the readme to be rendered by crates.io. The remaining issue is that the uploaded crate does not include the readme within it.

I'm going to close this issue in favor of the cargo issue, because there isn't anything we can change server side to modify this behavior.