Skip to content

revamp doc-build chapter #1402

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.

Sign up for GitHub

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

Merged
tshepang merged 6 commits into from
Jul 31, 2022
Merged

revamp doc-build chapter #1402

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
66f0e32
revamp doc-build chapter
tshepang Jul 19, 2022
9355ef4
Update src/building/compiler-documenting.md
tshepang Jul 22, 2022
431ada1
summary of chapter
tshepang Jul 30, 2022
90c7bc2
try address review comments
tshepang Jul 30, 2022
8b3d8b1
accept review suggestion
tshepang Jul 31, 2022
e447e36
address review comment
tshepang Jul 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions src/building/compiler-documenting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Building documentation

This chapter describes how to build documentation of toolchain components,
either in whole or individually.
like the standard library (std) or the compiler (rustc).

- Document everything

This uses `rustdoc` from the beta toolchain,
so will produce (slightly) different output to stage 1 rustdoc,
as `rustdoc` is under active development:
as rustdoc is under active development:

```bash
./x.py doc
Expand All @@ -20,8 +20,8 @@ either in whole or individually.
```

First,
the compiler and rustdoc get built to make sure everything is okay,
and then it documents the files.
the compiler gets built to make sure rustdoc compiles,

@jyn514 jyn514 Jul 30, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is super nitpicky and you can ignore it if you like, but I still feel like "make sure rustdoc compiles" is ambiguous. We're not checking that it compiles, we're actually compiling it. I would be less worried about this if it weren't for the fact that check is a cargo/x.py subcommand 😅

Maybe it makes more sense to just say "first rustdoc is built," ?

@tshepang tshepang Jul 31, 2022

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

glad you are "nitpicky"... was not too happy with it, so thanks for this

then that newly-built rustdoc is used to document the components.

- Much like running individual tests or building specific components,
you can build just the documentation you want:
Expand Down