75521 rustdoc book improvements #75778

AndyGauge · 2020-08-21T17:38:27Z

Added some guidelines about documenting with rustdoc
Fixes #75521

rust-highfive · 2020-08-21T17:38:30Z

(rust_highfive has picked a reviewer for you, use r? to override)

GuillaumeGomez · 2020-08-21T17:59:26Z

src/doc/rustdoc/src/how-to-write-documentation.md

@@ -1,14 +1,85 @@
 # How to write documentation

+Good documentation is not natural.  There are opposing forces that make good


I was wondering: do we have to keep two whitespaces between sentences? cc @rust-lang/docs

src/doc/rustdoc/src/how-to-write-documentation.md

GuillaumeGomez · 2020-08-21T18:00:56Z

src/doc/rustdoc/src/what-is-rustdoc.md

+
+## Configuring rustdoc
+
+There's two problems with this: first, why does it


Suggested change

There's two problems with this: first, why does it

There are two problems with this: first, why does it

I agree, I'll re-read it looking for more of these.

I thought it looked more natural as a contraction, but either way is fine as long as it's consistent.

src/doc/rustdoc/src/what-to-include.md

GuillaumeGomez · 2020-08-21T18:07:58Z

This is a great start! I think if we should also talk more about the arguments that allows to customize the HTML output (for example, adding themes or adding your own JS/CSS files, etc...). We can do that in another PR though (but if so, don't mark this PR as a fix for #75521 ;) ).

GuillaumeGomez · 2020-08-21T18:08:38Z

Oh also: I'll definitely need a native english person to double-check the typos and other things. :)

AndyGauge · 2020-08-21T18:10:27Z

I agree with the themes included in this PR. Should I adjust the title to include work in process?

GuillaumeGomez · 2020-08-21T18:12:27Z

Well, it remains "rustdoc improvements", so it's fine. But you might want to expand the description of the PR a bit if you do it in this PR. ;)

src/doc/rustdoc/src/how-to-write-documentation.md

Dylan-DPC-zz

initial review tidbits, just felt it reads better, can ignore if you wish :D

src/doc/rustdoc/src/how-to-write-documentation.md

jyn514

I may have gone a little overboard.

src/doc/rustdoc/src/how-to-write-documentation.md

src/doc/rustdoc/src/what-to-include.md

src/doc/rustdoc/src/how-to-write-documentation.md

jyn514 · 2020-08-22T16:08:07Z

src/doc/rustdoc/src/how-to-write-documentation.md

+The first line of description will be reused to describe the component in
+searches and module overviews.  For example, the function `std::env::args()`
+above will be shown on the [`std::env`] module documentation.  Multi-line
+summaries are also possible, however, concise writing is a goal of good
+documentation.


This is still not correct - it implies that only the first line of a multi-line summary will be shown. It should say that everything before a line break will be shown, but it's good practice to only have one line in the summary.

src/doc/rustdoc/src/references.md

jyn514 · 2020-08-22T16:08:57Z

src/doc/rustdoc/src/what-is-rustdoc.md

@@ -7,22 +7,22 @@ CSS, and JavaScript.

 ## Basic usage

-Let's give it a try! Let's create a new project with Cargo:
+Let us give it a try! Create a new project with Cargo:


This also seems really stilted.

src/doc/rustdoc/src/how-to-write-documentation.md

bors · 2020-09-14T13:07:29Z

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

Note that reviewers usually do not review pull requests until merge conflicts are resolved! Once you resolve the conflicts, you should change the labels applied by bors to indicate that your PR is ready for review. Post this as a comment to change the labels:

@rustbot modify labels: +S-waiting-on-review -S-waiting-on-author

jyn514

This mostly looks good to me - there's a lot of new information, thank you so much! I'm still a little unsure about expanding out all the contractions (especially since some have been missed, and it's now a little inconsistent).

Also this adds a link to the rustdoc book when you pass --help, I'm not sure how I feel about that (#76427 (comment)). Maybe remove it for now and add it to #76427, so this PR won't be blocked on it?

src/doc/rustdoc/src/how-to-write-documentation.md

src/doc/rustdoc/src/what-is-rustdoc.md

AndyGauge · 2020-09-14T19:45:23Z

Thanks for the feedback. Looks like there was an accidental merging of 2 tasks, thanks for identifying that. I'm a bit swamped now, but maybe this weekend I'll put some time into this.

jyn514

I think any more changes can be done as follow-ups, this already looks really good. If you split out the change linking to the rustdoc book I think this ready to go.

GuillaumeGomez · 2020-10-19T09:33:11Z

It just requires to rebase to fix the merge conflict and then it's good to go!

AndyGauge · 2020-10-30T16:58:07Z

I will get this done. We moved and that's been taking all my time lately.

jyn514 · 2020-10-30T17:40:47Z

No worries! Thanks for writing this up, it's super helpful :) If you find you don't have time to finish it up I can rebase it myself, too.

jyn514

Normally we use a rebase-only workflow for PRs: https://rustc-dev-guide.rust-lang.org/git.html#no-merge-policy. Do you mind rebasing this instead to get rid of the merge conflict? There are instructions in https://rustc-dev-guide.rust-lang.org/git.html#rebasing, if you have trouble let me know and I'm happy to help.

src/doc/rustdoc/src/how-to-write-documentation.md

AndyGauge · 2020-11-04T18:26:46Z

I will, this was a 2 step process, making sure my master merge didn’t bring in extra artifacts. I was nervous I might lose my history. Thank you for the instructions!

Co-authored-by: Joshua Nelson <joshua@yottadb.com>

AndyGauge · 2020-11-06T17:15:05Z

@jyn514 we good now?

jyn514 · 2020-11-06T17:16:34Z

Looks great, thanks!

@bors r+

bors · 2020-11-06T17:16:35Z

📌 Commit 881820a has been approved by jyn514

AndyGauge · 2020-11-06T18:36:37Z

wohoo!

bors · 2020-11-06T19:01:16Z

⌛ Testing commit 881820a with merge a601302...

bors · 2020-11-06T21:48:04Z

☀️ Test successful - checks-actions
Approved by: jyn514
Pushing a601302 to master...

rust-highfive assigned GuillaumeGomez Aug 21, 2020

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 21, 2020

GuillaumeGomez reviewed Aug 21, 2020

View reviewed changes

src/doc/rustdoc/src/how-to-write-documentation.md Outdated Show resolved Hide resolved

GuillaumeGomez reviewed Aug 21, 2020

View reviewed changes

src/doc/rustdoc/src/what-to-include.md Show resolved Hide resolved

GuillaumeGomez reviewed Aug 21, 2020

View reviewed changes

src/doc/rustdoc/src/what-to-include.md Outdated Show resolved Hide resolved

GuillaumeGomez reviewed Aug 21, 2020

View reviewed changes

src/doc/rustdoc/src/what-to-include.md Outdated Show resolved Hide resolved

GuillaumeGomez reviewed Aug 21, 2020

View reviewed changes

src/doc/rustdoc/src/what-to-include.md Show resolved Hide resolved

GuillaumeGomez reviewed Aug 21, 2020

View reviewed changes

src/doc/rustdoc/src/what-to-include.md Show resolved Hide resolved

Dylan-DPC-zz reviewed Aug 22, 2020

View reviewed changes

src/doc/rustdoc/src/how-to-write-documentation.md Outdated Show resolved Hide resolved

Dylan-DPC-zz reviewed Aug 22, 2020

View reviewed changes

src/doc/rustdoc/src/how-to-write-documentation.md Outdated Show resolved Hide resolved

ollie27 added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Aug 22, 2020

AndyGauge commented Aug 22, 2020

View reviewed changes

src/doc/rustdoc/src/how-to-write-documentation.md Outdated Show resolved Hide resolved

Dylan-DPC-zz reviewed Aug 22, 2020

View reviewed changes

jyn514 reviewed Aug 22, 2020

View reviewed changes

AndyGauge force-pushed the 75521-rustdoc-book-improvements branch from d7c21eb to 0f605b0 Compare August 22, 2020 15:25

jyn514 reviewed Aug 22, 2020

View reviewed changes

jyn514 reviewed Aug 23, 2020

View reviewed changes

src/doc/rustdoc/src/how-to-write-documentation.md Show resolved Hide resolved

crlf0710 added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 12, 2020

jyn514 mentioned this pull request Sep 14, 2020

Cannot write doc-tests in markdown files #76709

Closed

jyn514 reviewed Sep 14, 2020

View reviewed changes

jyn514 added the A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools label Sep 14, 2020

jyn514 approved these changes Sep 26, 2020

View reviewed changes

jyn514 added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Oct 13, 2020

jyn514 reviewed Nov 4, 2020

View reviewed changes

src/doc/rustdoc/src/how-to-write-documentation.md Outdated Show resolved Hide resolved

Added Rustdoc book sections for linting and embedding more examples

881820a

Co-authored-by: Joshua Nelson <joshua@yottadb.com>

AndyGauge force-pushed the 75521-rustdoc-book-improvements branch from f2c82d7 to 881820a Compare November 5, 2020 02:02

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-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Nov 6, 2020

bors added the merged-by-bors This PR was explicitly merged by bors. label Nov 6, 2020

bors merged commit a601302 into rust-lang:master Nov 6, 2020

rustbot added this to the 1.49.0 milestone Nov 6, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

75521 rustdoc book improvements #75778

75521 rustdoc book improvements #75778

AndyGauge commented Aug 21, 2020 •

edited

Loading

rust-highfive commented Aug 21, 2020

GuillaumeGomez Aug 21, 2020

GuillaumeGomez Aug 21, 2020

AndyGauge Aug 21, 2020

jyn514 Aug 22, 2020

GuillaumeGomez commented Aug 21, 2020

GuillaumeGomez commented Aug 21, 2020

AndyGauge commented Aug 21, 2020

GuillaumeGomez commented Aug 21, 2020

Dylan-DPC-zz left a comment

jyn514 left a comment

jyn514 Aug 22, 2020

jyn514 Aug 22, 2020

bors commented Sep 14, 2020

jyn514 left a comment

AndyGauge commented Sep 14, 2020

jyn514 left a comment

GuillaumeGomez commented Oct 19, 2020

AndyGauge commented Oct 30, 2020

jyn514 commented Oct 30, 2020

jyn514 left a comment

AndyGauge commented Nov 4, 2020 via email •

edited by jyn514

Loading

AndyGauge commented Nov 6, 2020

jyn514 commented Nov 6, 2020

bors commented Nov 6, 2020

AndyGauge commented Nov 6, 2020

bors commented Nov 6, 2020

bors commented Nov 6, 2020

		@@ -1,14 +1,85 @@
		# How to write documentation

		Good documentation is not natural. There are opposing forces that make good


		## Configuring rustdoc

		There's two problems with this: first, why does it

	There's two problems with this: first, why does it
	There are two problems with this: first, why does it

75521 rustdoc book improvements #75778

75521 rustdoc book improvements #75778

Conversation

AndyGauge commented Aug 21, 2020 • edited Loading

rust-highfive commented Aug 21, 2020

GuillaumeGomez Aug 21, 2020

Choose a reason for hiding this comment

GuillaumeGomez Aug 21, 2020

Choose a reason for hiding this comment

AndyGauge Aug 21, 2020

Choose a reason for hiding this comment

jyn514 Aug 22, 2020

Choose a reason for hiding this comment

GuillaumeGomez commented Aug 21, 2020

GuillaumeGomez commented Aug 21, 2020

AndyGauge commented Aug 21, 2020

GuillaumeGomez commented Aug 21, 2020

Dylan-DPC-zz left a comment

Choose a reason for hiding this comment

jyn514 left a comment

Choose a reason for hiding this comment

jyn514 Aug 22, 2020

Choose a reason for hiding this comment

jyn514 Aug 22, 2020

Choose a reason for hiding this comment

bors commented Sep 14, 2020

jyn514 left a comment

Choose a reason for hiding this comment

AndyGauge commented Sep 14, 2020

jyn514 left a comment

Choose a reason for hiding this comment

GuillaumeGomez commented Oct 19, 2020

AndyGauge commented Oct 30, 2020

jyn514 commented Oct 30, 2020

jyn514 left a comment

Choose a reason for hiding this comment

AndyGauge commented Nov 4, 2020 via email • edited by jyn514 Loading

AndyGauge commented Nov 6, 2020

jyn514 commented Nov 6, 2020

bors commented Nov 6, 2020

AndyGauge commented Nov 6, 2020

bors commented Nov 6, 2020

bors commented Nov 6, 2020

AndyGauge commented Aug 21, 2020 •

edited

Loading

AndyGauge commented Nov 4, 2020 via email •

edited by jyn514

Loading