`cargo doc` could support building/testing standalone markdown files

[huonw]

E.g. project specific guides/tutorials, like rust-lang/rust itself.

See also

• Run doc tests on README #383
• doc-comment

[chriskrycho]

Right now, it appears that rust-lang/rust uses pandoc to build its docs. It seems like it would be nice to go ahead and get this moving forward so that dependency could be dropped. Two questions, therefore:

1. What is the status on this? Has anything been done?
2. What would need to be done to make it work?

[steveklabnik]

I'm not aware of anything that's being done.

I don't actually think pandoc is used anymore, all that is stale.

[chriskrycho]

Ah, interesting. I'll go read the makefile; if nothing else I can submit a PR to update that.

[steveklabnik]

I was editing but since you replied, I'll make it a new comment:

I don't actually think pandoc is used anymore, all that is stale. It was being used to generate PDF and EPUB, but we don't do that anymore.

You'd basically need a way to tell cargo to invoke rustdoc on MD files, wherever those are. I would suggest maybe a top-level doc directory that any doc/**/*.md gets rustdoc called on would make sense.

[chriskrycho]

One quick question about that: I assume you're meaning top-level doc relative to src, in line with the conventions in e.g. this repository? So a basic crate setup for Cargo would have something like:

/
  Cargo.toml
  README.md
  src/
    lib.rs
    and_modules/
    doc/
      some_stuff.md
      more_stuff.md

Or am I misreading you?

Also, would it make sense to include the README.md file if one is supplied—as the index, perhaps?

Fair warning: it'll probably take me at least a month to implement, if not more, but I'd like to give it a go. I'll probably be inhabiting #rust an awful lot on the weekends I work on it. 😛

[alexcrichton]

I've thought about this a bit in the past, and the general idea is something like:

1. On cargo doc, Cargo will automatically crawl /doc (in the project root) for *.md files
2. Each markdown file will be passed through rustdoc and rendered, maintaining the same basic structure as the doc folder itself
3. On cargo test Cargo will automatically run rustdoc --test over all markdown files

Feel free to reach out to me with any questions!

[chriskrycho]

@alexcrichton, very good.

The reason I was thinking to use /src/doc rather than /doc for the root was because both this repository and the main Rust repository both already have their docs there. As such, my guess was that a fair bit of the community may have their packages likewise structured (because my own first instinct for structuring a project is to check how large, official projects in a language do it). Obviously those can move, though,* and I'm happy to defer to you guys in any case. I'll plan for it to work basically as you outlined.

* I was also hesitant initially because I was remembering repository size problems problems with large moves in Mercurial, but that's not a pain point for Git, so.

[chriskrycho]

@alexcrichton and @steveklabnik, how should this interact with (including just ignoring it) rustbook?

[alexcrichton]

I don't have super strong opinions about /src/doc vs just /doc, but I think we'd prefer to root everything in /doc as it seems to fit the conventions of other projects in other languages. The reason the compiler does this is that the top level /doc is actually where all the generated documentation goes. I... don't actually know why cargo does it!

I'm not currently aware of any conventions externally in the community about this, I wouldn't expect there to be too much buy in to either scheme just yet though.

I'm also fine just not worrying about rustbook for now, conventions can always be adapted!

[steveklabnik]

Yeah, I feel the same as @alexcrichton, basically. Same with 'dont worry about Rustbook'.

[chriskrycho]

Excellent—just wanted to check that box before proceeding. I'll go ahead with the root docs directory! Hopefully starting in on it a bit this week(end).