Convert manual to markdown/mdbook

[joshrotenberg]

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]

Everybody loves screenshots!

[hw0lff]

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]

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

[joshrotenberg]

Argh what did I do.

[bors]

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

[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]

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]

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]

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]

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

[joshrotenberg]

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.

[joshrotenberg]

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.

[bors]

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

[lnicola]

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.

Sorry I'm so late to the party, but actually we can't hotlink them any more. It still works for old media if you remove private- and the JWT from the URL, but not for the new ones. See #17377 for an example.

[Veykril]

I wonder, can we just put images into a different repo and link to those? (to prevent polluting the main repo with image files)

[lnicola]

Sounds like a pain, but we'll probably need to. We could put them in the website repo, I guess. We need a place for the changelog images anyway.

[lnicola]

Or maybe there's another way: GitHub emails can't use the JWT, so they have links like https://github.com/rust-lang/rust-analyzer/assets/3886057/d0c1f6db-c9e9-4295-b4d7-be2ae7555da7, which seem to work even if you're not logged in.

[Veykril]

Current state, everything should be set with the final missing piece being integration in the website CI build step rust-analyzer/rust-analyzer.github.io#223

[bors]

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

[Veykril]

Okay so, really the only blocker is on integrating the mdbook site as a subsite in jekyll but I do not understand jekyll. I've been looking through its docs and have not found a single option that would make this work (rust-analyzer/rust-analyzer.github.io#223 is just a dry run which copies things into the repo)

[bors]

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

[Wilfred]

@Veykril I don't think you need to integrate with jekyll, do you? I'd have thought that the website repo could just do an mdbook build and include it in the output directory generated by jekyll. Something like this in rust-analyzer.github.io/.github/workflows/ci.yml (untested):

name: CI
on:
  push:
    branches:
      - src
  schedule:
    # Every hour, to pick up the latest rust-analyzer repo changes.
    - cron: '0 * * * *'

jobs:
  CI:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "2.7"

      - run: bundle install && bundle exec jekyll build

      - name: Install mdbook
        run: cargo install mdbook mdbook-toc

      - name: Clone the latest rust-analyzer, as of the mdbook PR
        run: git clone [email protected]:joshrotenberg/rust-analyzer.git
      - name: Switch to the mdbook PR branch
        run: cd rust-analyzer && git checkout mdbook-yolo
        
      - name: Run mdbook and include in jekyll output
        run: cd rust-analyzer/docs/book && mdbook build && cp -r book _site
        
      - name: Deploy
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: master
          publish_dir: _site
          force_orphan: true

[Veykril]

Maybe? I tried things out locally and that didn't work (though likely because the local jekyll server just doesn't do that)

[Wilfred]

OK, here's a tested version: rust-analyzer/rust-analyzer.github.io#224

This works as far as I can tell, but ideally there would be a separate xtask for the various generated.md files.

[Veykril]

It would make sense to lift out the website dist part as a separate xtask that the normal dist calls as well

Actually you can just run the release command with the --dry flag I think?