This patch adds vim-like keybindings to the tui viewer: hjkl for
navigation, G and g (instead of gg) for End and Home, and Ctrl+F and
Ctrl+B for Page Down and Up.
In the last patch, we added the termion dependency for the tui viewer.
With this patch, we remove the ansi_term, atty and terminal_size
dependencies and use termion instead.
With this patch, we replace cursive’s default ncurses backend with the
termion backend. This has multiple reasons:
- The ncurses backend has safety issues, see [0].
- ncurses requires a pre-installed library and a C compiler, introducing
additional build dependencies. Termion is implemented in Rust only.
- ncurses does not work on Windows, while termion works in all terminals
that support ANSI escape codes.
Per default, the termion backend does not buffer the output which may
cause flickering [1]. Therefore, we also use the
cursive_buffered_backend that buffers the output and fixes the
flickering problem.
[0] https://github.com/gyscos/cursive/issues/488
[1] https://github.com/gyscos/cursive/issues/142
We’ve moved the HtmlView into a separate crate, so we can replace our
own HtmlView with cursive_markup::MarkupView. We only have to implement
a custom Renderer that applies the syntax highlighting to code snippets.
This patch adds links to the items in the module member list. This only
applies for the tui viewer, as the links wouldn’t provide any additional
information for the plain and rich viewers.
In the previous commit, we used the Option::zip method to make querying
the focus and the links in the HtmlView struct easier. But Option::zip
has only been added in Rust 1.46, so we replace it with a custom utility
function to keep compatibility with Rust 1.40.
This patch adds a new viewer, tui, that provides an interactive
interface using cursive. This viewer makes it possible to follow links
to other documentation items and to open external links in a web
browser.
Previously, we only used the underline effect to highlight links in the
rich viewer, but we did not provide any information about their target.
With this patch, we print a list of link at the end of a block, similar
to the plain text viewer.
We are currently always listing the links in the plain text viewer when
rendering HTML, so we no longer need the show_links field that could be
used to disable link listing.
When changing the viewer to use the text-style crate, we mistakenly
changed the format for links in the rich viewer from underline to bold.
This patch fixes that mistake.
This patch changes the rich viewer to use a custom rich text decorator.
As we use colors to highlight code, and as we print the string text with
a bold font, we don’t need a backtick or an asterix to indicate these
elements.
This patch moves the HTML processing (i. e. syntax highlighting for code
snippets) into the viewer::utils method. This allows us to use it for
other viewers too.
This patch adds syntax highlighting for code blocks in the doc comments.
Previously, we only highlighted the definition of the documented
elements. With this patch, we also highlight code blocks in the doc
blocks, like examples.
This patch updates the html2text dependency to v0.2.1. This release
fixed the handling of preformatted blocks, allowing us to add syntax
highlighting for code blocks in the next patch.
This patch introduces the viewer::utils::Highlighter struct that takes
care of syntax highlighting. This will make it easier to use syntax
highlighting from others viewers once we add them.
This patch replaces the direct text formatting with ansi_term with the
text-style crate. This also allows us to directly convert the syntect
annotations to styled strings.
This patch replaces the crossterm dependency with ansi_term, atty and
terminal_size. This allows us for an easier integration with the
text_style crate in an upcoming patch, and it reduces the total number
of dependencies from 166 to 160.
This means that we drop support for non-ANSI terminals, but as this only
affects old versions of cmd.exe/PowerShell, we don’t care about it.
This patch adds the merge dependency to automatically merge the
command-line arguments and the settings from the configuration file.
This means that we no longer have to manually maintain the Args::merge
function.
This patch introduces the ManRenderer trait that can be used by viewers
that render documentation in a man-like style. This is a more general
version of the previous Printer trait.
This patch adds the viewer::utils module with utility methods for viewer
implementations. It contains common functions for text rendering and
syntax highlighting.
We use the HTML ID of a member element to get its name. If there are
multiple members with the same type and name (e. g. from a Deref
implementation), the ID has a suffix to make it unique. Previosuly, we
just interpreted this suffix as part of the name. With this patch, we
strip the suffix and only use the actual name.
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.
