Commit Graph

37 Commits

Author SHA1 Message Date
Robin Krahl
f799d860ca
Import item types from librustdoc
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.
2020-07-22 17:15:00 +02:00
Robin Krahl
bb3b361d02
Improve rendering of module members
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.
2020-07-21 23:55:00 +02:00
Robin Krahl
a97c9e5a0f
Refactor viewer module
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.
2020-07-21 23:24:34 +02:00
Robin Krahl
06851357a2
Extract parse_module_doc from parse_item_doc
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.
2020-07-21 13:55:26 +02:00
Robin Krahl
60cb034c5a
Store item type for items
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.
2020-07-21 13:41:00 +02:00
Robin Krahl
9613235ccc
Store full name in doc::Doc
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.
2020-07-21 12:56:52 +02:00
Robin Krahl
94dff39c8a Introduce Name and Fqn types for names
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.
2020-07-21 12:49:23 +02:00
Robin Krahl
58929bc98b
Use pattern search-index*.js for index files
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.
2020-07-20 13:47:35 +02:00
Robin Krahl
d0c73d2523
List members in module documentation
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.
2020-07-20 11:48:29 +02:00
Robin Krahl
3d4fac0d5c Skip associated types in search index
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.
2020-07-20 10:44:37 +02:00
Robin Krahl
1b8a2c23f6 Fix wrong command in example usage 2020-07-20 10:29:55 +02:00
Robin Krahl
baef1a06b0
Extend contributing guide
This patch extends the CONTRIBUTING.md file with more information on
possible tasks, the test suite and the code checks.
2020-07-20 10:23:28 +02:00
Robin Krahl
a6048238b1
Add doc comment for main.rs
This patch adds a doc comment to the main.rs file that describes the
structure of rusty-man.
2020-07-20 09:20:24 +02:00
Robin Krahl
1128919f1f
Add installation and contributing information
This patch extends the README.md file and adds the INSTALL.md and
CONTRIBUTING.md files with more detailed information.
2020-07-20 01:42:30 +02:00
Robin Krahl
e1ef283159 Check parent for search index items
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.
2020-07-20 01:42:26 +02:00
Robin Krahl
1bd5cf8fbe Add --no-search option
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.
2020-07-20 00:03:59 +02:00
Robin Krahl
f6eaab94a0
Fix path for search index items
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.
2020-07-19 23:48:11 +02:00
Robin Krahl
0c080ab401
Show error message if an item could not be found
With the introduction of the search index, I mistakenly removed the
error message for missing items.  This patch fixes that.
2020-07-19 23:48:05 +02:00
Robin Krahl
bd71f41458
Also match patch in Index::find
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.
2020-07-19 22:44:21 +02:00
Robin Krahl
61fdf31c0a
Read search index from search-index.js
With this patch, we read the search index generated by rustdoc.  It
allows us to suggest matching items if we don’t find an exact match.
2020-07-19 22:23:47 +02:00
Robin Krahl
d4dd4d6548
Run cargo doc before cargo test
This patch fixes the builds by running cargo doc before cargo test.
Without generated documentation, we don’t have anything to test.
2020-07-19 17:39:47 +02:00
Robin Krahl
1204e108cf
Send notification mail on build failure 2020-07-19 17:29:17 +02:00
Robin Krahl
646b36708b
Replace “interface” with “viewer” in description
Previously, we called rusty-man a command-line interface for rustdoc
documentation, but “viewer” is a more appropriate term.
2020-07-19 17:24:38 +02:00
Robin Krahl
5a6a8f43ce Add build scripts
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.
2020-07-19 17:08:01 +02:00
Robin Krahl
c16d7f7d60 Add support for item members
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.
2020-07-19 16:54:30 +02:00
Robin Krahl
ab1d655d39 Load module documentation
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).
2020-07-19 16:52:31 +02:00
Robin Krahl
5d37789837 Ignore BrokenPipe error when piping to pager
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.
2020-07-19 16:51:55 +02:00
Robin Krahl
02b3116ecd Adapt text output to terminal size
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.
2020-07-19 16:04:10 +02:00
Robin Krahl
fdabe11c4a Select default viewer based on TTY
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.
2020-07-19 16:00:26 +02:00
Robin Krahl
96df0924ba Add rich viewer
This patch adds a new viewer with rich text output using html2text’s
from_read_rich function.  We then use termion to format the generated
rich text.
2020-07-19 16:00:20 +02:00
Robin Krahl
7c228e5009 Add custom TextDecorator implementation
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.
2020-07-19 15:44:49 +02:00
Robin Krahl
5ce0365c7f Add --viewer option and plain text viewer
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.
2020-07-19 15:44:21 +02:00
Robin Krahl
0309107bc3 Add default source directories
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.
2020-07-19 15:40:11 +02:00
Robin Krahl
6993df9cb6 Extract documentation from HTML files
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.
2020-07-19 15:40:10 +02:00
Robin Krahl
e6f299635e Implement basic doc item data structures
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.
2020-07-19 15:11:15 +02:00
Robin Krahl
11b6d27b8a Implement command-line interface using structopt
This patch adds the structopt dependency and implements a simple
command-line interface for rusty-man.
2020-07-19 14:11:00 +02:00
Robin Krahl
3967de8bd2 Initial project scaffolding
This patch contains the initial project scaffolding, based on the files
generated by cargo new.
2020-07-19 14:10:54 +02:00