Skip to content
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.

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

Add some extra pointers for rustdoc frontend devs #2229

Merged
merged 1 commit into from
Jan 29, 2025
Merged
Changes from all commits
Commits
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
9 changes: 9 additions & 0 deletions src/rustdoc.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,10 +58,13 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
* If you want to copy those docs to a webserver, copy all of
`build/host/doc`, since that's where the CSS, JS, fonts, and landing
page are.
* For frontend debugging, disable the `rust.docs-minification` option in [`config.toml`].
* Use `./x test tests/rustdoc*` to run the tests using a stage1
rustdoc.
* See [Rustdoc internals] for more information about tests.

[`config.toml`]: ./building/how-to-build-and-run.md

## Code structure

* All paths in this section are relative to `src/librustdoc` in the rust-lang/rust repository.
Expand All @@ -77,6 +80,7 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
* The tests on the structure of rustdoc HTML output are located in `tests/rustdoc`, where
they're handled by the test runner of bootstrap and the supplementary script
`src/etc/htmldocck.py`.
* Frontend CSS and JavaScript are stored in `html/static/`.

## Tests

Expand All @@ -91,6 +95,11 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
browser-UI-test](https://github.com/GuillaumeGomez/browser-UI-test/) that uses
puppeteer to run tests in a headless browser and check rendering and
interactivity.
* Additionally, JavaScript type annotations are written using [TypeScript-flavored JSDoc]
comments and an external d.ts file. The code itself is plain, valid JavaScript; we only
use tsc as a linter.

[TypeScript-flavored JSDoc]: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html

## Constraints

Expand Down