Pull the cargo docs out of tree and convert them to mdBook #4040
Comments
|
@istankovic is working on a draft of this over here! https://github.com/istankovic/cargo-book |
|
Here's an old PR for this: #4220 The content of pages have been updated since this PR and the fork. Not sure how they're going to be handled. |
|
Heh, just the other day I spent quite some time porting the doc changes made in the meantime to my branch. And now there are additional changes, which I don't mind, really, but I'd like to avoid unnecessary work, if possible. Is there another effort to move the cargo docs to mdbook, that I am not aware of? |
|
I don't know about the migrations, but have been updating the docs recently, because of code changes and improving readability. |
|
@behnam would you be willing to take over the migration effort? 😄 |
|
@istankovic Would be glad to help with Cargo's migration. Although, I haven't worked with mdBook yet and not sure what the plans are overall. Specifically, I have updated cargo docs to get the online docs like http://doc.crates.io/manifest.html updated, which is considered the reference for manifest syntax. What do we expect to happen to these URLs with the migration? /ping @carols10cents |
|
Well, the idea here is to make Cargo docs more like other books, see rust-lang/rust#39588. So you can take a look at how the other books look now, it's very straightforward. You can also checkout the doc-migration branch and run The good news is the migration is almost done (modulo your latest changes). The only thing that I did not yet figure out is what to do with the script that builds the docs. This is also probably related to your question about the URLs. Maybe @steveklabnik can give some advice here. One thing to note is that, unlike other books, this will not be in a separate repo, see the related discussion in the PR. |
|
Ok, we talked about this in the cargo team meeting today, and this sort of affects the book too. Here's what we discussed:
I am going to ask the doc team what URL they'd like for the cargo docs, and then I'd like help/pointers from @alexcrichton to set up said redirect to doc.crates.io, and then I can help with getting #4220 rebased and merged in as peoples' schedules allow (but that isn't as urgent as the first two). Anything I'm forgetting? |
|
Any objections to |
|
Sounds like a good plan, @carols10cents! One question: @istankovic mentioned that the new structure is almost ready for the book format, and there's already plenty of the content there, some of which needing updates from upstream. So, it is possible right now to host the new repo on <doc.rust-lang.org>, in an unstable form, and make that the source of truth whenever the content is up-to-date and redirects are set for it from <doc.crates.io>. This way, there's no need to set up redirects in the other direction. Have you considered this option? (I'm curious what may be preventing the new repo going online right now.) |
Since the new structure is going to be deployed through rust-lang/rust, it has to ride the trains. That means it'll only be available at doc.rust-lang.org/nightly/cargo at first, then doc.rust-lang.org/beta/cargo the first time beta branches after that PR makes it in, then doc.rust-lang.org/cargo 6 weeks after that. We want to have a URL to print in the book that needs to definitely go somewhere sometime before December (I don't know when the REALLY hard deadline for that is). I don't want to rush the PR converting the docs because of the book. So for now, we're just going to set up the redirect from doc.rust-lang.org/cargo -> doc.crates.io, make sure that gets into the very next beta, print the Does that make sense? |
|
Got it! So it's the release schedule for the new repo. Totally makes sense. :) |
|
Sounds reasonable to me. Still, I'd like to point out once more that the docs are mostly converted. The only changes needed are to port doc updates made by @behnam, which should not be a big deal, and to deal with the infrastucture (build script etc.). @behnam, if you're willing to do it, I'd be more than happy to hand over the doc-migration effort. |
|
Sure, @istankovic. I can help with that. Would you please also give me some pointers, specially which other docs repo is a good example to look at, specially for build process/scripts? |
|
You can take a look at how I transferred doc changes here: https://github.com/istankovic/cargo-book/commits/master. For each doc commit in cargo I have a commit in cargo-book which is mostly copy-paste. I changed the original structure somewhat so you need to find appropriate places for the changes, but it is pretty straightforward. Also keeping references up to date should not be a big deal. |
…=alexcrichton Implement a temp redirect for cargo docs As discussed in rust-lang/cargo#4040 (comment) This is a redirect meant to be replaced once cargo docs have been converted to mdbook. We just want *a* URL to ride the trains for now so that we can print doc.rust-lang.org/cargo in the paper book and guarantee that it will go *somewhere* useful by the time the book is printed. Implemented as a meta redirect in HTML because we don't currently have any google juice at doc.rust-lang.org/cargo to lose. When I run `./x.py doc`, this creates a `build/x86_64-apple-darwin/doc/cargo/index.html` file that contains a meta redirect to doc.crates.io. As I understand rust-central-station to work, this should be what we need to make `doc.rust-lang.org/cargo` to work. r? @alexcrichton and/or @steveklabnik
|
We have decided to keep the docs in-repo. We can update the title of this issue. And the first PR is here: #4453 |
Import mdBook-based docs and sync Since we decided to keep the mdBook-based docs in-repo, I have imported the existing converted docs from <https://github.com/istankovic/cargo-book> under `/src/doc/book/` here, and have synced the current docs and the mdBook-based ones manually, file-by-file. I have created a `MIGRATION_MAP` file, which shows the relationship between old docs and new ones. The first column is the old file, the second column is the canonical location in mdBook, and the rest of columns are globs of other files in mdBook containing content from the old file. The first and second column of `MIGRATION_MAP` shall later be used to create redirect rules from `doc.crates.io/` to `doc.rust-lang.org/cargo/`. I will also add a README file to remind everyone to keep these files in sync during the migration. There are also two or three small wording fixes here, which I'll note inline. This is a retry of <#4220>. First step for <#4040>.
[doc/book] Add introduction page and other enhancements Preview: http://code.behnam.es/rust-cargo/book/ * Reorganize files to use folders instead of numbered files. This will allow us to add new sections and pages without breaking a numbering system or the URLs. * Rename "Cargo In Depth" to "Cargo Reference", as those pages are considered *the* reference for cargo behaviors. * Add `introduction.md`, as the landing page with the book title and Cargo logo on top. * Expand `installation.md`: Import install text and links from <https://crates.io/install>, as we want to drop that page and redirect it to here. (See <rust-lang/crates.io#1029>) * Sync `SUMMARY.md` titles (and sub-pages lists in section pages) with page titles and fix some wordings and casings. * Expand Introduction and section pages with some intro text. * Set lang for some of the code blocks. * Add `book.toml` to get the title in HTML head title, etc. Tracker: <#4040>
[doc] Publish book to gh-pages Export mdBook into `target/doc/book/`, to make it accessible at <http://doc.crates.io/book/> I have tested the changes on my repo (but when I had this commit on top of the other PR) locally. The result is at <http://code.behnam.es/rust-cargo/book/>. Tracker: <#4040>
|
Preview is now live here: http://doc.crates.io/book/ mdBook has a major issue with in-page link generation and we need to wait until the fix lands and makes it to a release, before we add it to the bookshelf. (Upstream fix: https://github.com/azerupi/mdBook/pull/419) I'm also addressing some other small issues and looking forward to more feedback. |
We don't need to put `policies.md` in the book. See <rust-lang/crates.io#1030> for more. Renaming `introduction.md` to `index.md` prevents creating two html files (and URL) for one source. The rest are small styling issues. Tracker: <rust-lang#4040>
[doc/book] Drop reference/policies.md and small fixes We don't need to put `policies.md` in the book. See <rust-lang/crates.io#1030> for more. Renaming `introduction.md` to `index.md` prevents creating two html files (and URL) for one source. The rest are small styling issues. Tracker: <#4040>
|
Okay, let's close this issue in favor of the follow up here: rust-lang/rust#44910 |
|
Sounds great! |
Part of rust-lang/rust#39588. I didn't see an issue for this yet @steveklabnik so I made one :)
The text was updated successfully, but these errors were encountered: