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.
With this patch, we replace the termion dependency with crossterm. This
should make it possible to compile and run rusty-man on other platforms
than Unix.
This patch updates the readme with better usage examples and with the
documentation for rusty-man itself.
Signed-off-by: Robin Krahl <robin.krahl@ireas.org>
rustdoc normalizes the name of a crate by replacing hyphens with
underscores. With this patch, we also perform this normalization when
looking up a crate.
With this patch, we change our rich and plain viewer implementations to
format their output similar to the output of man. This means:
- Adding a title with the current crate, documentation item and
“rusty-man”
- Printing headings at indent levels 0, 3, 6 and printing content with
indent 6, 12
- Printing headings bold and uppercase (level 1) or bold (levels 2, 3)
This patch introduces the helper struct MemberDocs that wraps a Vec<Doc>
that allows us to simplify the parser code. The MemberDocs struct takes
care of creating Doc instances using the names, definitions and
descriptions of member items.
Previosuly, we stored the members as a vector of vectors, group by a
string -- their title. This was very hard to read and also too simple:
For example, there can be multiple blocks of methods in the
documentation for a struct. Therefore we introduce a new type,
MemberGroup, that represents a group of member items with an optional
title.
Previously, we only displayed the member name when viewing the
documentation of a member. With this patch, we use the ItemType enum to
also print the type of the member.
For consistency, we remove the title field from doc::Doc that was
previously used for the titles of modules and items and use the same
title as for members. While we lose the links to the parent items,
these were not particularly helpful anyway. If we want to, we could
also generate them from the item name.
Previously, we maintained a list of headings and HTML element IDs for
item types in parser.rs. As we now have a complete ItemType enum, we
can use ItemType methods to provide this data.
Some elements, for example std::io::ErrorKind, have nested docblocks in
their type-decl docblock. This would lead to a wrong description
because we pick the first non-type-decl docblock for the description.
With this patch, we require that the description docblock is a direct
child of #main to fix this issue.
Previously, our ItemType enum only had three values: Module, Item and
Member. With this patch we import the ItemType variants from librustdoc
(see html/item_type.rs) for better compatibility and easier parsing.
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.
Robin Krahl