漂亮README

一个简单的crate，包含一个过程宏，可轻松将输入的README.md文件适配为Rustdoc使用。目标是使编写一个在GitHub（或另一个存储库位置）和Docs.rs（或本地文档构建）上看起来和功能（链接、示例等）都完美的README.md文件变得非常简单。

允许运行任何包含Rust代码块示例作为doctests，即使它们包含没有指定函数或返回Result类型的问号（?）操作符。还可以将给定的文档URL替换为另一个URL，这可以用于将构建文档中的绝对链接替换为相对链接。

最初是为tyche crate编写的。

示例

给定输入README.md文件

# Some Cool Crate!

Some Cool Crate defines the [StuffDoer] type for other things to do stuff with. Wow!

## Examples

```rust
use some_cool_crate::StuffDoer;

// Do some stuff
StuffDoer::do_stuff();

// Do some stuff, but fallibly
StuffDoer::do_stuff_that_might_fail()?;
```

## License

IDK, do whatever you want.

与库的lib.rs

#![doc = pretty_readme::docify!("README.md", "https://docs.rs/super-cool-crate/latest/super-cool-crate/", "./")]

pub struct StuffDoer;

impl StuffDoer {
	pub fn do_stuff() {
		// we lied, we do nothing here
	}

	pub fn do_stuff_that_might_fail() -> Result<(), SomeError> {
		// we lied again, nothing will ever fail
		Ok(())
	}
}

#[derive(Debug)]
pub struct SomeError;

impl std::fmt::Display for SomeError {
	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
		write!(f, "Some error occurred")
	}
}

impl std::error::Error for SomeError {}

此示例实现以下功能

• 允许在README中的示例代码块作为doctests运行，即使使用了问号（?）操作符且没有显式函数或Result类型，即使使用了问号操作符，也能保持示例整洁，在GitHub上查看时也能保持整洁
• 将StuffDoer类型文档页面的完整URL替换为相对URL，以便在docs.rs或本地文档构建中查看时始终链接到当前查看的版本

贡献

尽管这个crate是为了一个相当具体的目的而制作的，但如果您有想法，贡献是完全受欢迎的！尽量保持PR相对较小（每次一个功能/修复/重构）并描述性地措辞您的提交。

许可证

Pretty Readme根据LGPLv3许可证授权。