rust-lang / rust-lang/rust-analyzer

rust-analyzer reader-mode

Open
#8,696 37 comments 16 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

E-hard fun good first issue S-actionable
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.server and 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-mode and is exposed via ide crate.
  • 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.