Skip to content

htmldocck.py: replace outdated doc comment with link to updated docs #131974

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

Jump to bottom
Closed
3 tasks
lolbinarycat opened this issue Oct 20, 2024 · 4 comments · Fixed by #141890
Closed
3 tasks

htmldocck.py: replace outdated doc comment with link to updated docs #131974

lolbinarycat opened this issue Oct 20, 2024 · 4 comments · Fixed by #141890
Assignees
@Derukugis
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools C-bug Category: This is a bug. C-enhancement Category: An issue proposing an enhancement or a PR with one. E-easy Call for participation: Easy difficulty. Experience needed to fix: Not much. Good first issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@lolbinarycat
Copy link
Contributor

lolbinarycat commented Oct 20, 2024 •
edited by rustbot
Loading

the documentation is at

rust/src/etc/htmldocck.py

Lines 4 to 119 in a2a1206

r"""
htmldocck.py is a custom checker script for Rustdoc HTML outputs.
# How and why?
The principle is simple: This script receives a path to generated HTML
documentation and a "template" script, which has a series of check
commands like `@has` or `@matches`. Each command is used to check if
some pattern is present or not present in the particular file or in
a particular node of the HTML tree. In many cases, the template script
happens to be the source code given to rustdoc.
While it indeed is possible to test in smaller portions, it has been
hard to construct tests in this fashion and major rendering errors were
discovered much later. This script is designed to make black-box and
regression testing of Rustdoc easy. This does not preclude the needs for
unit testing, but can be used to complement related tests by quickly
showing the expected renderings.
In order to avoid one-off dependencies for this task, this script uses
a reasonably working HTML parser and the existing XPath implementation
from Python's standard library. Hopefully, we won't render
non-well-formed HTML.
# Commands
Commands start with an `@` followed by a command name (letters and
hyphens), and zero or more arguments separated by one or more whitespace
characters and optionally delimited with single or double quotes. The `@`
mark cannot be preceded by a non-whitespace character. Other lines
(including every text up to the first `@`) are ignored, but it is
recommended to avoid the use of `@` in the template file.
There are a number of supported commands:
* `@has PATH` checks for the existence of the given file.
`PATH` is relative to the output directory. It can be given as `-`
which repeats the most recently used `PATH`.
* `@hasraw PATH PATTERN` and `@matchesraw PATH PATTERN` checks
for the occurrence of the given pattern `PATTERN` in the specified file.
Only one occurrence of the pattern is enough.
For `@hasraw`, `PATTERN` is a whitespace-normalized (every consecutive
whitespace being replaced by one single space character) string.
The entire file is also whitespace-normalized including newlines.
For `@matchesraw`, `PATTERN` is a Python-supported regular expression.
The file remains intact but the regexp is matched without the `MULTILINE`
and `IGNORECASE` options. You can still use a prefix `(?m)` or `(?i)`
to override them, and `\A` and `\Z` for definitely matching
the beginning and end of the file.
(The same distinction goes to other variants of these commands.)
* `@has PATH XPATH PATTERN` and `@matches PATH XPATH PATTERN` checks for
the presence of the given XPath `XPATH` in the specified HTML file,
and also the occurrence of the given pattern `PATTERN` in the matching
node or attribute. Only one occurrence of the pattern in the match
is enough.
`PATH` should be a valid and well-formed HTML file. It does *not*
accept arbitrary HTML5; it should have matching open and close tags
and correct entity references at least.
`XPATH` is an XPath expression to match. The XPath is fairly limited:
`tag`, `*`, `.`, `//`, `..`, `[@attr]`, `[@attr='value']`, `[tag]`,
`[POS]` (element located in given `POS`), `[last()-POS]`, `text()`
and `@attr` (both as the last segment) are supported. Some examples:
- `//pre` or `.//pre` matches any element with a name `pre`.
- `//a[@href]` matches any element with an `href` attribute.
- `//*[@class="impl"]//code` matches any element with a name `code`,
which is an ancestor of some element which `class` attr is `impl`.
- `//h1[@class="fqn"]/span[1]/a[last()]/@class` matches a value of
`class` attribute in the last `a` element (can be followed by more
elements that are not `a`) inside the first `span` in the `h1` with
a class of `fqn`. Note that there cannot be any additional elements
between them due to the use of `/` instead of `//`.
Do not try to use non-absolute paths, it won't work due to the flawed
ElementTree implementation. The script rejects them.
For the text matches (i.e. paths not ending with `@attr`), any
subelements are flattened into one string; this is handy for ignoring
highlights for example. If you want to simply check for the presence of
a given node or attribute, use an empty string (`""`) as a `PATTERN`.
* `@count PATH XPATH COUNT` checks for the occurrence of the given XPath
in the specified file. The number of occurrences must match the given
count.
* `@count PATH XPATH TEXT COUNT` checks for the occurrence of the given XPath
with the given text in the specified file. The number of occurrences must
match the given count.
* `@snapshot NAME PATH XPATH` creates a snapshot test named NAME.
A snapshot test captures a subtree of the DOM, at the location
determined by the XPath, and compares it to a pre-recorded value
in a file. The file's name is the test's name with the `.rs` extension
replaced with `.NAME.html`, where NAME is the snapshot's name.
htmldocck supports the `--bless` option to accept the current subtree
as expected, saving it to the file determined by the snapshot's name.
compiletest's `--bless` flag is forwarded to htmldocck.
* `@has-dir PATH` checks for the existence of the given directory.
* `@files FOLDER_PATH [ENTRIES]`, checks that `FOLDER_PATH` contains exactly
`[ENTRIES]`.
All conditions can be negated with `!`. `@!has foo/type.NoSuch.html`
checks if the given file does not exist, for example.
"""

it has several issues:

  • it is hard to find, not linked to from rustc-dev-guide
  • it has not be updated to reflect the fact the syntax has changed from // @foo to //@ foo.
  • says "only absolute paths are supported", but then requires xpaths to start with //, not /.
@rustbot rustbot added the needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. label Oct 20, 2024
@fmease fmease added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools and removed needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. labels Oct 20, 2024
@fmease fmease self-assigned this Dec 6, 2024
@fmease fmease added C-enhancement Category: An issue proposing an enhancement or a PR with one. C-bug Category: This is a bug. labels Dec 6, 2024
@lolbinarycat
Copy link
Contributor Author

It is actually linked from rustc-dev-guide, but not from where you would expect, only from the "rustdoc internals" section.

https://rustc-dev-guide.rust-lang.org/rustdoc-internals.html#dotting-is-and-crossing-ts

related rustc-dev-guide PR: rust-lang/rustc-dev-guide#2260

@lolbinarycat
Copy link
Contributor Author

mostly fixed by rust-lang/rustc-dev-guide#2295, now all that's left is to remove the outdated doc comment from htmldocck.py and replace it with a link to the correct page of the dev guide.

@lolbinarycat lolbinarycat added the E-easy Call for participation: Easy difficulty. Experience needed to fix: Not much. Good first issue. label May 29, 2025
@lolbinarycat lolbinarycat changed the title rewrite documentation for htmldocck htmldocck.py: replace outdated doc comment with link to updated docs May 29, 2025
@Derukugis
Copy link
Contributor

@rustbot claim

@Derukugis
Copy link
Contributor

Linked the documentation, sorry if i did the pull request wrong, im kind of new.

@Derukugis Derukugis mentioned this issue Jun 2, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@Derukugis Derukugis

Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools C-bug Category: This is a bug. C-enhancement Category: An issue proposing an enhancement or a PR with one. E-easy Call for participation: Easy difficulty. Experience needed to fix: Not much. Good first issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add link to correct documentation in htmldocck.py Derukugis/rust
4 participants
@fmease @lolbinarycat @rustbot @Derukugis