Add support for AsciiDoc README files

[nlopes]

I'd love if crates.io could render README.adoc files with custom html, just like README.md files do.

I'm happy to put a PR to work on this - I don't think it would be a huge lift as long as a few assumptions I'm making hold true:

• keep the current text_to_html for any files not .adoc or .asciidoc (I'm going to use .adoc from now on for simplicity sake but assume both extensions)
• we don't auto-detect README.adoc files for now, user has to set readme = README.adoc in Cargo.toml
• we auto-detect README.md if readme = isn't set but nothing else
• any extension that is unknown is rendered as is (stays with current behaviour)

I'm looking for any current maintainers/developers of crates.io for objections - barring that I'm willing to just put a PR up.

Additional context:
I've created a set of asciidoc tooling in rust (you can find it in https://github.com/nlopes/acdc which includes a parser and multiple converters). One of those converters is a HTML converter, meaning the code should be very similar to the current markdown one.

I don't intend to add this feature as a piece of self promotion (although I get that it may come across that way) - if there are other parsers/converters you'd prefer I use, happy to do that as well! In the end, the main outcome I'd love to have is crates.io supporting README.adoc files out of the box.

[Turbo87]

I feel like this has been discussed already in the past, but I can't seem to find the discussion anymore 😞

in any case, this is a decision that would not only affect crates.io, but also other downstream systems like docs.rs, thus it would require an RFC (see https://github.com/rust-lang/rfcs/). if you want to move this forward then coming up with an RFC would be the first step and then we can gauge whether the proposal is viable or not.

[nlopes]

Thank you, that's really useful context. 🙏

I feel like this has been discussed already in the past, but I can't seem to find the discussion anymore 😞

I had the same feeling and ended up with the same result 😬 - if anyone finds them, please link them, that would be useful.

but also other downstream systems like docs.rs

Is this out of allowing readme = README.adoc in Cargo.toml or also something else? If it is "just" that, we could simply autodetect the README.adoc in crates.io and leave any assumptions on setting readme = X out of the Cargo.toml.

I'm basically trying to understand if the generated .html file for the Readme section at https://crates.io/crates/<crate> within crates.io has significant consequences further downstream.

[Turbo87]

Is this out of allowing readme = README.adoc in Cargo.toml or also something else? If it is "just" that, we could simply autodetect the README.adoc in crates.io and leave any assumptions on setting readme = X out of the Cargo.toml.

it starts with e.g. https://doc.rust-lang.org/cargo/reference/manifest.html#the-readme-field, which does not currently support README.adoc. crates.io currently does not read the readme file itself, but instead cargo passes the readme content to crates.io as part of the publish process, so support for that would potentially have to be built into cargo, or crates.io would have to be adjusted to read the file itself, but that itself is also a non-trivial change.

[nlopes]

crates.io currently does not read the readme file itself, but instead cargo passes the readme content to crates.io as part of the publish process, so support for that would potentially have to be built into cargo, or crates.io would have to be adjusted to read the file itself, but that itself is also a non-trivial change.

Aah, it's this bit of context I was missing - I thought crates.io would just access the file in the filesystem (for some reason I imagined cargo just uploading all the repo files).

Thank you for the clarification. I'll mull this one over a bit more and also look at what it would take to write a RFC as you suggested. 🙏

[syphar]

docs.rs also currently renders the markdown itself, so adoc would have to be supported there too (or somehow the pregenerated html from crates.io could be used)

[nlopes]

docs.rs also currently renders the markdown itself, so adoc would have to be supported there too (or somehow the pregenerated html from crates.io could be used)

Very useful to know, and I'd be happy to make the change there as well!

[LevitatingBusinessMan]

Any progress on this? There's no RFC yet is there?

[nlopes]

There is not, not yet. I started writing it, and then life happened. Still intend to write this up, it hasn't been forgotten! 🙏

[LevitatingBusinessMan]

lmk if you need help, if you have a draft maybe I can help out