robzz / cargo-docset Goto Github PK

Describe the bug
I was trying to install cargo-docset via a method that runs tests before installation and noticed that the test test_validate_docset_params_1_into_args is failing.

To Reproduce
cargo test in the crate root

Expected behavior
Tests succeed.

Screenshots

running 5 tests
test tests::test_default_docset_params_into_args_is_empty ... ok
test tests::clap_verify_cli ... ok
test tests::test_validate_matches_docset_params_1 ... ok
test tests::test_validate_docset_params_1_into_args ... FAILED
test tests::test_parse_docset_params_1 ... ok

failures:

---- tests::test_validate_docset_params_1_into_args stdout ----
thread 'tests::test_validate_docset_params_1_into_args' panicked at 'assertion failed: cargo_doc_args.is_empty()', src/main.rs:286:17
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace


failures:
    tests::test_validate_docset_params_1_into_args

test result: FAILED. 4 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

error: test failed, to rerun pass '--bin cargo-docset'

Describe the bug

I got confused, and ran cargo-docset (with a hyphen) rather than cargo docset (two separate words). It didn't like this very much!

After realising that I needed to run cargo, it all worked fine. I installed it with cargo install cargo-docset just now.

Screenshots

$ cargo docset
Cargo configuration error: could not find `Cargo.toml` in `/Users/ben` or any parent directory

$ cargo-docset
thread 'main' panicked at 'called `Option::unwrap()` on a `None` value', src/libcore/option.rs:378:21
stack backtrace:
   0: std::panicking::default_hook::{{closure}}
   1: std::panicking::default_hook
   2: std::panicking::rust_panic_with_hook
   3: std::panicking::continue_panic_fmt
   4: rust_begin_unwind
   5: core::panicking::panic_fmt
   6: core::panicking::panic
   7: cargo_docset::main
   8: std::rt::lang_start::{{closure}}
   9: std::panicking::try::do_call
  10: __rust_maybe_catch_panic
  11: std::rt::lang_start_internal
  12: main

Desktop (please complete the following information):

• OS: macOS 10.14

It's a bit of a pain to install docsets manually. Some quick thoughts on automating this:

• Simply copy/pasting the docset directory works, but Zeal needs to be restarted to pick up the new docset. Doing that and killing/restarting Zeal if it's open is a possibility... The heim crate sounds like the good place to check but it may lack the needed functionality. We'll see.
• Needs to figure out the docset directory. For Zeal, it seems to be stored in an ini like file called Zeal.conf. The dirs crate can probably be used to locate the config file and/or docset directory. Or we use that method as a fallback, and build on #5 and specify it either in the toml file, or in a global toml file (~/.config/cargo-docset.toml or something ?)

Describe the bug
Since removing the cargo dependency, the base workspace directory is not detected properly, which causes errors when doing filesystem operations on the target directory.

To Reproduce
Run the cargo docset command in a package directory that isn't the workspace root.

Expected behavior
No errors.

If anyone encounters said errors and stumbles here, a workaround is to run cargo docset from the workspace root with the --package option, which should normally work. If it doesn't, that's a separate issue, and please report it so it can be investigated.

It failed to install for me because it couldn't find "sqlite3.lib". I've figured out the issue and fixed it, but you should probably mention the dylib dependency in the readme. The rusqlite crate has good docs on how to fix the error, so linking to that crate's readme might be a good idea as well.

Describe the bug
When the build-cache is changed from default [1], running cargo docset fails with an I/O read error.

[1] - https://doc.rust-lang.org/cargo/guide/build-cache.html

To Reproduce
Steps to reproduce the behavior:

I use a shared cache as described in [1] above, a simple test is to override with an environment variable:

bash% CARGO_TARGET_DIR="$HOME/.cargo/target" cargo docset
Running 'cargo clean --doc'...
Running 'cargo doc'...
 Documenting libc v0.2.76
 ...
 Documenting clap v2.33.3
 Documenting testproject v0.1.0 (/home/dstar4138/Code/projects/testproject)
    Finished dev [unoptimized + debuginfo] target(s) in 11.17s
I/O read error: No such file or directory (os error 2)

Expected behavior
Expected the docset directory to be generated within $CARGO_TARGET_DIR/docset.

Screenshots
Not-Applicable.

Desktop (please complete the following information):

• OS: Ubuntu 20.04.1 LTS
• Documentation browser [e.g. dash, zeal]: Zeal
• Version: zeal 0.6.1

Additional context
Add any other context about the problem here.

• Not sure if related: #19
• Feature request: Would be cool to run over the whole shared-cache too.

Describe the bug
When a crate re-exports symbols from a private module, cargo doc still produces html files for these re-exported symbols in the private module, and these files simply redirect to the public location, and omits the private location from the JS search index. Unfortunately cargo-docset is still indexing these private locations.

To Reproduce

$ cargo init --lib --name doctest
$ cat >src/lib.rs <<EOF
mod foo {
    /// Yes this is Bar.
    pub struct Bar;
}
pub use foo::Bar;
EOF
$ cargo docset
$ sqlite3 target/docset/doctest.docset/Contents/Resources/docSet.dsidx 'SELECT * FROM searchIndex;'
1|doctest|Package|doctest/index.html
2|doctest::Bar|Struct|doctest/struct.Bar.html
3|doctest::foo::Bar|Struct|doctest/foo/struct.Bar.html

Expected behavior
The index should look like

1|doctest|Package|doctest/index.html
2|doctest::Bar|Struct|doctest/struct.Bar.html

Screenshots

Desktop (please complete the following information):

• OS: macOS 11.2.3 (20D91)
• Documentation browser [e.g. dash, zeal]: Dash
• Version: cargo-docset 0.2.1

Additional context
These redirection files look like

<!DOCTYPE html>
<html lang="en">
<head>
    <meta http-equiv="refresh" content="0;URL=../../doctest/struct.Bar.html">
</head>
<body>
    <p>Redirecting to <a href="../../doctest/struct.Bar.html">../../doctest/struct.Bar.html</a>...</p>
    <script>location.replace("../../doctest/struct.Bar.html" + location.search + location.hash);</script>
</body>
</html>

It shouldn't be hard to detect the redirection and ignore the symbol.

I also wonder how hard it would be to extract the JSON search index from target/doc/search-index.js and use that to build the docset index? That seems like a more long-term effort though.

See #36 for the feature suggestion

Describe the bug
When building with current master (3e2c9b3), if I'm documenting a workspace with a virtual manifest, the dashIndexFilePath key in the docset's Info.plist is garbage. The resulting value appears to be the first entry in the members list with /index.html tacked on.

In my case, my manifest has

members = [
    "crates/*", "crates-alt/*", "examples/*",
]

And the dashIndexFilePath of the resulting docset is crates/*/index.html.

To Reproduce

1. Run cargo-docset in a workspace that has a virtual manifest with multiple entries in members.

Expected behavior
By default, it shouldn't have a dashIndexFilePath at all, since there's no index file for docs built from a virtual manifest. If I passed RUSTDOCFLAGS='-Z unstable-options --enable-index-page' (or --index-page PATH) then it would ideally be set to the resulting index.html page instead.

Describe the bug
Can't run the plugin in a workspace.
Cargo doc error: failed to parse lock file at: /home/karrq/rust/project/Cargo.lock

To Reproduce
cargo docset

Expected behavior
The program should run and generate a docset

Desktop (please complete the following information):

• OS: Linux Manjaro
• Documentation browser [e.g. dash, zeal]: NA
• Version: NA

Additional context
Normal cargo doc works great.
I tried other commands like specifying a single package but I still got the same error

The current way to do error output is a bit lazy and relies on returning an error from main, which gives us this:

Error: Cargo { source: ErrorMessage { msg: "the lock file /home/robzz/repos/diesel/Cargo.lock needs to be updated but --locked was passed to prevent this" } }

Describe the bug
When using a workspace that uses a virtual manifest, cargo-docset docset panics with

thread 'main' panicked at 'Cargo.toml doesn't have a package table', src/commands/generate.rs:343:18

A virtual manifest workspace is one without a "root" package. cargo doc works just fine here (cargo doc --workspace --open just opens to the first crate in the workspace members list, but it includes all the crates).

It appears that cargo-docset is attempting to look up the root package name here. For virtual manifest workspaces, it would be really great if it could support a flag to provide a docset name, and default to the name of the containing folder. Until such time as cargo doc synthesizes a proper landing page for the docset, cargo-docset could just default to the first member crate exactly as cargo doc does (or it could synthesize a common landing page).

As a workaround, I can invoke cargo-docset docset --all from one of the member crates, but the resulting docset is named after that member crate.

To Reproduce
Steps to reproduce the behavior:

1. Make a virtual manifest workspace (a workspace whose Cargo.toml contains a [workspace] section but not a [package] section)
2. From the root of that workspace, run cargo-docset docset.

Expected behavior
It should build a docset for the workspace.

Describe the bug
Looks like the travis CI is currently broken.

To Reproduce
CI hasn't run for the last PRs.

Expected behavior
CI should have ran.

Additional context
Should probably fix this before next release especially since the last PR includes some unit tests. This might be a good time to look into github actions.

This is a work in progress in the add_ci branch. Linux CI works, but OS X and Windows don't yet, seems to have issues linking with sqlite ?

The current options for generating the documentation are a bit limited. There are quite a few options supported by cargo doc that we don't support yet and would be nice to have. List of cargo doc options I'd like cargo-docset to support in the short to medium term:

• -q, --quiet
• --exclude ... Exclude packages from the build
• --lib Document only this package's library
• --bin ... Document only the specified binary
• --bins Document all binaries
• --features Space-separated list of features to activate
• --all-features Activate all available features
• --no-default-features Do not activate the default feature
• -v, --verbose Use verbose output (-vv very verbose/build.rs output)
• --frozen Require Cargo.lock and cache are up to date
• --locked Require Cargo.lock is up to date
• --offline Run without accessing the network

The following options are for cargo-docset itself:

• -C, --no-clean Don't clean the doc directory before generating the docset

Most of these options don't require many changes on the cargo-docset side, and would only need to be passed on to cargo. Depending on how cargo handles invalid combinations, we might be able to get away without validating the parameters and letting cargo do it for us in most (all?) cases. Adding support for any of these options should be easy enough, should anyone want to contribute.

Describe the bug
After installing the created docset and visiting any page, the documentation is either missing or displays a Loading Content... indicator

To Reproduce
I've tried running cargo docset --all at the root of my workspace on stable (1.40). Same thing happens if I try to generate docsets for individual projects (with cargo docset)

Expected behavior
The full documentation should be displayed

Screenshots

Desktop (please complete the following information):

• OS: macOS 10.15.1
• Documentation browser [e.g. dash, zeal]: Dash
• Version: 5.0.3

Additional context
Not context, just a comment: Thanks for your work on this. Let me know if I can assist in fixing

I'm getting tired with having to specify all the packages I want to document in a workspace. I'd like cargo-docset to read parameters from a toml file (if present/specified), or from the command line otherwise, maybe with the ability to override or add to the parameters from the command line.

I think all that needs to be done is to create the appropriate serializable types (one per command I imagine, and there's only the generate command for now) that we can then deserialize with e.g. serde-toml.

Is your feature request related to a problem? Please describe.
There currently is no way of generating the docsets for multiple crates at once unless those crates are part of the same workspace.

Describe the solution you'd like
Generate docsets for many crates at once by leveraging the cargo build cache. cargo-docset would have to run over the whole build cache. It should also be possible to generate a single docset containing the documentation for the whole build cache. Gotta play with the build cache a bit before settling on how to do this, since I've never really used it.

Additional context
What should the feature look like from a UX perspective ? We could expand the generate command to make it able to achieve this, but it needs to behave so differently in this situation that I'm thinking it might be better as a different command, say generate-cache. The user could then use this feature with the following invocation: cargo docset generate-cache <options>.
The generate command would remain the default, and the simple cargo docset invocation would behave the same as it currently does.

I need to at the very least sleep on this though :)

Describe the solution you'd like
Add a CLI option to rename the generated docset, e.g. --docset-name. This should be useful for virtual manifest workspaces in particular, though the feature should be usable with any docset.

So, this repo started pretty much as an afternoon experiment. Then it grew a little. It's at the point where the code looks pretty damn terrible, so next order of business before implementing any new non trivial features should be to clean it up.

Describe the bug
I just built a docset for my workspace and deps, and to my surprise, all 860 modules have the suffix ::index.

To Reproduce
I ran cargo-docset docset --all from within the first member crate of my workspace (due to #25), then opened the result in Dash.

Expected behavior
The modules list should be correct.

Screenshots

Desktop (please complete the following information):

• OS: macOS 11.2.3 (20D91)
• Documentation browser: Dash 6.0.5
• Version: cargo-docset 0.2.1

Describe the bug
'cargo-docset' installed via 'cargo install' fails to run. The version built from github & installed from there works.

To Reproduce
cargo install cargo-docset
cargo docset

Expected behavior
I'd expect the 'cargo docset' command to run instead of failing.

Screenshots

(pasted from the terminal, tried on few projects with the same result)

➜  Rocket git:(master) RUST_BACKTRACE=1 cargo docset
thread 'main' panicked at 'Cargo.toml doesn't have a package table', /Users/mariusz/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-docset-0.2.1/src/commands/generate.rs:343:18
stack backtrace:
   0: rust_begin_unwind
             at /rustc/a178d0322ce20e33eac124758e837cbd80a6f633/library/std/src/panicking.rs:515:5
   1: core::panicking::panic_fmt
             at /rustc/a178d0322ce20e33eac124758e837cbd80a6f633/library/core/src/panicking.rs:92:14
   2: core::option::expect_failed
             at /rustc/a178d0322ce20e33eac124758e837cbd80a6f633/library/core/src/option.rs:1243:5
   3: cargo_docset::commands::generate::generate
   4: cargo_docset::main
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

Desktop (please complete the following information):

• OS: macOS 11.5
• Documentation browser [e.g. dash, zeal]: dash
• Version: (version of OS or dash?)

First of all thanks for the awesome tool!

The issue is:

Dash couldn't redirect you to the online version of the page you were viewing, because it doesn't know where to find that page.

https://kapeli.com/docsets#onlineRedirection

Why I want this:
On docs.rs, the top toolbar is sometimes helpful (other versions, dependencies, feature flags...)

Not a feature request but an offer for PR.

The other day I stumbled across your project. It works quite well for locally available crates, however I wondered if it could also provide the docs for any other crate without needing to clone them.

As it does not yet, I hacked around your solution a bit and created a solution using the data downloadable at docs.rs. You can find it at https://git.sr.ht/~mlthlschr/cargo-docset/tree . Let me know if you are interested in pulling this functionality into your project. Then I can clean up the code a bit, move the repo to github and create a PR.