What is offered by this crate

The crate provides include_display_mode_tex! macro that allows to embed tex formulae in documentation generated by rustdoc via cargo doc.

Requirements

#![feature(proc_macro_span)] is absolutely necessary to imitate the behavior of include_str.

Now and future

In its current implementation, include_display_mode_tex! macro merely turns the contents of .tex files into Markdown with raw LaTeX formulae. For the formulae to be displayed as such and not LaTeX syntax, Markdown with raw LaTeX must be rendered with some library, such as KaTeX or MathJax. Such approach burdens the crate with extra complexity of .cargo config and the requirement to build the documentation via cargo doc --no-deps instead of cargo doc but it works.

There is also katex crate that theoretically can allow to render HTML when the documentation is generated. A PR with such functionality will be very welcome (though feature-gated for backward compatibility).

Setting up the crate

The following steps will allow to render .tex included via include_display_mode_tex! with KaTeX renderer:

  1. Create .cargo directory in the crate root (the directory containing Cargo.toml)
  2. In .cargo, add config.toml with the following contents: toml [build] rustdocflags = [ "--html-in-header", "./src/html/docs-header.html" ]
  3. Add these two line to your Cargo.toml toml [package.metadata.docs.rs] rustdoc-args = [ "--html-in-header", "./src/html/docs-header.html" ]
  4. Create ./src/html directory (where ./src/html is a relative path from the crate root)
  5. In ./src/html add docs-header.html with the following contents: ```html

```

Example

```norun use includedisplaymodetex::includedisplaymode_tex;

[doc = includedisplaymode_tex!("./tex/example.tex")]

let s = 0;

```

Notice that the path is relative not to the crate root but to the call site and that the documentation must be built with text cargo doc --no-deps

Sources of inspiration

Other include* macros: * core::include_str * core::include_bytes * core::include * include_dir::include_dir

Special thanks to victe for providing rust-latex-doc-minimal-example

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.


Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.