Move manual to mdBook

[joshrotenberg]

I made a mess of this last time around. Here is another try, fortunately with lots of hindsight.

Fixes #9504.

Manually deployed to: http://joshrotenberg.com/rust-analyzer/index.html

This is a work in progress. Here are the current steps, with probably more to come.

• - Convert docs/user/manual.adoc to markdown.

I did this with pandoc using something similar to this blog post. For the static content,
this worked really well.

• - Create a base mdbook setup.

I used mdbook init and then reused my previous book.toml and SUMMARY.md.

• - Sweep through the generated markdown for lints, images, style, etc.

I moved each section according to the current manual to match the mdbook structure, and in the process fixed some minor issues, restructured headings, brought in the images, lint, etc.

• - Move the developer guide to the book.

This isn't absolutely necessary but it does consolidate the docs in one place, and since docs/dev is already markdown it was easy. I did go through and do some minor linting/markdown style but for the most part the Contributing section of the book is the same as docs/dev.

• - Convert generated docs from adoc to markdown.

This is a big chunk of the work, obviously, and is a fairly atomic step which makes everything above a little bit more difficult: the current manual and the new manual can't really coexist, at least not fully functional (or without some kind of interim conversion).

• - Remove old docs.

Just a matter of deciding where the new manual should live (top level manual directory? docs/user? docs/manual?). I've got docs/manual for now.

Edit: had to change a path in a source file as well.

• - Update release for mdbook files.

Right now the adoc files are handled explicitly in the task:

rust-analyzer/xtask/src/release.rs

Line 49 in 7c8ae35

for adoc in [

• - Figure out deployment.

I'm still a little confused about this, need to dig around again.

• - Solve workflow failures.

• - Deploy current state on fork.

See http://joshrotenberg.com/rust-analyzer/index.html. Will be updated periodically.

Screenshots

Introduction:

Features:

Assists:

Diagnostics:

[Veykril]

This looks great!

[Veykril]

oh before you continue to build on the merge commits, can you try and get rid of those. We don't really want to have merge commits aside from bors in the tree (Ill also be gone for the rest of the month so if you want a review from me in that time span you'll have to wait)

[Wilfred]

This looks really good! Anything I can do to help?

[joshrotenberg]

This looks really good! Anything I can do to help?

I put it down for a bit since @Veykril was off, and then I messed something up with the commits and haven't had a chance to fix it yet. For the most part things were looking pretty good. Once I get it back in shape I guess making any updates to doc changes that have happened recently, and then reviews and decisions around the best way to merge and deploy this. If you have any feedback, though, I'm all ears.

[joshrotenberg]

Once again I messed up my branch. Ugh. I'm going to move the work and information over and create a new one and hopefully get this thing taken care of.

[joshrotenberg]

Hopefully this is the one! #15795

@Veykril @Wilfred would love a review.