cargo
cargo copied to clipboard
rust-lang
`cargo doc` could support building/testing standalone markdown files
E.g. project specific guides/tutorials, like rust-lang/rust itself.
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:
- What is the status on this? Has anything been done?
- What would need to be done to make it work?
I'm not aware of anything that's being done.
I don't actually think pandoc is used anymore, all that is stale.
Ah, interesting. I'll go read the makefile; if nothing else I can submit a PR to update that.
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.
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. :stuck_out_tongue:
I've thought about this a bit in the past, and the general idea is something like:
- On
cargo doc, Cargo will automatically crawl/doc(in the project root) for*.mdfiles - Each markdown file will be passed through
rustdocand rendered, maintaining the same basic structure as thedocfolder itself - On
cargo testCargo will automatically runrustdoc --testover all markdown files
Feel free to reach out to me with any questions!
@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.
@alexcrichton and @steveklabnik, how should this interact with (including just ignoring it) rustbook?
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!
Yeah, I feel the same as @alexcrichton, basically. Same with 'dont worry about Rustbook'.
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).
Would these generated HTML files (optionally?) include the crate index side bar and the search bar?
While I haven't had a chance to dig in yet courtesy of start-of-the-semester busyness, my tentative plan is to make those available, yep. Presumably with an optional argument to the command, similar to how you can specify a CSS file or other HTML to include now.
Just a quick update: I've spent several hours last week and expect to spend several more this weekend familiarizing myself with the way cargo doc currently works so that when I start implementing, it'll be in line with how things presently work.
@chriskrycho awesome! Feel free to ask any questions here or on IRC if you run into any speed bumps!
Alas: no. School and work this semester have taken up more time than I’ve expected. It is still very much on my radar, but of course if someone else gets to it first… I won’t argue.
Just checking in: nobody has started work on this in the meantime, yeah? Maybe I should.
No, I had an abortive start back in October or so, but nada since then. If you give it a go, I’d be happy to chip in.
Just as a consideration, how would we name these markdown files? Tread them the same way as .rs files so that I pub mod documentation for a documentation.rs? There are tones of projects on github that have Readme.md files in subdirectories. What about (when this is reopened) rustdoc automatically includes Readme.md files in module folders as module level documentation?
@chriskrycho BTW: I would also love to see this take off, so if you want to collaboratively start working on this again? I'm in.
@hoodie in general, the idea would be that you'd write whatever.md and that will generate a whatever.html.
I'm skeptical of making readmes into module-level documentation, but possibly as an index.html.
I though, only explicitly if the Readme.md is right next to a mod.rs, per se.
Has there been any progress on this recently? It'd be really useful if I could write up some general documentation for my crates in a /doc directory and have it included in the generated html automatically.
I theory this shouldn't be a difficult feature to add to cargo doc. You could add a function that'll walk the /doc directory (or /src/doc, or some other place, potentially specified in your Cargo.toml) and it'll use rustdoc --input-format md to turn any markdown files it finds into html.
From there I imagine it'd be fairly simple to alter the template used to build the sidebar to include the generated documentation.
If someone knows how cargo doc works under the hood and is able to point me in the right direction, I wouldn't mind giving it a go.
@Michael-F-Bryan not a lot of activity now that I know of, but the integration may not be the easiest unfortunately. I think we'll need to plumb this through all the dependency tracking as well to ensure we don't re-document files too often. That is:
- We'll want to add support to
cargo::ops::cargo_rustcfor building standalone docs- This has all the support for "fingerprints", tracking when files change
- Also has support for parallelization
- Automatic support for cross compiles, custom flags, etc
- This'd likely be done by dynamically generating a list of rules based on the files on the filesystem into the backend.
Other than that, may not be too hard to hook up though!
I'm a bit confused about what the docs mean regarding standalone markdown files if they're not referring to this feature. Am I missing something obvious?
That's what I thought as well. I tried putting a markdown file in my src directory (with the % title line) and then running cargo doc, but it looks like cargo completely ignores the file.
Minimal example:
$ cd /tmp
$ cargo new dummy && cd dummy
$ cat > src/extra_docs.md << EOF
% A Title
# Heading 1
Lorem ipsum...
EOF
$ cargo doc --open
$ find ./target/doc -name "*extra_docs*"
In this case I'd expect the extra_docs page to be compiled to html and then linked in with the rest of my documentation. You can compile markdown manually with rustdoc, which is probably what the documentation is referring to, but that won't link it in with the rest of your docs or apply any styling and cargo doesn't have any (easy) ways of including extra pages purely for documentation.
This was done using nightly rustc and cargo.
https://www.reddit.com/r/rust/comments/5crpfy/announcing_cargo_externaldoc/