Rfcs: add option of outputting doc attributes to crates + a doc fetching tool

[steveklabnik]

Issue by thestinger
_Wednesday May 01, 2013 at 22:16 GMT_

_For earlier discussion, see https://github.com/rust-lang/rust/issues/6160_

_This issue was labelled with: A-an-interesting-project, A-docs, A-tools in the Rust repository_

---

Similar to Python's pydoc tool, it should just take a path and resolve it to the correct docstring. The REPL could also take advantage of this with a :help meta-command.

[tomjakubowski]

This seems almost like a dupe of #647, or at least very very closely related.

[steveklabnik]

Yeah, I decided to import them separately, but they're very, very similar.

[vitiral]

As someone who tries to stay as close to the command line as possible, I am going to take this as my first rust project.

My current approach will be:

• write or use a library that can parse rust source and convert it into HashMaps of structs. So if you have:

/// this is a function /// more info about the function /// # Examples /// ``` /// let x = myfun(67) /// ``` fn myfun(x: i32) -> i32 { ... }

You would get a struct like

Doc { 
    name: "myfun", 
    type: Types::Fn, 
    doc: "this is a function\nmore info about the function...", // raw documentation
    sig: "fn myfun(x: i32) -> i32",
    term: &str, // This will be converted to display nicely on a terminal (i.e. color sequences, bold, etc)
    html: &str, // converted to html for other tools
}

Do you know if something like this exists?

• the user will specify their cargo and rust source directory. Whenever the user runs the docsearch tool, it will check that the crate/rustsource versions are the same as before -- if they aren't it will reparse only what changed. Parsed data will be stored in an sqllite database.
  
  
  
  • user queries will be converted to sql queries and parsed, then displayed from the "term" block
  
  

I just finished rustbyexample.com and not having a command line doctool was one of my biggest pain points, so I am going to go forth! Would love any feedback on the design.

[vitiral]

Aaand, obviously I should be using the rustdoc library for the parsing, which is what I will be doing.

I think my larger goal is to be able to integrate with editor tools so that it is fairly painless to display documentation dynamically (including for the library you are currently working on).

[Ruin0x11]

Just letting people know that I'm working on such a tool, oxidoc. Feedback on the current design and contributions are highly encouraged.

[Centril]

Closing in favor of https://www.github.com/Ruin0x11/oxidoc.

[schodet]

oxidoc is no longer maintained as said in the referenced oxidoc issue. It is no longer able to work with the current rust version. Can this issue be reopen?

[rw]

Could we please re-open this issue? Golang wins right now on CLI documentation tooling, and I feel that Rust should at least reach parity with Golang on this.

Since oxidoc is not maintained, I don't see a current solution for viewing documentation in the CLI.

Thanks!

[DrBluefall]

+1 for re-opening this issue. I personally work on a fairly slow computer, and working in a virtual terminal keeps everything fast and snappy. Not to mention that it's just more convenient to have the docs just print to stdout than to get kicked into another application that may or may not be a hassle to use.

stares at elinks

[DarrienG]

I was developing C a little earlier this week and was reminded:

1. How much I hate C
2. But how nice it is to have terminal manpages for at least the standard library

Not having to open up a browser to check the syntax for say clap for the 100th time would be extremely handy.

As mentioned before, Oxidoc is no longer maintained so it would be really nice to have some official support.

Edit: Perhaps if it's too hard to add, making some kind of IR for docs. e.g. rustdoc generates some kind of easily parseable standard output which can then be used by library writers.

It seems like the reason oxidoc stopped being maintained was because of how difficult it was to consistently support it after new releases.

[rw]

@DarrienG I happen to agree! Here is an issue that was closed in February about it: https://github.com/rust-lang/rust/issues/68870

[steveklabnik]

Opening this issue doesn't really change anything; issues in the RFC repo aren't how work is tracked. The most productive way forward for interested parties here is to try to build such a thing, and then see what interfaces are needed, and then write an RFC to get them stabilized.

[robinkrahl]

I’m working on a command-line viewer for rustdoc documentation, rusty-man. Currently, it parses the HTML documentation, but of course it would be much better to have some standardized format. I’d like to help working on such interfaces, but I think someone with more experience with the librustdoc implementation and RFCs should take the lead.