1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
//! Crate's macros.
/// Include Markdown file as given name module.
///
/// ## File path
///
/// Argument file path is relative path from the crate root directory.
///
/// Note, this behavior is different from [`include_str`] which uses
/// relative path from calling file.
///
/// ## Fragment key
///
/// You can specify a fragment key after the file path.
///
/// - If the key is not specified, all document is included.
/// - If the key is `#`, first level 1 section is included.
/// - If the key is `#some-id`, the fragment section is included.
///
/// ## Heading Level adjust
///
/// Heading level adjust works with [fragment key](#fragment-key).\
/// This adjust target heading of fragment key to level 1.\
/// And adjust levels of subsequent headings relative to it.
///
/// ## Link copy guard
///
/// `!copy_guard` is a special reference definition with this crate.\
/// All URLs of links in Markdown, including the guard path, are disabled.
///
/// This is primarily intended for use in `README.md`, like the following.
/// This ensures that the links in rustdoc are valid even if `docs.rs`
/// is unavailable. Additionally, `cargo doc` will report warning if
/// `my_func` is removed.
///
/// ```text
/// # my_crate
///
/// Welcome to my crate.
///
/// This crate has only one function [`my_func`].
///
/// [!copy_guard]: https://docs.rs/my_crate/latest/
/// [`my_func`]: https://docs.rs/my_crate/latest/my_crate/fn.my_func.html
/// ```
///
/// # Examples
///
/// \- `src/lib.rs`
///
/// ```rust, ignore
/// //! Welcome to my crate API document.
/// #![doc = doc::sub::examples::all!()]
///
/// doc_file!(doc, "README.md#");
///
/// use rustdoc_copy::prelude::*;
///
/// pub fn some_func() -> i32 {
/// 42
/// }
/// ```
///
/// \- `README.md`
///
/// ````text
/// # my_crate
///
/// This crate is ...
///
/// ## Examples
///
/// ```rust
/// use my_crate::some_func;
///
/// assert_eq!(some_func(), 42);
/// ```
/// ````