Expand description
The readme-sync
crate makes it easy to add an integration test
that checks that your readme and crate documentation are synchronized.
§About
This crate provides several abstractions for readme and documentation front page content
as well as multiple readme and documentation parsing and transformation functions.
With them, readme and documentation can be converted
to a set of markup nodes that are expected to be the same.
Their equality can be checked with the assert_sync
function,
which also provides useful diagnostic messages about the differences found.
Documentation parser accepts not only inner doc-comments (//!
) but also
inner doc-attributes (#[!cfg(...)]
and #[!cfg_attr(...)]
).
This is useful when some doc-tests require certain features to compile and run.
§Usage
First, add the following to your Cargo.toml
:
[dev-dependencies]
readme-sync = "0.3.0"
Then add an integration test using the necessary readme and docs modifiers,
and check their synchronization using the assert_sync
function.
The example below is used to test the synchronization of the readme and documentation of this crate. You can copy it and follow the diagnostic messages to adjust the modifiers used and to correct your readme and documentation.
#[cfg(test)]
#[test]
fn readme_sync_test() {
use readme_sync::{assert_sync, CMarkDocs, CMarkReadme, Config, Package};
use std::borrow::ToOwned;
let package = Package::from_path(env!("CARGO_MANIFEST_DIR").into()).unwrap();
let config = Config::from_package_docs_rs_features(&package);
let readme = CMarkReadme::from_package(&package).unwrap();
let docs = CMarkDocs::from_package_and_config(&package, &config).unwrap();
let readme = readme
.remove_badges_paragraph()
.remove_documentation_section()
.remove_codeblock_tag("no_sync")
.disallow_absolute_repository_blob_links()
.unwrap()
.use_absolute_repository_blob_urls()
.unwrap();
let docs = docs
.increment_heading_levels()
.add_package_title()
.remove_codeblock_rust_test_tags()
.use_default_codeblock_rust_tag()
.remove_hidden_rust_code()
.map_links(
|link| match link {
"CMarkDocs::map_links" => "struct.CMarkDocs.html#method.map_links".into(),
link => link.into(),
},
"workaround for intra-doc links",
)
.disallow_absolute_package_docs_links()
.unwrap()
.use_absolute_package_docs_urls()
.unwrap();
assert_sync(&readme, &docs);
}
Note that both cargo build
and cargo test
enable features from dev-dependencies,
so if you want to test your crate without them (for example in no_std
environment)
you can use readme-sync
with default-features = false
.
See this
FAQ section for more details.
§Feature Flags
codemap
(enabled by default): Enablescodemap
dependency and required forassert_sync
and other diagnostic functions.codemap-diagnostic
(enabled by default): Enablescodemap-diagnostic
dependency and required forassert_sync
and other diagnostic functions.glob
(enabled by default): Enablesgloc
dependency and required for badges detection and methods likeCMarkReadme::remove_badges_paragraph
.platforms
: Enablesplatforms
dependency and methodConfig::with_target_arch_os_env
.proc-macro2
(enabled by default): Enablesproc-macro2
dependency withspan-locations
feature that allows the crate to show the errors location for source Rust files.pulldown-cmark
(enabled by default): Enablespulldown-cmark
dependency and required for almost everything except manifest and documentation parsing and some utility functions.serde
(enabled by default): Enablesserde
dependency and required for manifest deserializing.syn
(enabled by default): Enablessyn
dependency and required for documentation parsing.thiserror
(enabled by default): Enablesthiserror
dependency and required by all functions and methods that can return errors.toml
(enabled by default): Enablestoml
dependency and required for manifest parsing.
§Other crates
cargo-sync-readme
: generates readme section from documentation. It does not support doc-attributes and does not provide diagnostics for differences found. But if you just need to synchronize readme and docs text or check if they are synchronized it might be a better choice.version-sync
: crate makes it easy to add an integration test that checks that README.md and documentation are updated when the crate version changes.
§FAQ
§Are rust intra-doc links supported?
Currently intra-doc link resolution is not supported.
References to structures in the documentation can be changed with CMarkDocs::map_links
.
The pulldown cmark also requires the link address to be specified.
§Why is the example integration test so long and there is no function that would do it all at once?
Readme and documentation transformations are very different between different crates and the API of this crate is not yet stabilized.
At the moment, however, it supports extensive customization. You can specify the paths to readme and docs, their contents, the features and transformations used, and use your own transformations.
So any feedback is welcome!
§Why use syn
instead of just parsing documentation comments?
Because of cfg
and cfg_attr
that are useful for documentation tests
that require some specific features and can only be compiled with them.
§Why Markdown instead of text comparison?
It simplifies the Markdown transformations. Transformations are necessary, because of some differences between readme content and documentation front page including: the presence of a crate name, different heading levels, the presence of badges, different relative url root, etc.
§License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
§Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Structs§
- A
CMarkItem
s container storing a list of events with multiple transformation functions. - Parsed documentation Markdown with optionally specified package path and package manifest.
- Parsed readme Markdown with optionally specified package path and package manifest.
- Event’s region of source text.
- Storage for codemap and corresponding codemap files.
- Codemap span labels temporary storage used to create diagnostic messages.
- A set of enabled named and key-value configuration options.
- Parsed documentation text chunk.
- Documentation text chunk span start and end.
- File path and its contents.
- Parsed
.rs
file documentation. - Package manifest.
- Package manifest
[[bin]]
section. - Manifest metadata that customize docs.rs builds.
- Package manifest
[lib]
section. - Package manifest
[package]
section. - Readme and docs match failed diagnostics and codemap files.
- A struct contains package manifest and its root path.
- The pair of a source and the corresponding target text remap range.
Enums§
- An error which can occur when locating the binary file path by the specified target name.
- An error which can occur when building documentation from attribute.
- An error which can occur when building documentation from meta-attribute.
- An enum that store Markdown event, its origin, and modifications. The event modification tree is stored to improve error messages.
- An error which can occur when creating readme from package.
- An error which can occur when checking readme and docs for equality.
- An error which can occur when checking for disallowed link prefixes.
- An error which can occur when evaluating configuration predicate.
- An error which can occur when creating file documentation form a given file.
- An error which can occur when reading a file from the specified path.
- The optional Manifest
readme
field that allows string or boolean value. - Markdown parser text source which may be either readme file contents or package target parsed documentation.
- An error which can occur when parsing manifest from toml file.
- An error which can occur when reading manifest from the specified file path.
Traits§
- A helper trait to create an event as modified from other events.
- A helper trait to mark events as removed.
- A helper trait to mark an event with the specified note.
Functions§
- Asserts that the given readme and docs are the same.
- Returns a Vec of populatar badge url patterns.
- Builds documentation from the specified attribute.
- Builds documentation from the specified compile-time structured attribute.
- Returns
Ok(())
if the given readme and docs are the same, andErr(CheckSyncError)
otherwise. - Returns a slice of currently known tags used by
cargo test
in Markdown fenced code blocks. - Evaluates configuration predicate.
Type Aliases§
- A
CMarkItem
s container iterator.