rust-lang / rust-lang/rust-analyzer
rust-analyzer reader-mode
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 16.9k
- Forks
- 2.2k
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 72
Description
TL;DR: https://github.com/rust-dev-tools/cargo-src, but on top of rust-analyzer
Add a command, rust-analyzer reader-mode path/to/Cargo.toml, which produces a directory with a bunch of html files, which contain source for the project, a-la rustdoc output, but also have goto definition, hover, etc.
Interface Constraints:
- Static site
- Assume modern desktop browser
- No external CSS, or CSS pre-processors, minimal hand-written CSS to get the job done.
- No or minimal JavaScript
- No build-in HTTP serever (but it's OK to try to auto-discover
python3 -m http.serverand such on usres' machine) - (Maybe) an option to compress everything down to a single html file which you can just open in the browser.
Implementation Constraints:
- Implementatin lives in
ide-reader-modeand is exposed viaidecrate. - There's a transparent intermediate representation. The result of reader mode is not directly an HTML string, but something else. That something else is a set of annotated files,
struct ReaderView. This view is independent of the hir or ide types, and is just a large chunk of data. The data includes two things, a list of files and a list of defs. Each file is a text plus a number of auxilary maps that describe ranges in the file. There should be a map for syntax hightlighting, a map for references and definitons, maybe a map for folding ranges (fold method bodies would be useful feature to have). Spans in files refer to defs by ID. Defs are untyped, and store their defining spans and a list of refs. Not sure if we need a separate ref list or just spans would be enough. - ReaderView might want to live in a separate crate, just to make sure it doesn't depend on rust-analyzer types
- ReaderView has
fn to_html(&self) -> HashMap<PathBuf, String>method, which renders it as a directory with htmls and csses. This should be completely independent of the rust-analyzer.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by examining the ide-reader-mode implementation area and how it is exposed through the ide crate. Review the proposed ReaderView intermediate representation and its HTML rendering constraints, then determine the smallest design and integration steps needed for a static reader-mode output.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- devtools
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100