Move rust-analyzer manual to mdbook

[joshrotenberg]

This refreshes the asciidoc manual to use mdbook.

See responses/ideas in #9504.

Currently a work in progress. If this seems like the right direction, I'll continue with the list below.

TODO:

• For now, verbatim copy content from current manual to corresponding markdown file in manual.
• Figure out how to deal with generated content.
  • generated_diagnostics - crates/ide-diagnostics/src/tests/sourcegen.rs
  • generated_features - crates/rust-analyzer/tests/slow-tests/sourcegen.rs
  • generated_config - crates/rust-analyzer/src/config.rs
  • generated_assists - crates/ide-assists/src/tests/sourcegen.rs
• Move landing page to introduction.
• Add Quickstart.
• Copy over docs/dev md files to manual/src/contributing.
• Figure out changes needed for deployment.
• Add docs on how to build/test/run/modify book.

Fixes #9504.

[joshrotenberg]

[Veykril]

I apologize that no one has gotten back to the PR after 7 months, looks like it feel off of everyone's radar. With that said, are you still interested in this PR? Then I'd take a look at what you've got here and commit some time to review/discussion.

[joshrotenberg]

I apologize that no one has gotten back to the PR after 7 months, looks like it feel off of everyone's radar. With that said, are you still interested in this PR? Then I'd take a look at what you've got here and commit some time to review/discussion.

No need to apologize, I understand. I’m definitely still interested. I can take another look at it and remember how I left it this week.

[joshrotenberg]

Ok, getting back to this. If you like this approach, I can go through and move the current static content from the docs into the new mdbook/markdown format, and then we can discuss how to manage the generated content, as well as any changes/updates you'd like to make to the contents. I may make some editorial updates while I move things over where appropriate. Why don't I do a couple of sections and then we can review and see if you're happy with how it's turning out, and go from there.

[Veykril]

Ye I think this looks good, as the issue outlines we should think a bit about the landing page/front page later on but I don't think that impacts the books structure so that's something for later.

Sounds like a plan 👍

[joshrotenberg]

Ok, I think this PR is at the point where the remaining changes start touching a lot more files (mostly the generated stuff, of course), so the question is this: would it be preferable to have this overall documentation change (moving to mdbook, I mean) be a process over several PRs (say, this one for just new content and another for the cutover) or just one PR that has all the changes?

Edit to add that while I don't see the changes required for the generated content to be significant in effect (mostly just ascii doc to markdown stuff), there will be a lot of them given that content is pulled from comments.

[joshrotenberg]

Quick peek at how the features page looks. I'll try to get the latest deployed to gh pages on my fork to make it easier to see the current state.

[joshrotenberg]

OK! The last big round of updates takes the Features page out of ascii doc and into markdown. This involved touching quite a few files, almost all of which was moving from adoc to md in the comments that are parsed. Fortunately, there is a fair amount of crossover. There were also the small code changes required to write the markdown file.

I had originally stubbed out a single page per feature. The benefit of this is that we get the full list in the navigation markdown. Since the current process generates to a single file, though, it made more sense to stick with that for now I think, so I added a TOC to the top of the Features page. It's ... ok. I think it's a detail that can potentially get fixed later on.

In regards to my previous comment, making it so that the old and new manual can coexist seems like more work than necessary, so I'm going to plan on making this PR a clean cutover unless someone disagrees. I'll go through and get the other generated sections moved over as well.

[bors]

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

[Veykril]

Ah I never asked, should I take a look by now or are you still moving some things around?

[joshrotenberg]

Ah I never asked, should I take a look by now or are you still moving some things around?

Still some stuff to work on, had to take a break for other things, but I should be able to get back to it soon.

[Veykril]

No rush

[joshrotenberg]

Had some environment issues, decided to start fresh with a better conversion process. See #13316