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
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
74 changes: 35 additions & 39 deletions src/building/compiler-documenting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,55 +1,51 @@
# Building documentation

You might want to build documentation of the various components
available like the standard library. There’s two ways to go about this.
You can run rustdoc directly on the file to make sure the HTML is
correct, which is fast. Alternatively, you can build the documentation
as part of the build process through `x.py`. Both are viable methods
since documentation is more about the content.
You can run `rustdoc` directly on a file to make sure the HTML is correct,
which runs quickly.
Copy link
Member

Choose a reason for hiding this comment

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

This seems a little too concise to me. I'd like to talk that this section is to document things on rust-lang/rust like std or submodule docs at first.

Copy link
Member Author

Choose a reason for hiding this comment

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

should I remove this mention... I only kept it because I found it there, and I feel it's not worth a mention

Copy link
Member

@JohnTitor JohnTitor Jul 23, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

and I feel it's not worth a mention

Hmm, why? I think describing what this page talks about at first makes some sense as not all readers will read through the entire chapter.

Copy link
Member Author

Choose a reason for hiding this comment

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

I meant only the part about rustdoc being able to be run on a single file

Copy link
Member

Choose a reason for hiding this comment

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

I mean you removed the "You might want to build documentation of the various components available like the standard library." sentence but the introduction now sounds a little too concise.

Copy link
Member Author

Choose a reason for hiding this comment

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

my latest commit is also concise, but it explains what the chapter is about... whatyouthink

Copy link
Member

Choose a reason for hiding this comment

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

I agree with @JohnTitor, "toolchain components" seems like jargon that won't be familiar to most readers. I think "the various components available, like the standard library or compiler," would be more clear.

A more conventional way is using `/x.py doc`.

## Document everything
- Document everything

This uses the beta rustdoc, which usually but not always has the same output
as stage 1 rustdoc.
This uses `rustdoc` from the beta toolchain,
so will produce (slightly) different output to stage 1 rustdoc,
as `rustdoc` is under active development:

```bash
./x.py doc
```
```bash
./x.py doc
```

## If you want to be sure that the links behave the same as on CI
If you want to be sure the documentation looks the same as on CI:

```bash
./x.py doc --stage 1
```
```bash
./x.py doc --stage 1
```

First the compiler and rustdoc get built to make sure everything is okay
and then it documents the files.
First,
the compiler and rustdoc get built to make sure everything is okay,
and then it documents the files.
Copy link
Member

Choose a reason for hiding this comment

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

hmm, this sentence is saying a lot of complicated things in very few words.

  • rustdoc doesn't check that programs are valid, so you have to run rustc directly to make sure the program compiles
  • rustdoc uses the built metadata to document the compiler (it's very unclear in this sentence whether "it" refers to rustdoc or bootstrap).

unless it's talking about stage1, in which case it's just completely wrong - the reason you have to build rustdoc is so you can run it, because it might be different from the beta rustdoc.

Copy link
Member

Choose a reason for hiding this comment

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

(this is also one of the few cases where --keep-stage 0 is sound - if you've only modified documentation, it can't affect the build artifacts, so it's ok to only rebuild the documentation and not rustdoc itself.)

Copy link
Member Author

Choose a reason for hiding this comment

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

not sure how much detail to provide, but please have a look at the small change I made


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

```bash
./x.py doc src/doc/book
./x.py doc src/doc/nomicon
./x.py doc src/doc/book library
```
```bash
./x.py doc src/doc/book
./x.py doc src/doc/nomicon
./x.py doc compiler library
```

Much like individual tests or building certain components you can build only
the documentation you want.
- Document internal rustc items

## Document internal rustc items
Compiler documentation is not built by default.
To enable it, modify "config.toml":

Compiler documentation is not built by default. To enable it, modify config.toml:
```toml
[build]
compiler-docs = true
```

```toml
[build]
compiler-docs = true
```
Note that when enabled,
documentation for internal compiler items will also be built.

Note that when enabled,
documentation for internal compiler items will also be built.
NOTE: The documentation for the compiler is found at [this link].

### Compiler Documentation

The documentation for the Rust components are found at [rustc doc].

[rustc doc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/
[this link]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/