mdBook icon indicating copy to clipboard operation
mdBook copied to clipboard

Add support for doc_comment_include

Open cor opened this issue 3 years ago • 2 comments

Currently, it is not possible to include rust doc comments as part of an mdBook and render it as markdown. However, this is very useful functionality if you want to reference a part of your documentation in your book.

This PR adds support for #doc_comment_include. It works like this:

{{#doc_comment_include ../../rust-project/src/lib.rs:anchor}}
		// ANCHOR: anchor
		///
		/// example content
		/// lorem ipsum
		///
		/// ### this h3 will be rendered as an h3 in the book
		/// - this list
		/// - will be rendered
		/// - as a list in the book
		///
		// ANCHOR_END: anchor
		pub fn hello_world() { ... }

it works by trimming the whitespace and removing the leading ///

It also supports including part of a doc comment:

		///
		/// this will not be included
		///
		// ANCHOR: anchor
		/// ### but this h3 will be included
		/// and so will this
		///
		// ANCHOR_END: anchor
		pub fn hello_world() { ... }

cor avatar Apr 12 '22 15:04 cor

is it a reference to rust docs or embedding? if references, can we cargo doc and include reference in mdbook? or embeed part of cargo doc result. not sure if PR include will work well - until it works on project level it will behave not so good i think.

dzmitry-lahoda avatar Apr 16 '22 22:04 dzmitry-lahoda

This would be super helpful for my project. Is this going to be merged?

maccesch avatar May 14 '23 23:05 maccesch