Convert manual to markdown/mdbook #15795

joshrotenberg · 2023-10-23T16:35:30Z

Ok, let's try this one more time!

Comments/reviews appreciated. This time it's just about bare bones moving the manual from adoc to mdbook.

Live deploy at http://joshrotenberg.com/rust-analyzer/index.html

Fixes #9504.

joshrotenberg · 2023-10-23T16:40:05Z

Everybody loves screenshots!

hw0lff · 2023-10-25T17:59:51Z

Some time ago I made a proof-of-concept for a better configuration page. The information on the current site is lacking important information such as possible configuration values for enums (and their description) or values of previous rust-analyzer version if anyone cannot use the newest version.
I never got any answer if it is desired to overhaul it or not. I think it would improve the configuration docs immensely. Since the PoC uses markdown to render the pages I thought it might fit into a future PR expanding the work here.

Edit: removed confusing "since" at beginning of the second sentence. expand the examples of "important information"

bors · 2023-11-11T15:21:33Z

☔ The latest upstream changes (presumably #15871) made this pull request unmergeable. Please resolve the merge conflicts.

joshrotenberg · 2023-11-11T23:35:53Z

Argh what did I do.

bors · 2023-11-12T14:17:20Z

☔ The latest upstream changes (presumably #15870) made this pull request unmergeable. Please resolve the merge conflicts.

docs/book/.gitignore

Veykril

Can we no longer link to images/gifs with this setup? I'd really rather us not having to put the images/gifs into the repo.

joshrotenberg · 2023-11-12T16:15:08Z

Can we no longer link to images/gifs with this setup? I'd really rather us not having to put the images/gifs into the repo.

We can, no problem. I thought it might be easier to manage them in the same place as the docs but either way works. I can go through and fix all the links.

Veykril · 2023-11-12T16:18:35Z

Can we no longer link to images/gifs with this setup? I'd really rather us not having to put the images/gifs into the repo.

We can, no problem. I thought it might be easier to manage them in the same place as the docs but either way works. I can go through and fix all the links.

Adding the images to the repo increases the repo size, which would be fine for just a few images, but we might add more, might update some etc. And it's not much of a management burden to handle links like this, so I'd prefer keeping the images out of the repo for the time being.

rustbot · 2023-11-12T16:32:21Z

There are merge commits (commits with multiple parents) in your changes. We have a no merge policy so these commits will need to be removed for this pull request to be merged.

You can start a rebase with the following commands:

$ # rebase
$ git rebase -i master
$ # delete any merge commits in the editor that appears
$ git push --force-with-lease

The following commits are merge commits:

0861100

bors · 2023-11-12T17:04:14Z

☔ The latest upstream changes (presumably #15882) made this pull request unmergeable. Please resolve the merge conflicts.

joshrotenberg · 2023-11-13T00:25:52Z

Adding the images to the repo increases the repo size, which would be fine for just a few images, but we might add more, > might update some etc. And it's not much of a management burden to handle links like this, so I'd prefer keeping the
images out of the repo for the time being.

Done, they should all point to the links that were previously there.

crates/ide/src/typing/on_enter.rs

Veykril · 2023-11-13T12:59:37Z

I think you missed updatin http://joshrotenberg.com/rust-analyzer/features/index.html#highlight-related, it looks weird here

joshrotenberg · 2023-11-13T17:51:38Z

I think you missed updatin http://joshrotenberg.com/rust-analyzer/features/index.html#highlight-related, it looks weird here

Fixed!

Veykril · 2023-11-14T17:24:58Z

crates/rust-analyzer/src/config.rs

@@ -2612,7 +2601,7 @@ mod tests {

    #[test]
    fn generate_config_documentation() {
-        let docs_path = project_root().join("docs/user/generated_config.adoc");
+        let docs_path = project_root().join("docs/book/src/configuration/generated.md");


We either need to keep this file checked in as before, or change this test to just generate the file without checking it. I don't recall why we had this file checked in in the first place though (whereas other files were not). @matklad do you remember?

I don’t really remember, though perhaps the goal was to have a stand-alone .adoc available in the repo?

It renders ok on GitHub:

https://github.com/rust-lang/rust-analyzer/blob/master/docs/user/manual.adoc#configuration

(note that you can click on the link to generated config).

MDBook also has this nice property that links in the source, rendered on GitHub, and rendered on the website work the same, so I’d keep the generated source checked in.

Sorry for picking adoc back then instead of markdown! My hypothesis was that rust-analyzer’s own docs would be a temporary thing, until we merge with rustc, so I decided to experiment instead of picking something long-term maintainable by community :-)

MDBook also has this nice property that links in the source, rendered on GitHub, and rendered on the website work the same, so I’d keep the generated source checked in.

I agree. In theory we could just keep all four generated files checked in, making them available both in the repo and as part of the deployed mdbook.

Let me know what you want to do and I can make the changes (for this one or all of them).

Any thoughts on how to deal with this?

Veykril · 2023-11-14T17:26:27Z

r? @lnicola if you have the time, would you mind giving this a quick look as well (and share your opinions on this if you have any)

Live deploy at http://joshrotenberg.com/rust-analyzer/index.html

bors · 2023-11-20T17:51:19Z

☔ The latest upstream changes (presumably #15885) made this pull request unmergeable. Please resolve the merge conflicts.

manual.adoc to markdown add entire static manual and toc move generated adoc to md in book dir add features add features add assists add config add diagnostics split up book, clean up links update book config add intro remove old docs, add a README clean up ignores add temporary workflow temporary makefile remove workflow Fix import preference config keys convert manual to mdbook manual.adoc to markdown add entire static manual and toc move generated adoc to md in book dir add features add features add assists add config add diagnostics split up book, clean up links update book config add intro remove old docs, add a README clean up ignores add temporary workflow temporary makefile remove workflow remove generated config.md rework generated locations and ignores remove img, replace with externally linked remove img, replace with externally linked these should be gone remove these fix kbd Co-authored-by: Lukas Wirth <lukastw97@gmail.com> fix md header smaller header fix highlight_related list update book readme

bors · 2023-12-01T14:38:19Z

☔ The latest upstream changes (presumably #16000) made this pull request unmergeable. Please resolve the merge conflicts.

Veykril · 2023-12-01T16:18:52Z

Ah sorry, I'll take a final look at this this weekend (and rebase myself if needed)

joshrotenberg · 2024-02-19T19:46:39Z

I have some free time in the next few weeks to handle any issues/additions on this if there is still interest in pushing it through.

Veykril · 2024-02-27T10:52:42Z

I'm sorry that i still haven't merged this 😓 I wanted to get a second opinion but that never came up I guess. I still very much want this!

davidbarsky · 2024-02-27T16:49:11Z

I think I like the current design of the site more, but I think mdbook's ease of contribution outweighs that, IMO. I'm personally onboard with this!

hw0lff · 2024-02-29T14:13:43Z

I am looking forward to this being merged. It lays a ground for more improvements, e.g. better reference documentation for configuration options. The current design is insufficient for the sheer number of options RA has.
Another IMO useful feature would be to build reference docs of config options for previous RA versions too.
Based on the mentioned points, I disagree with this statement in the main comment:

Fixes #9504.

I never got written feedback on the issues 1 2 I raised and ideas I proposed in a PoC. I don't want to put effort into a PR that won't be merged because it's not aligned with the opinions of the maintainers.
That's why I'd like some clarification on this.

Veykril · 2024-04-18T08:32:06Z

SO we are currently redesigning the config stuff meaning this has conflicts yet again (because I still haven't gotten back to it), and there will be new ones once thats completed. So I'll wait with this until that redesign is finished, then I'll rebase it and get it over, don't want you to put more and more time in just to wait again (unless thats your kind of thing 😶). That change should also allow us to more easily address the fact that the documentation is not showing all config options which can do as a follow up.

Again really sorry this is taking so long to get in.

joshrotenberg · 2024-04-18T16:34:05Z

SO we are currently redesigning the config stuff meaning this has conflicts yet again (because I still haven't gotten back to it), and there will be new ones once thats completed. So I'll wait with this until that redesign is finished, then I'll rebase it and get it over, don't want you to put more and more time in just to wait again (unless thats your kind of thing 😶). That change should also allow us to more easily address the fact that the documentation is not showing all config options which can do as a follow up.

Again really sorry this is taking so long to get in.

No problem, I'm here when you're ready.

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Oct 23, 2023

joshrotenberg mentioned this pull request Oct 23, 2023

Move manual to mdBook #15144

Closed

10 tasks

joshrotenberg force-pushed the mdbook-yolo branch 4 times, most recently from aa0ec91 to a8e8c4f Compare October 25, 2023 02:52

Veykril self-assigned this Nov 11, 2023

joshrotenberg closed this Nov 11, 2023

joshrotenberg force-pushed the mdbook-yolo branch from a8e8c4f to 5fcf528 Compare November 11, 2023 23:33

joshrotenberg reopened this Nov 11, 2023

joshrotenberg force-pushed the mdbook-yolo branch from d9b8f08 to f160f31 Compare November 12, 2023 00:07

Veykril reviewed Nov 12, 2023

View reviewed changes

docs/book/.gitignore Show resolved Hide resolved

Veykril reviewed Nov 12, 2023

View reviewed changes

Veykril added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Nov 12, 2023

rustbot added the has-merge-commits label Nov 12, 2023

joshrotenberg force-pushed the mdbook-yolo branch from e4e0df5 to d78f3e0 Compare November 12, 2023 22:25

joshrotenberg force-pushed the mdbook-yolo branch 2 times, most recently from 54f8c7e to 3afdf72 Compare November 13, 2023 00:33

Veykril removed the has-merge-commits label Nov 13, 2023

Veykril reviewed Nov 13, 2023

View reviewed changes

crates/ide/src/typing/on_enter.rs Outdated Show resolved Hide resolved

Veykril reviewed Nov 13, 2023

View reviewed changes

crates/ide/src/typing/on_enter.rs Outdated Show resolved Hide resolved

joshrotenberg force-pushed the mdbook-yolo branch 3 times, most recently from 085a70a to cf9b928 Compare November 13, 2023 17:50

Veykril approved these changes Nov 14, 2023

View reviewed changes

Veykril reviewed Nov 14, 2023

View reviewed changes

joshrotenberg force-pushed the mdbook-yolo branch from cf9b928 to b09b661 Compare November 15, 2023 21:46

joshrotenberg force-pushed the mdbook-yolo branch from b09b661 to 9e8005c Compare November 21, 2023 17:22

Veykril added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jan 2, 2024

Veykril mentioned this pull request Jan 15, 2024

minor: Add a stable #visual-studio anchor to the Manual #16361

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Convert manual to markdown/mdbook #15795

Convert manual to markdown/mdbook #15795

joshrotenberg commented Oct 23, 2023 •

edited

joshrotenberg commented Oct 23, 2023 •

edited

hw0lff commented Oct 25, 2023 •

edited

bors commented Nov 11, 2023

joshrotenberg commented Nov 11, 2023

bors commented Nov 12, 2023

Veykril left a comment •

edited

joshrotenberg commented Nov 12, 2023

Veykril commented Nov 12, 2023

rustbot commented Nov 12, 2023

bors commented Nov 12, 2023

joshrotenberg commented Nov 13, 2023

Veykril commented Nov 13, 2023

joshrotenberg commented Nov 13, 2023

Veykril Nov 14, 2023

matklad Nov 14, 2023

joshrotenberg Nov 14, 2023

joshrotenberg Dec 17, 2023

Veykril commented Nov 14, 2023

bors commented Nov 20, 2023

bors commented Dec 1, 2023

Veykril commented Dec 1, 2023

joshrotenberg commented Feb 19, 2024

Veykril commented Feb 27, 2024

davidbarsky commented Feb 27, 2024

hw0lff commented Feb 29, 2024

Veykril commented Apr 18, 2024

joshrotenberg commented Apr 18, 2024

Convert manual to markdown/mdbook #15795

Are you sure you want to change the base?

Convert manual to markdown/mdbook #15795

Conversation

joshrotenberg commented Oct 23, 2023 • edited

joshrotenberg commented Oct 23, 2023 • edited

hw0lff commented Oct 25, 2023 • edited

bors commented Nov 11, 2023

joshrotenberg commented Nov 11, 2023

bors commented Nov 12, 2023

Veykril left a comment • edited

Choose a reason for hiding this comment

joshrotenberg commented Nov 12, 2023

Veykril commented Nov 12, 2023

rustbot commented Nov 12, 2023

bors commented Nov 12, 2023

joshrotenberg commented Nov 13, 2023

Veykril commented Nov 13, 2023

joshrotenberg commented Nov 13, 2023

Veykril Nov 14, 2023

Choose a reason for hiding this comment

matklad Nov 14, 2023

Choose a reason for hiding this comment

joshrotenberg Nov 14, 2023

Choose a reason for hiding this comment

joshrotenberg Dec 17, 2023

Choose a reason for hiding this comment

Veykril commented Nov 14, 2023

bors commented Nov 20, 2023

bors commented Dec 1, 2023

Veykril commented Dec 1, 2023

joshrotenberg commented Feb 19, 2024

Veykril commented Feb 27, 2024

davidbarsky commented Feb 27, 2024

hw0lff commented Feb 29, 2024

Veykril commented Apr 18, 2024

joshrotenberg commented Apr 18, 2024

joshrotenberg commented Oct 23, 2023 •

edited

joshrotenberg commented Oct 23, 2023 •

edited

hw0lff commented Oct 25, 2023 •

edited

Veykril left a comment •

edited