Up to rustdoc version 1.45.2, the code element containing the definition
of a member always had the ID "<name>.v". This ID has been dropped in
rustdoc 1.46.0. Therefore we now look for members by searching for the
heading which has the id "<ty>.<name>" (for all possible types).
This patch refactors the test suite:
- Instead of always generating the documentation with the available
rustdoc version, we now store generated documentation for all
supported rustdoc versions in the test/html directory.
- Instead of using one snapshot per test case, we now use one snapshot
per test case and rustdoc version.
Sometimes, there might be multiple items with the same name, for example
std::u8 is both a module and a primitive. Previously, we could not
determine which one Source::load_doc would return. With this patch, we
add the ty parameter that can be used to filter by the item type.
Previously, we only used the name and the description to represent index
items. Therefore we consider e. g. the std::u8 module and the std::u8
primitive to be the same. With this patch, we also take the item type
into account when comparing index items.
With this patch, we change the type of the Doc::groups field to
BTreeMap<ItemType, Vec<MemberGroup>>. This makes it clearer and easier
to read. We also reorder the ItemType module so that the output order
of the member groups is not changed by this patch.
Previosuly, we used the u8 values for the ItemType variants used in the
search index as the discriminant. But as the ID used in the search
index is an implementation detail of the index parser, this patch moves
the mapping to the index module.
In commit 729414cbfe16324379ac0b886ba65349bbf44ff6, we introduced the
Text struct that wraps HTML and plain text to make it clear what data we
store in the fields of the Doc and Example structs. This patch adds the
Code struct that stores a plain-text representation of code snippets to
make the structs even clearer and to make it easier to transition to
plain-text-only code, e. g. provided by the new JSON backend.
Previously, the doc::ItemType::group_id method returned the ID of the
section for the item type in the HTML documentation files. This patch
refactors the method into the get_item_group_id function in the parser
module as it is an implementation detail of the HTML parser.
This patch introduces the parser::util mod with utility methods for HTML
parsing. These utility methods are members of the new NodeRefExt trait
that is implemented for kuchiki::NodeRef and kuchiki::NodeDataRef<T>.
To avoid parsing the same file multiple times under some circumstances,
we introduce the Parser struct that stores the document node and
provides the public interface of the parser module.
Previously, the Crate, Item and Doc struct made assumptions about the
structure of the documentation source by calling the parser directly.
This works with our current setup with only one documentation format and
one documentation source. But as we intend to add other formats in the
future, we refactor the documentation lookup into the source module
where the format and the source can be taken into account.
This patch adds the --width option to select a fixed output width and
the --max-width to set a maximum output width if the width is
dynamically set using the terminal size.
This patch adds an integration test suite using the insta crate for
snapshot testing. The test suite is tested for all supported Rust
versions and should always succeed for the MSRV (currently 1.40.0) and
the current stable Rust version.
However there are some minor changes in the configuration format between
Rust versions, so tests that don’t work on all supported Rust versions
are marked with the ignore attribute. But even the ignored tests should
work on the stable Rust release.
kuchiki’s NodeRef::text_contents() implementation does not take into
account the value of the display attribute or line breaks caused by br
elements. Therefore we have to implement our own converter that
produces readable output for the HTML code generated by rustdoc.
This patch adds the --config-file option that allows the user to specify
a custom configuration file (or to disable reading configuration files
if the option is set to "-").
With this patch, we load defaults for the command-line arguments from
the configuration file located in the user configuration directory
according to the XDG Base Directory Specification.
This patch crates the args module, renames the Opt struct to Args and
moves it to the new args module. This makes the main.rs file easier to
read and allows us to add more details to the Args struct in the future.
This patch adds two new command-line options for the rich text viewer:
--no-syntax-highlight and --theme. --no-syntax-highlight disables the
syntax highlighting for code snippets. --theme selects a color theme
for the syntax highlighting.
This patch adds the ViewerArgs struct to the Opt struct that contains
the viewer-specific arguments. It also adds a ViewerArgs argument to
the methods of the Viewer trait so that viewers can access these
arguments.
We also refactor the TextViewer implementations so that we can pass the
viewer arguments to the Printer constructor.
Currently, there are no viewer arguments, but we will add them in
upcoming patches.
Previously, we renderer item and member definitions as HTML. With this
patch, we print them as code so that they can be highlighted in the rich
text output.
This patch uses syntect to add syntax highlighting for code snippets in
the rich text output. Currently, this only applies to the examples
printed with the -e/--examples option.
This patch adds the Text struct to the doc module that is a wrapper for
a string that is available as HTML or as plain text. This makes it
clearer what data is stored in the Doc and Example structs and what the
viewers should do with this data.
This patch release adds support for documentation generated with Rust
1.45.0 and fixes some minor bugs in the documentation parser. It also
adds the documentation downloaded using rustup to the default sources.
As described in the previous commit, Rust 1.45 changed the ID of the
methods subheading from "methods" to "implementations". The last patch
fixed this for the trait implementations, this patch updates the method
group parser with the new IDs.
In older Rust versions, trait implementations were listed under the
heading with the id "implementations" and in the div with the id
"implementations-list". Since Rust 1.45, the method heading has the id
"implementations" and the trait implementations have the ids
"trait-implementations" and "trait-implementations-list".
This patch updates the parser with these new IDs while also checking the
old IDs for older documentation.
Previously, we only showed plain text versions of the item descriptions
in the module overview due to a formatting issue. As this issue
disappeared, we can now use the HTML version of the description.
Similar to the fix for functions in 1a242e5, we have to use a different
selector to query the definition for constants, "pre.const" instead of
".docblock.type-decl".
With this patch, we require that the identifier element for a member in
the module documentation is a direct child of the table cell. This
fixes problems with spurious member elements if there are more elements
in the table cell, e. g. stability annotations.
This patch changes the documentation parser for methods to use the first
code child of the subheading as the definition instead of the first
child. This fixes a problems when there is additional information in
the subheading, for example about the relevant traits.
Previously, we were used /usr/share/doc/rust{,-doc}/html as a default
source, assuming that it would contain the standard library
documentation. This is true if the user installed the Rust
documentation manually or using a package manager. If they use rustup
instead, the documentation is placed in a subdirectory of ~/.rustup.
With this patch, we call `rustc --print sysroot` to determine the
installation directory of the currently activated Rust toolchain –
either the system Rust installation or a Rust installation managed by
rustup. We then use `$(sysroot)/share/doc/…` as a default path for the
standard library documentation (with /usr as a fallback if the call to
rustc does not return a valid path).
This patch release adds basic logging output and a new `-e`/`--examples`
option to extract only the examples from the documentation. It also
fixes a bug when displaying the documentation for a function.
As I noticed when trying to debug an issue with a very large HTML file,
we still need more log messages that indicate what is currently going on
in rusty-man. This patch adds some more log messages.
Previosuly, we always used the selector ".docblock.type-decl" to select
the definition for an item. But this did not work for functions.
Therefore we change the selector to "pre.fn" for functions.
This patch adds some basic info log messages to make it easier to debug
incompatible rustdoc output. To show the messages, run rusty-man with
the environment variable RUST_LOG=info.
Robin Krahl