purescript / purescript-docs-search Goto Github PK

The latest version (0.0.9) includes the optional grouping for modules in the sidebar and the index proposed in #20, which is very lovely. While using it I noticed that it could do with some small UX improvements to make it more intuitive:

• module grouping should be on by default, since it's really the better way to look at things
• the project modules don't seem to be included in a package when grouping. I propose that we include them (we can get the project name from the Spago config), and we always list the project package at the top of the list of packages
• clicking on the package name opens up a subtree in the list, but the icon on the left of the name is still a -, which doesn't communicate that it's an expandable item. Some kind of arrow, like ▸, would probably be clearer
• the title (in both the sidebar and the index) is still "Modules", even when grouping by packages

Thoughts?

The problem is that we get a list of modules by looking at particular definitions, so if there are no new definitions in a module, it is non-existent for us.

Currently, the REPL interface only shows the names of constructors for data/newtype declarations like so:

Tuple

tuples                                   Data.Tuple

Additive

prelude                                  Data.Monoid.Additive

I think this can be improved by adding data constructor and newtype constructor prefixes. I'm also currently trying to integrate docs-search into Emacs and having prefixes like this would make it easier to write, considering the output format itself is already easy to parse given how the results are spaced.

data constructor Tuple :: a -> b -> Tuple a b

tuples                                   Data.Tuple

newtype constructor Additive :: a -> Additive a

prelude                                  Data.Monoid.Additive

Any thoughts? I can try working on this later this week as well. I have a working implementation at purefunctor/purescript-docs-search@1518f71

Is it possible to issue a request to the CLI without starting an interactive session?

Steps to replicate:

spago build
spago docs
spago test

So far everything works as expected. But now run

spago docs

again. It does create most of the documentation but fails to create an index and reports an error message that includes "TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension " and warns that it "Failed while trying to make the documentation searchable: 1"

This issue is to track changes in the PureScript compiler that affect docs.json format and may break things for us.

1. purescript/purescript#3715

We want to do it in order to be able to use starsuit as a search engine in the browser.

We want to render comments as markdown, not as plain text.

https://github.com/nonbili/purescript-markdown-it-halogen looks like a solution.

Currently, we are printing the results reversed, so that the most relevant ones appear last. That makes sense, because that way there's no need to scroll. However, using $PAGER when available might be a better option.

As for now we output raw markdown, but this should be changed.

We need to wrap one of Node markdown renderers into a PS interface.

Candidates are:

https://github.com/trabus/markdown-it-terminal

https://github.com/mikaelbr/marked-terminal

The first is preferred, since we are already using markdown-it for HTML rendering.

Contributors are very welcome!

Is this branch good to merge into master? I have a project where build-index has errors without it.

As for now, we do something like fromMaybe defaultCommands <$> getArgs where getArgs :: Effect (Maybe Commands). The default command is Search (i.e. start an interactive CLI session) with some reasonable defaults.

Thus, we are unable to pass arguments to the default command when it's not specified explicitly. E.g. this fails:

purescript-docs-search \
  --bower-jsons ".spago/*/*/bower.json" \
  --bower-jsons "bower_components/purescript-*/bower.json"

We want to build a mapping from packages to modules the right way, instead of scraping package names from source file paths.

"The right way" is to parse bower.jsons.

https://github.com/klntsky/purescript-bower-json is on the way.

Also, we want to include packages and modules in the index.

When trying out the new side bar feature, I realized that the build script is not triggered on running npm install.

I guess if there was an install script it would build to dist and then register the CLI binary in node_modules/.bin so that the following would work:

npm install purescript-docs-search
npm run purescript-docs-search

Sometimes we don't want to pollute the namespace with prelude and other dependencies, i.e. we want to just search the local package.

The Ask:

Make it possible to pass a CLI flag to only include certain packages

Feature request from Slack:

We could fold and hide the modules list for every package name, and show it in a nested list once the user clicks on some arrow

From purescript/spago#534.

Could the command line return JSON/XML/Dhall or some other data output?

Would be great e.g. for third-party integration.

Today I tried the functionality via spago search CLI.
Searching for individual names works great!

But what I miss is some kind of "show everything" or "focus on one module" functionality. Use case: you remember the function you're looking for is in module XYZ, but can't remember its name. I'd like to list all functions from given module. Or maybe I'd like to just go through all names that are available in the docs to explore them.

For example in Haskell's ghci you can type these commands:
:browse - show all things loaded in the repl (just functinn/type names without associated docs)
:browse Module.Name - show list of names in given module

It would be great it this package had similar functionality in CLI :-)

Hi!

Thanks for building and sharing this useful tool!

I'm getting RangeError: Maximum call stack size exceeded for a quite large project. I'm using purs version 0.13.0 at the moment but I'm not sure if this is relevant.
Here is a short stack trace and attached bundle:

[nix-shell:~/programming/purescript/projects/magusai]$ purescript-docs-search build-index                                                                             
Building the search index...
Found 1071 modules.
/home/paluh/programming/purescript/projects/magusai/node_modules/purescript-docs-search/dist/main.js:2317                                                             
      function Cons(value0, value1) {
                   ^

RangeError: Maximum call stack size exceeded
    at new Cons (/home/paluh/programming/purescript/projects/magusai/node_modules/purescript-docs-search/dist/main.js:2317:20)                                        
    at $tco_loop (/home/paluh/programming/purescript/projects/magusai/node_modules/purescript-docs-search/dist/main.js:11934:89)                                      
    at /home/paluh/programming/purescript/projects/magusai/node_modules/purescript-docs-search/dist/main.js:11998:33                                                  
    at Object.shapeOfType (/home/paluh/programming/purescript/projects/magusai/node_modules/purescript-docs-search/dist/main.js:12003:97)                             
    at /home/paluh/programming/purescript/projects/magusai/node_modules/purescript-docs-search/dist/main.js:12047:85                                                  
    at /home/paluh/programming/purescript/projects/magusai/node_modules/purescript-docs-search/dist/main.js:12054:58                                                  
    at /home/paluh/programming/purescript/projects/magusai/node_modules/purescript-docs-search/dist/main.js:2608:59                                                   
    at /home/paluh/programming/purescript/projects/magusai/node_modules/purescript-docs-search/dist/main.js:2608:110                                                  
    at /home/paluh/programming/purescript/projects/magusai/node_modules/purescript-docs-search/dist/main.js:2608:110                                                  
    at /home/paluh/programming/purescript/projects/magusai/node_modules/purescript-docs-search/dist/main.js:2608:110

dist.main.js.zip

Please ping me back if you want me to test or provide additional info.

e.g. $('input').select() is the behavior you want when you want the input to be focused with all of the text selected, so you can readily replace the contents

I would like to merge this repository into the Spago repo - now that everything is PureScript over there I think we can (or at least I can) offer better maintenance if the code is sitting over there.

Thoughts @klntsky?