Rustdoc feature request

documentation
1

Hi all, I have been very excited about the ability to use README's as module documentation ever since Rust 1.54 landed and #![doc = include_str!("README.md")] became available. However when I started trying to actually use this pattern, I ran into some problems. Basically, I would like all of the following to work:

  • To have code samples that get compiled and run by Rustdoc (in the README)
  • To have syntax highlighting work as expected when rendering as plain markdown (e.g. github-flavored markdown).
    • This should include code that is marked no_run or ignore

As of now, these goals are at odds with one another. For example, none of the following types of code fences will give me the results I want:

```
```no_run
```ignore

Each of these is interpreted by rustdoc to mean "Rust code here" and to either

  • Compile and run
  • Compile only
  • Syntax highlight only

respectively, however on other markdown renderers these will not be interpreted to mean Rust code is inside.

I am wondering whether it'd be possible to add aliases to each of these code fences so that these all work:

  • Compile and run Rust
```
```rustdoc
  • Compile and syntax-highlight as Rust
```no_run
```rustdoc_no_run
  • Syntax highlight as Rust, applying rustdoc formatting rules (e.g. hiding lines beginning with #)
```ignore
```rustdoc_ignore
  • Treat as non-rust text
```text
```rustdoc_text

The objective with these is that while writing module documentation in README files, one can use the rustdoc_* style code-fence info-strings, and we can hopefully push for popular markdown parser/renderers to treat these the same way that rustdoc does. This would allow folks to write code snippets in READMEs that get compiled and tested just like any other rustdoc test, which I think would be awesome.

What does everybody think about this? I'm interested in hearing opinions, whether this should or shouldn't be done, should be done differently, or whether there are any tips on a path forward with integrating with the greater markdown ecosystem.

1 Like
2

Source? I use ```rust fences all of the time and they work fine.

In fact, I use ```rust, ignore, ```rust, no_run, etc., which provide both language-rust highlighting in pure markdown plus syntax highlighting engines and the desired behavior from rustdoc.

With GitHub at least, this isn't happening. The burden of proof for even an extension addition is far too high (even when actively mangling data). Not to mention if you wanted to add stripping of # prefixes, which is an entirely new feature to GFM.

1 Like
3

Ah, you're right. This is one of those assumptions was stuck in my head when I typed this (I had even tested this earlier and seen this work!), I've updated the original post.

I definitely figured that the "hiding # lines" part would be quite a stretch, so I suppose we should focus on the code-fence aliases. I can't imagine that it would be too hard to add those in the rustdoc implementation, and it shouldn't interfere with anything else, should it? This seems like one of those things where we can enable extension-points, but it requires cooperation from other parts of the ecosystem to actually make use of them.

I suppose I'm still hopeful about the potential here, and if there's anything that could be done on this end to make external integrations like this possible and if there is no downside to doing it, I'd be interested in making it happen. I imagine this is something I could try implementing it if it was agreed on.

4

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.