-
Notifications
You must be signed in to change notification settings - Fork 1.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Move rust-analyzer manual to mdbook #10791
Move rust-analyzer manual to mdbook #10791
Conversation
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. |
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. |
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 👍 |
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. |
OK! The last big round of updates takes the 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. |
☔ The latest upstream changes (presumably #13262) made this pull request unmergeable. Please resolve the merge conflicts. |
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. |
No rush |
Had some environment issues, decided to start fresh with a better conversion process. See #13316 |
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:
manual
.generated_diagnostics
- crates/ide-diagnostics/src/tests/sourcegen.rsgenerated_features
- crates/rust-analyzer/tests/slow-tests/sourcegen.rsgenerated_config
- crates/rust-analyzer/src/config.rsgenerated_assists
- crates/ide-assists/src/tests/sourcegen.rsdocs/dev
md files tomanual/src/contributing
.Fixes #9504.