Build the manual using mdbook and redirect old page #226
Conversation
Split manual.adoc into markdown files, one for each chapter. For the parts of the manual that are generated from source code doc comments, update the comments to use markdown syntax and update the code generators to write to `generated.md` files. For the weekly release, stop copying the .adoc files to the `rust-analyzer/rust-analyzer.github.io` at release time. Instead, we'll sync the manual hourly from this repository. See rust-analyzer/rust-analyzer.github.io#226 for the sync. This PR should be merged first, and that PR needs to be merged before the next weekly release. This change is based on rust-lang#15795, but rebased and updated. I've also manually checked each page for markdown syntax issues and fixed any I encountered. Co-authored-by: Lukas Wirth <[email protected]> Co-authored-by: Josh Rotenberg <[email protected]>
Split manual.adoc into markdown files, one for each chapter. For the parts of the manual that are generated from source code doc comments, update the comments to use markdown syntax and update the code generators to write to `generated.md` files. For the weekly release, stop copying the .adoc files to the `rust-analyzer/rust-analyzer.github.io` at release time. Instead, we'll sync the manual hourly from this repository. See rust-analyzer/rust-analyzer.github.io#226 for the sync. This PR should be merged first, and that PR needs to be merged before the next weekly release. This change is based on rust-lang#15795, but rebased and updated. I've also manually checked each page for markdown syntax issues and fixed any I encountered. Co-authored-by: Lukas Wirth <[email protected]> Co-authored-by: Josh Rotenberg <[email protected]>
Split manual.adoc into markdown files, one for each chapter. For the parts of the manual that are generated from source code doc comments, update the comments to use markdown syntax and update the code generators to write to `generated.md` files. For the weekly release, stop copying the .adoc files to the `rust-analyzer/rust-analyzer.github.io` at release time. Instead, we'll sync the manual hourly from this repository. See rust-analyzer/rust-analyzer.github.io#226 for the sync. This PR should be merged first, and that PR needs to be merged before the next weekly release. This change is based on rust-lang#15795, but rebased and updated. I've also manually checked each page for markdown syntax issues and fixed any I encountered. Co-authored-by: Lukas Wirth <[email protected]> Co-authored-by: Josh Rotenberg <[email protected]>
Split manual.adoc into markdown files, one for each chapter. For the parts of the manual that are generated from source code doc comments, update the comments to use markdown syntax and update the code generators to write to `generated.md` files. For the weekly release, stop copying the .adoc files to the `rust-analyzer/rust-analyzer.github.io` at release time. Instead, we'll sync the manual hourly from this repository. See rust-analyzer/rust-analyzer.github.io#226 for the sync. This PR should be merged first, and that PR needs to be merged before the next weekly release. This change is based on rust-lang#15795, but rebased and updated. I've also manually checked each page for markdown syntax issues and fixed any I encountered. Co-authored-by: Lukas Wirth <[email protected]> Co-authored-by: Josh Rotenberg <[email protected]>
Split manual.adoc into markdown files, one for each chapter. For the parts of the manual that are generated from source code doc comments, update the comments to use markdown syntax and update the code generators to write to `generated.md` files. For the weekly release, stop copying the .adoc files to the `rust-analyzer/rust-analyzer.github.io` at release time. Instead, we'll sync the manual hourly from this repository. See rust-analyzer/rust-analyzer.github.io#226 for the sync. This PR should be merged first, and that PR needs to be merged before the next weekly release. This change is based on rust-lang#15795, but rebased and updated. I've also manually checked each page for markdown syntax issues and fixed any I encountered. Co-authored-by: Lukas Wirth <[email protected]> Co-authored-by: Josh Rotenberg <[email protected]>
| @@ -3,6 +3,9 @@ on: | |||
| push: | |||
| branches: | |||
| - src | |||
| schedule: | |||
There was a problem hiding this comment.
Do we want this? It might be confusing for the users if the manual includes features that aren't available in the stable release yet. I think we should either have nightly and stable versions, or just stable.
There was a problem hiding this comment.
Yes, once a week or manually triggered as part of a release seems preferable. I wonder if we can easily setup some form cross repo triggers? (that is once a stable releases CI run finished, trigger CI here?)
There was a problem hiding this comment.
Maybe let's add workflow_dispatch too, so we can trigger it manually.
There was a problem hiding this comment.
Neat, I didn't know you could do that. Added.
|
OK, I've rebased and changed the job to run daily, as suggested in this comment. I don't see an obvious best frequency to run this. Users can run rust-analyzer from rustup (Stable is every six weeks, Nightly is presumably every day for rust-analyzer commits), or from the VS Code extension (released weekly with the latest rust-analyzer), or from their Linux distro (e.g. Arch is roughly weekly). The nice thing about running more often is contributors seeing their docs fixes reach the site sooner. I suppose it depends on how often docs fixes are version-specific. https://github.com/rust-lang/rust-analyzer/commits/2025-01-27/docs/user/manual.adoc is averaging around 1 change per month, but hopefully we will see more contributions once this lands :) I'm happy to change to whatever frequency you folks prefer, in any case. |
Wilfred
force-pushed
the
build_mdbook
branch
2 times, most recently
from
b718043 to
ffdabda
Compare
|
Hmm, can we move it to the parent directory so we no longer need the redirect? |
|
Unfortunately mdbook generates an index.html, so using the parent directory means that https://rust-analyzer.github.io/ is entirely replaced with the mdbook content I think. |
|
@Veykril do you have anything against merging this before Monday? |
|
No
…On Sat, Feb 1, 2025, 7:17 PM Laurențiu Nicola ***@***.***> wrote:
@Veykril <https://github.com/Veykril> do you have anything against
merging this before Monday?
—
Reply to this email directly, view it on GitHub
<#226 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AA4VNSYJYWW2YB2QXG4MZA32NUFSNAVCNFSM6AAAAABVYQGYWSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMMRZGA2TKOBVGU>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
GitHub actions changes corresponding to rust-lang/rust-analyzer#19015