-
Notifications
You must be signed in to change notification settings - Fork 2.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Run doc tests on README #383
Comments
I imagine people might have many markdown files which are documentation and contain examples; it would be nice to be able to specify additional |
Sounds like a good idea! We could at least start out with a README and expand it with a manifest key later on. |
Some concerns were raised in #445 which are applicable to this as well. |
The question is: how will README interact with the Cargo registry? Currently the examples are in the README file mainly because it's easy to read when you discover a library on github. But if the registry automatically provides the rustdoc output of each package, then I think that the basic examples should simply be in the crate root documentation, just like the standard |
I'd like to have this feature. Broken README code is worse then broken code in the crate docs, as this is the first place where people go to. Outdated READMEs are even worse of an issue, a thing tested READMEs elegantly circumvent. Also, I prefer writing README code, as crate documentation is a bit cumbersume and hard to read in source, given the amount of comment characters it needs. Rust code can be highlighted on github and ignored by using:
(this currently is parsed correctly, but not properly picked up. As a middleground, my suggestion is to allow listing additional documents to test with rustdoc in the Manifest and generate a Cargo.toml including "README.md" in that list per default. This raises awareness of the feature, but ultimately leaves the user in control. |
I'd like to push this one, I just ran into precisely the problem that my README examples were the only ones broken. |
+1 |
I would love this. Concerns can be addressed by making the feature opt-in (and maybe also with attribute metadata, but I don't know markdown well enough to know if that's a thing). |
👍 |
Always forget to update README.md in my projects 👍 |
potentially relevant: rust-lang/rfcs#1990 |
The external docs include feature (RFC 1990) is definitely the best way to go about this, IMO. You could include your README.md as the docs for a hidden item and then |
In case anyone missed it, I've got a proof-of-concept project for using the This can be done conditionally under a Cargo feature so it doesn't require nightly to test. |
cargo test doesn't currently pick up doctests in README.md, tracking issue: rust-lang/cargo#383
I'd like to revive this. I've seen projects do CI on their README by manually running |
I've been happily using doc-comment to do this. |
For anyone who doesn't want to add another dependency, this little macro works perfectly: #[cfg(doctest)]
mod test_readme {
macro_rules! external_doc_test {
($x:expr) => {
#[doc = $x]
extern {}
};
}
external_doc_test!(include_str!("../README.md"));
} |
158: tests: test readme r=jmesmon a=jmesmon Using doc-comment. See rust-lang/cargo#383 Co-authored-by: Cody P Schafer <[email protected]>
The code to include the readme as a doctest is from [this rust ticket](rust-lang/cargo#383 (comment)).
The code to include the readme as a doctest is from [this rust ticket](rust-lang/cargo#383 (comment)).
The README now includes a code sample (and [this][1] technique is used to test it). [1]: rust-lang/cargo#383 (comment)
Thanks to rust-lang/cargo#383 (comment) for the assist.
Thanks to rust-lang/cargo#383 (comment) for the assist.
We have several code snippets in the README.md file, some ignored (because it's irrelevant to compile and run them), some not. They are currently not tested by "cargo test". Let's include the file as part as the documentation for the library, so that these examples are automatically tested. Note that the file name and lines indicated in the output for the tests are not relevant to the README.md file. Reference: https://github.com/rust-lang/rust/blob/5f4e0677190b/src/doc/rustdoc/src/write-documentation/documentation-tests.md#include-items-only-when-collecting-doctests Note that there's a related issue in cargo to add native support for tests on README's examples: rust-lang/cargo#383 Signed-off-by: Quentin Monnet <[email protected]>
We have several code snippets in the README.md file, some ignored (because it's irrelevant to compile and run them), some not. They are currently not tested by "cargo test". Let's include the file as part as the documentation for the library, so that these examples are automatically tested. Note that the file name and lines indicated in the output for the tests are not relevant to the README.md file. Reference: https://github.com/rust-lang/rust/blob/5f4e0677190b/src/doc/rustdoc/src/write-documentation/documentation-tests.md#include-items-only-when-collecting-doctests Note that there's a related issue in cargo to add native support for tests on README's examples: rust-lang/cargo#383 Signed-off-by: Quentin Monnet <[email protected]>
We have several code snippets in the README.md file, some ignored (because it's irrelevant to compile and run them), some not. They are currently not tested by "cargo test". Let's include the file as part as the documentation for the library, so that these examples are automatically tested. Note that the file name and lines indicated in the output for the tests are not relevant to the README.md file. Reference: https://github.com/rust-lang/rust/blob/5f4e0677190b/src/doc/rustdoc/src/write-documentation/documentation-tests.md#include-items-only-when-collecting-doctests Note that there's a related issue in cargo to add native support for tests on README's examples: rust-lang/cargo#383 Signed-off-by: Quentin Monnet <[email protected]>
We have several code snippets in the README.md file, some ignored (because it's irrelevant to compile and run them), some not. They are currently not tested by "cargo test". Let's include the file as part as the documentation for the library, so that these examples are automatically tested. Note that the file name and lines indicated in the output for the tests are not relevant to the README.md file. Reference: https://github.com/rust-lang/rust/blob/5f4e0677190b/src/doc/rustdoc/src/write-documentation/documentation-tests.md#include-items-only-when-collecting-doctests Note that there's a related issue in cargo to add native support for tests on README's examples: rust-lang/cargo#383 Signed-off-by: Quentin Monnet <[email protected]>
We have several code snippets in the README.md file, some ignored (because it's irrelevant to compile and run them), some not. They are currently not tested by "cargo test". Let's include the file as part as the documentation for the library, so that these examples are automatically tested. Note that the file name and lines indicated in the output for the tests are not relevant to the README.md file. Reference: https://github.com/rust-lang/rust/blob/5f4e0677190b/src/doc/rustdoc/src/write-documentation/documentation-tests.md#include-items-only-when-collecting-doctests Note that there's a related issue in cargo to add native support for tests on README's examples: rust-lang/cargo#383 Signed-off-by: Quentin Monnet <[email protected]>
Three years later, here's an update to #383 (comment): For anyone who doesn't want to add another dependency, this works: #[cfg(doctest)]
#[doc = include_str!("../README.md")]
struct ReadMe; Note, it can't be in Your IDE may gray it out as code not being used, because of the #[doc = include_str!("../README.md")]
struct _ReadMe; I chose to put that in Improvements welcome. |
And here's the official documentation for it: https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html#include-items-only-when-collecting-doctests Considering that many README.md's likely contain broken code and not-even-intended-to-be-complete examples, is this amount of opt-in good enough; can this issue be closed? |
Hi, I didn't knew that this is an intended feature and by-chance found a bug. (unsure) As here you can see, I ran TL;DR + Conclusion: So, I think it is wrongly reporting that the issue is in Please, let me know if I am somehow mistaken and that this is indeed the expected behavior. |
Its hard to tell whats going on without a reproduction case. I'm assuming you are including your README in the documentation for your lib. I have also seen line numbers be a bit strange in these scenarios. I believe rustdoc is what determines all of that. |
If you don't mind may I share the link to the repository? So, that you can reproduce it yourselves. Also, I myself think that wrong line numbers are an issue then. (Yes, README is included.) |
cargo test
could run (the equivalent of)rustdoc --test README.md
, since people often have a basic example in it.See also
cargo doc
could support building/testing standalone markdown files #739Past efforts
The text was updated successfully, but these errors were encountered: