This patch improves the rendering of module members: Instead of the
full name of the member, we now display only the last part. This also
fixes a bug where we would use the HTML instead of the text content for
the member name.
And we also display the description next to the member name. As we
cannot extract the content of the description element (kuchiki nodes do
not have an inner_html method), we use the text representation instead.
Otherwise we would get formatting problems when rendering the
documentation.
This patch refactors the viewer module:
- The `text` option is renamed to `plain`.
- The TextViewer and RichViewer structs are replaced by a new TextViewer
struct that handles the basic documentation structure and uses a
Printer implementation for formatting.
- The new structs PlainTextRenderer and RichTextRenderer implement the
Printer trait.
- The Printer trait and the TextViewer struct are placed in the
viewer::text module. The Printer implementations are placed in the
plain and rich submodules.
This reduces code duplication and makes it easier to render more complex
documentation items.
Previously, we assumed that we can parse the documentation for a module
and an item (struct, trrait, …) with the same procedure. This approach
was too simple. For example, functions in a module are listed in a
table while the methods of a struct are listed in divs grouped by
subheadings.
Therefore, we extract the parsing of module documentation into a new
function parse_module_doc.
Previously, we assumed that we only have to differentiate between items
(= elements with their own documentation file) and members (= elements
described in the documentation file of their parent). But this model
was too simple. For example, there are big differences in the structure
of a module and a struct documentation file.
Therefore we introduce a new enum, ItemType, that stores the type of an
item. This allows us to drop the member field of the Item struct and to
add the name of the member to the full name of the item.
This patch adds a new field, name, to the doc::Doc struct for
documentation items. It stores the fully qualified name of the
documented element. Since we no longer require a title to identify an
item, we make the title optional. If it is not set, we print the item
name instead.
Previosuly, we used strings to store item names. Sometimes, these
strings would refer to full paths (e. g. kuchiki::NodeDataRef::as_node),
sometimes to local paths (e. g. NodeDataRef::as_node) and sometimes only
to the last item (e. g. as_node).
With this patch, we add two new types: doc::Name is a name without a
semantic meaning, so it could be any of the cases mentioned above.
doc::Fqn is a wrapper around doc::Name that stores fully-qualifier
names, i. e. names where the first element is the crate.
Previously, we always tried to load the search index from the
search-index.js file. But rustdoc may add a suffix to the file name, so
with withs patch, we use the first file that matches the pattern
search-index*.json. This makes it possible to use rusty-man with the
documentation installed by rustup.
This patch adds support for listing the module members on its
documentation page. This is quite easy as the items are displayed in a
single table per item type.
When searching for a keyword, we typically don’t want to match an
associated type. With this patch, we skip associated types when
searching items in the search index.
For members, the path listed in the search index does not point to the
parent item but to the path of the parent item. To get the parent item,
we have to access the parent field and lookup the index in the crate’s
path list.
If there is no exact match for the keyword, we read the search indexes
of all sources. This patch adds the option --no-search that disables
this feature.
rustdoc clears the path of an item in the search index if it is equal to
the path of the previous item (see build_index in html/render.rs).
Previously, we used the crate name if the path was empty. With this
patch, we use the past of the last item instead.
Previously, we only compared the type names when searching for matches
in the search index. With this patch, we also check the path: If the
full name of the item ends with the keyword (prepended with :: to avoid
partial matches), we return a match.
This patch adds three build scripts for the sr.ht CI:
- archlinux.yml is the main build script. It builds the project using
the latest stable release from rustup and executes the tests, clippy
and rustfmt. The build also runs the reuse tool to check compliance
with the reuse specification and verifies that the last commit is
signed by me.
- archlinux-msrv.yml builds and tests the project on the MSRV, currently
Rust 1.40.0.
Previously, we only supported documentation for modules and top-level
items. With this patch, we also display the documentation for members
of an item, typically methods of a struct or trait.
Previously, we could only print documentation for the items listed in
all.html. With this patch, we also load the documentation for modules
(including crates) from the <module>/index.html file. Note that items
are preferred over modules if there is documentation for both (e. g.
std::u8 is both a module and a primitive).
If the pager terminates before we wrote everything to stdout, we get a
BrokenPipe error. We just want to ignore this error but the print*!
macros panic. Therefore we replace the calls to print*! with calls to
write*! and ignore the BrokenPipe error kind when handling the error.
Previously, we wrapped all lines at 100 characters and just printed to
stdout. With this patch, we use the pager crate to spawn a pager
(typically less) before printing the text. Also, we try to use the
terminal size to determine the line length: The default line length is
still 100 characters but can be reduced to fit the terminal.
Previosuly, the plain text viewer was the default option. But for
interactive use, rich text output would be a more sensible default.
With this patch, we check whether we are called from a TTY to choose the
default viewer: rich for interactive use, text for non-interactive use.
html2text’s PlainDecorator that is used to produce plain text prints all
link targets at the end of a block. While this is generally useful,
listing all local links makes the output hard to read. JavaScript and
Rust plaground links are generally not very useful in this context.
Therefore we implement a custom TextDecorator that only lists external
links (http or https) and ignores links to the Rust playground.
This patch adds a new --viewer command line option that lets the user
select a viewer that displays the documentation. It also adds a default
viewer implementation that uses html2text to generate plain text from
the HTML documentation.
html2text requires the ptr_cast feature and we use the Option::as_deref
method in the viewer implementation, so we have to update the minimum
supported Rust version to 1.40.
This patch adds typical Rust documentation locations to the sources:
- /usr/share/doc/rust{,-doc}/html for the standard library documentation
- ./target/doc for the documentation generated for the current crate
It also adds the --no-default-sources option that disables this
behavior.
This patch adds the parser module that uses kuchiki and html5ever to
parse the HTML documentation.
As kuchiki requires std::mem::MaybeUninit, we have to bump the minimum
supported Rust version to 1.36.
This patch adds the doc and source module with the basic data structures
for the documentation items:
- A Source loads the documentation items from e. g. the file system.
- The documentation items (modules, traits, etc.) are grouped by crates.
It also adds a simple Source implementation, DirSource, that reads the
data from a local directory.
