docs: Minor re-grouping of pages #14620

epage · 2024-09-30T21:13:47Z

What does this PR try to resolve?

In figuring out where MSRV documentation should live, I found the location of some items confusing

Publishing is written in more of a guide-form, rather than reference
Caching is written in more of a reference form, rather than a guide, and is more advanced
Dependency references were scattered, making it harder to find

How should we test and review this PR?

Additional information

rustbot · 2024-09-30T21:13:54Z

rustbot has assigned @weihanglo.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

weihanglo · 2024-09-30T21:35:17Z

src/doc/src/SUMMARY.md

@@ -15,33 +15,33 @@
    * [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.md)
    * [Tests](guide/tests.md)
    * [Continuous Integration](guide/continuous-integration.md)
+    * [Publishing on crates.io](guide/publishing.md)


Redirections are needed. Maybe use this? https://rust-lang.github.io/mdBook/format/configuration/renderers.html#outputhtmlredirect

This will generate an HTML page which will automatically redirect to the given location. Note that the source location does not support # anchor redirects.

This is the interesting part of this config. We might need to do this as well?

cargo/src/doc/src/reference/specifying-dependencies.md

Lines 631 to 648 in 2fd7321

<script>

(function() {

var fragments = {

"#overriding-dependencies": "overriding-dependencies.html",

"#testing-a-bugfix": "overriding-dependencies.html#testing-a-bugfix",

"#working-with-an-unpublished-minor-version": "overriding-dependencies.html#working-with-an-unpublished-minor-version",

"#overriding-repository-url": "overriding-dependencies.html#overriding-repository-url",

"#prepublishing-a-breaking-change": "overriding-dependencies.html#prepublishing-a-breaking-change",

"#overriding-with-local-dependencies": "overriding-dependencies.html#paths-overrides",

};

var target = fragments[window.location.hash];

if (target) {

var url = window.location.toString();

var base = url.substring(0, url.lastIndexOf('/'));

window.location.replace(base + "/" + target);

}

})();

</script>

So instead of using the redirect feature, you are proposing that we place a hand-written file in the old location that includes the script to redirect fragments? I'm not fully confident in making sure all of these features interact well with each other, search engines, etc.

The mdbook config one is for generating those old pages with a <meta http-equiv="refresh" content="0; URL=/.path/to/new/location.html">, which is a reasonable way to getting a better search engine optimization. However it doesn't support hash. The hand-written <script> hack doesn't seem to help this situation, either.

Off the top of my head, the only way to support hash redirections is using JavaScript in the old location of the markdown file, and make the markdown file hidden. It is not good, though.

I have another "bad idea": don't rename file names. Just swap the order in SUMMARY.md.

cc @ehuss as you may know how well we need to maintain link validity. Like would tools in rust-lang/rust check this?

Hm, yea, this might actually be a little bit of a problem. I think there are quite a few links to https://doc.rust-lang.org/cargo/reference/publishing.html#github-permissions in particular.

~~I actually don't think there is a way to include a redirect file without leaving an entry in SUMMARY which I think is undesirable here.~~ (Scratch that, you can just place an html file in the src directory.)

I might recommend just moving the entries in SUMMARY.md, but don't rename the file. I realize that is not optimal, since the URL is a little confusing that way.

Perhaps in the future we can extend mdbook to support javascript redirects with HTML fragments on removed pages? We can rename the files at that time.

Oh, I see what you mean by leaving an html file in its place. I think that should work. That seems like a reasonable option, too.

For now, I'm leaving the path in the old location.

weihanglo

I am fine with the current state of this PR.

It doesn't "guide" people through a topic but explains in a more top-down fashion what caches exist and is not particularly a common topic people need to know.

src/doc/src/guide/build-cache.md

weihanglo

r=me when you rebuild those man pages.

epage · 2024-10-03T20:00:03Z

@bors r=weihanglo

bors · 2024-10-03T20:00:06Z

📌 Commit 3a0236f has been approved by weihanglo

It is now in the queue for this repository.

bors · 2024-10-03T20:01:14Z

⌛ Testing commit 3a0236f with merge 0473ee8...

bors · 2024-10-03T20:31:52Z

☀️ Test successful - checks-actions
Approved by: weihanglo
Pushing 0473ee8 to master...

Update cargo 17 commits in 80d82ca22abbee5fb7b51fa1abeb1ae34e99e88a..ad074abe3a18ce8444c06f962ceecfd056acfc73 2024-09-27 17:56:01 +0000 to 2024-10-04 18:18:15 +0000 - test: Remove the last of our custom json assertions (rust-lang/cargo#14576) - docs(ref): Expand on MSRV (rust-lang/cargo#14636) - docs: Minor re-grouping of pages (rust-lang/cargo#14620) - docs(ref): Highleft whats left for msrv-policy (rust-lang/cargo#14638) - Fix `cargo:version_number` - has only one `:` (rust-lang/cargo#14637) - docs: Declare support level for each crate in our Charter / docs (rust-lang/cargo#14600) - chore(deps): update tar to 0.4.42 (rust-lang/cargo#14632) - docs(charter): Declare new Intentional Artifacts as 'small' changes (rust-lang/cargo#14599) - fix: Remove implicit feature removal (rust-lang/cargo#14630) - docs(config): make `--config <PATH>` more prominent (rust-lang/cargo#14631) - chore(deps): update rust crate unicode-width to 0.2.0 (rust-lang/cargo#14624) - chore(deps): update embarkstudios/cargo-deny-action action to v2 (rust-lang/cargo#14628) - docs(ref): Clean up language for `package.rust-version` (rust-lang/cargo#14619) - docs: clarify `target.'cfg(...)'` doesnt respect cfg from build script (rust-lang/cargo#14312) - test: relax compiler panic assertions (rust-lang/cargo#14618) - refactor(compiler): zero-copy deserialization when possible (rust-lang/cargo#14608) - test: add support for features in the sat resolver (rust-lang/cargo#14583)

rustbot assigned weihanglo Sep 30, 2024

rustbot added A-documenting-cargo-itself Area: Cargo's documentation S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 30, 2024

weihanglo reviewed Sep 30, 2024

View reviewed changes

epage force-pushed the guideless branch 3 times, most recently from f157076 to 6867124 Compare October 1, 2024 02:08

weihanglo approved these changes Oct 2, 2024

View reviewed changes

epage added 3 commits October 3, 2024 08:23

docs: Move publishing from ref to guide

a3eaa4b

docs: Move Cache topic from Guide to Reference

1dde071

It doesn't "guide" people through a topic but explains in a more top-down fashion what caches exist and is not particularly a common topic people need to know.

docs: Group dep related references

3a0236f

epage force-pushed the guideless branch 2 times, most recently from cc63648 to a0c5276 Compare October 3, 2024 14:40

weihanglo reviewed Oct 3, 2024

View reviewed changes

src/doc/src/guide/build-cache.md Show resolved Hide resolved

src/doc/src/guide/build-cache.md Show resolved Hide resolved

epage force-pushed the guideless branch 3 times, most recently from d8cf767 to 5c3031d Compare October 3, 2024 19:02

weihanglo approved these changes Oct 3, 2024

View reviewed changes

epage force-pushed the guideless branch from 5c3031d to 3a0236f Compare October 3, 2024 19:59

rustbot added the A-cli-help Area: built-in command-line help label Oct 3, 2024

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Oct 3, 2024

bors merged commit 0473ee8 into rust-lang:master Oct 3, 2024
20 checks passed

epage deleted the guideless branch October 3, 2024 20:36

bors mentioned this pull request Oct 3, 2024

Document interaction between custom profiles and overrides #13590

Closed

weihanglo mentioned this pull request Oct 4, 2024

Update cargo rust-lang/rust#131124

Merged

rustbot added this to the 1.83.0 milestone Oct 5, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Minor re-grouping of pages #14620

docs: Minor re-grouping of pages #14620

epage commented Sep 30, 2024

rustbot commented Sep 30, 2024

weihanglo Sep 30, 2024

weihanglo Oct 1, 2024

epage Oct 1, 2024

weihanglo Oct 1, 2024

weihanglo Oct 2, 2024

weihanglo Oct 2, 2024

ehuss Oct 3, 2024 •

edited

Loading

ehuss Oct 3, 2024

epage Oct 3, 2024

weihanglo left a comment

weihanglo left a comment

epage commented Oct 3, 2024

bors commented Oct 3, 2024

bors commented Oct 3, 2024

bors commented Oct 3, 2024

	<script>
	(function() {
	var fragments = {
	"#overriding-dependencies": "overriding-dependencies.html",
	"#testing-a-bugfix": "overriding-dependencies.html#testing-a-bugfix",
	"#working-with-an-unpublished-minor-version": "overriding-dependencies.html#working-with-an-unpublished-minor-version",
	"#overriding-repository-url": "overriding-dependencies.html#overriding-repository-url",
	"#prepublishing-a-breaking-change": "overriding-dependencies.html#prepublishing-a-breaking-change",
	"#overriding-with-local-dependencies": "overriding-dependencies.html#paths-overrides",
	};
	var target = fragments[window.location.hash];
	if (target) {
	var url = window.location.toString();
	var base = url.substring(0, url.lastIndexOf('/'));
	window.location.replace(base + "/" + target);
	}
	})();
	</script>

docs: Minor re-grouping of pages #14620

docs: Minor re-grouping of pages #14620

Conversation

epage commented Sep 30, 2024

What does this PR try to resolve?

How should we test and review this PR?

Additional information

rustbot commented Sep 30, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ehuss Oct 3, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weihanglo left a comment

Choose a reason for hiding this comment

weihanglo left a comment

Choose a reason for hiding this comment

epage commented Oct 3, 2024

bors commented Oct 3, 2024

bors commented Oct 3, 2024

bors commented Oct 3, 2024

ehuss Oct 3, 2024 •

edited

Loading