Docs.rs and markdown files, bug?

1

Screenshot
Screenshot677×575 69.4 KB

I am observing a behavior that I don't understand in docs.rs, I don't know if I am doing something wrong or if it is a bug.

In a crate that has a markdown file for documentation:
https://docs.rs/crate/neutralts/latest/source/src/doc.rs

If we navigate to:

We can see that the sections are not well generated:

The next section after “code” should be “comment” but it does not appear, the same happens with other sections.

This is the source code for “code”:
https://docs.rs/crate/neutralts/latest/source/doc/bif-code.md

And of what should be the next section:
https://docs.rs/crate/neutralts/latest/source/doc/bif-comment.md

2

Shot in the dark, but have you tried inserting a blank line between your markdown imports? I.e.:

#![doc = include_str!("../doc/bif-code.md")]
//!
#![doc = include_str!("../doc/bif-comment.md")]

Edit: I tried this locally and got this instead:

image
image950×580 37.1 KB

2 Likes
3

The truth is that I have tried everything, now I am going to try to add a horizontal rule at the end of each file, I have seen that the error does not occur when the file ends in a code block, only when there is text at the end.

I'll upload it and see what happens....

I think it is definitely a bug.

4

I don't think it's a bug. Or at least I wouldn't expect my markdown interpreter to handle this case. EOF bytes in a string are not treated as white space characters, which leaves you with the expaned docs of roughly:

See the bif "param" for more information on parameters.\x04{:* comment *:}\n===============
1 Like
5

Adding a horizontal rule at the end of each file solves the problem :slight_smile:

Although the real origin I don't know what it is.

6

Indeed, it is possible that my editor (vscode) does not encode the files correctly, adding or omitting something at the end.

When I have time I will do more tests with a test crate.

7

Yes, editors can do strange stuff with file endings. Setting insert_final_newline = true in your .editorconfig would tell VSCode and most other popular editors to insert a final newline character at the end of the file. Personally I'd find relying on editor configuration too brittle though, so I'd just insert the extra empty lines in my docs between the files with //!, just to be sure a missing newline character at the end of a file doesn't resolve in a bug in my docs.

8

That was a very good observation of yours to look at the file encoding.

Thanks!

1 Like
9

I think the cleanest solution is to add “//!” after each inclusion.

1 Like