git.iko.soy/rowtype-yoga/purescript-docs-search
on master help sign in
swap
57ff86d5 ahead, 0 behind
11 files changed+94−20
since splitsnapshots
unifiedsplit
.github/workflows/build.yml+2−2 .github/workflows/release.yml+3−3 CHANGELOG.md+14 README.md+4−4 package.json+1−1 src/Docs/Search/Config.purs+1−1 src/Docs/Search/Declarations.purs+28−3 src/Docs/Search/IndexBuilder.purs+4 src/Docs/Search/Interactive.purs+26−1 src/Docs/Search/Main.purs+9−4 src/Docs/Search/SearchResult.purs+2−1
.github/workflows/build.yml+2−2
@@ -12,7 +12,7 @@ jobs:
1212
1313 - uses: actions/setup-node@v2
1414 with:
15− node-version: "14"
15+ node-version: "18"
1616
1717 - uses: purescript-contrib/setup-purescript@main
1818
@@ -41,4 +41,4 @@ jobs:
4141 npm run build
4242 npm test
4343 spago docs --no-search
44− ./dist/purescript-docs-search build-index
44+ ./dist/purescript-docs-search.cjs build-index
.github/workflows/release.yml+3−3
@@ -11,7 +11,7 @@ jobs:
1111
1212 - uses: actions/setup-node@v2
1313 with:
14− node-version: "14"
14+ node-version: "18"
1515
1616 - uses: purescript-contrib/setup-purescript@main
1717
@@ -41,7 +41,7 @@ jobs:
4141 with:
4242 files: |
4343 dist/docs-search-app.js
44− dist/purescript-docs-search
44+ dist/purescript-docs-search.cjs
4545 env:
4646 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
4747
@@ -52,4 +52,4 @@ jobs:
5252 run: |
5353 mv ci-npmrc.txt .npmrc
5454 npm ci
55− npm publish --non-interactive --access public
55+ npm publish --non-interactive --access public
CHANGELOG.md+14
@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
55The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77
8+## [0.0.12 - 2022-08-31]
9+
10+Changes:
11+- Package structure change: `dist/purescript-docs-search.cjs` has been moved to `dist/purescript-docs-search.cjs` due to NodeJS restrictions for `type: module` packages.
12+- Improve output for data and newtype constuctors ([#58](https://github.com/purescript/purescript-docs-search/pull/58))
13+
14+New features:
15+- Docs for each CLI option
16+- New `--source-files` option that allows to specify `.purs` sources (see below)
17+
18+Bugfixes:
19+- Include modules with only re-exports in the module list ([#62](https://github.com/purescript/purescript-docs-search/issues/62))
20+- Fix `docs.json` parser for some types
21+
822## [0.0.11 - 2021-04-15]
923
1024Changes:
README.md+4−4
@@ -1,8 +1,8 @@
11# purescript-docs-search
22
3−[![Build status](https://travis-ci.org/spacchetti/purescript-docs-search.svg?branch=master)](https://travis-ci.org/spacchetti/purescript-docs-search)
3+[![Build status](https://github.com/purescript/purescript-docs-search/actions/workflows/build.yml/badge.svg)](https://github.com/purescript/purescript-docs-search/actions/workflows/build.yml)
44
5−An app that adds search capabilities to generated documentation for purescript code.
5+An app that adds search capabilities to generated documentation for PureScript code.
66
77It supports nearly-all functionality of [Pursuit](https://github.com/purescript/pursuit), including querying by type.
88
@@ -10,7 +10,7 @@ It supports nearly-all functionality of [Pursuit](https://github.com/purescript/
1010
1111When using [spago](https://github.com/spacchetti/spago), you don't need to install this app manually: run `spago docs` or `spago search`.
1212
13−Otherwise, use [npx](https://github.com/npm/npx): `npx purescript-docs-search`.
13+Otherwise, use NPM (`npm install purescript-docs-search`) or [npx](https://github.com/npm/npx): `npx purescript-docs-search`.
1414
1515## Usage
1616
@@ -45,4 +45,4 @@ npm install
4545npm run build # or build-dev to skip JS compression stage
4646```
4747
48−Use `spago docs --no-search && ./dist/purescript-docs-search build-index` to generate the docs and patch them using the local version of the app.
48+Use `spago docs --no-search && ./dist/purescript-docs-search.cjs build-index` to generate the docs and patch them using the local version of the app.
package.json+1−1
@@ -1,7 +1,7 @@
11{
22 "name": "purescript-docs-search",
33 "type": "module",
4− "version": "0.0.11",
4+ "version": "0.0.12",
55 "description": "Search frontend for the documentation generated by the PureScript compiler.",
66 "directories": {
77 "test": "test"
src/Docs/Search/Config.purs+1−1
@@ -7,7 +7,7 @@ import Prelude
77import Data.Newtype (wrap)
88
99version :: String
10−version = "0.0.11"
10+version = "0.0.12"
1111
1212mkShapeScriptPath :: String -> String
1313mkShapeScriptPath shape = "./index/types/" <> shape <> ".js"
src/Docs/Search/Declarations.purs+28−3
@@ -11,7 +11,7 @@ import Prim hiding (Type)
1111import Control.Alt ((<|>))
1212import Data.Array ((!!))
1313import Data.Array as Array
14−import Data.Foldable (foldr)
14+import Data.Foldable (foldl, foldr)
1515import Data.List (List, (:))
1616import Data.List as List
1717import Data.Maybe (Maybe(..), fromMaybe)
@@ -244,8 +244,33 @@ mkChildInfo
244244 (SearchResult { info: parentInfo, moduleName, name: resultName })
245245 (ChildDeclaration { info } )
246246
247− | ChildDeclDataConstructor <- info.declType =
248− info.arguments <#> \arguments -> DataConstructorResult { arguments }
247+ | ChildDeclDataConstructor <- info.declType
248+ , DataResult { dataDeclType, typeArguments } <- parentInfo =
249+ let
250+ parentTypeCtor :: Type
251+ parentTypeCtor = TypeConstructor
252+ $ QualifiedName { moduleNameParts:
253+ String.split (wrap ".") (unwrap moduleName)
254+ , name: resultName }
255+
256+ parentTypeArgs :: Array Type
257+ parentTypeArgs = typeArguments <#> unwrap >>> \{ name } -> TypeVar name
258+
259+ parentType :: Type
260+ parentType = foldl TypeApp parentTypeCtor parentTypeArgs
261+
262+ typeArrow :: Type -> Type
263+ typeArrow =
264+ TypeApp (TypeConstructor (QualifiedName { moduleNameParts: [ "Prim" ]
265+ , name: Identifier "Function" }))
266+
267+ makeType :: Array Type -> Type
268+ makeType = foldr (\a b -> TypeApp (typeArrow a) b) parentType
269+ in
270+ info.arguments <#> \arguments ->
271+ DataConstructorResult { dataDeclType
272+ , "type": makeType arguments
273+ }
249274
250275 | ChildDeclTypeClassMember <- info.declType
251276 , TypeClassResult { arguments } <- parentInfo =
src/Docs/Search/IndexBuilder.purs+4
@@ -192,6 +192,10 @@ decodeDocsJsons cfg@{ docsFiles } = do
192192parseModuleHeaders :: Array String -> Aff (Array ModuleName)
193193parseModuleHeaders globs = do
194194 files <- getPathsByGlobs globs
195+
196+ -- we are not checking if the globs match at least one file, because
197+ -- we want to support scenarios where there is no "current project"
198+
195199 concat <$> for files \filePath -> do
196200 fileContents <- readTextFile UTF8 filePath
197201 case parseModuleName fileContents of
src/Docs/Search/Interactive.purs+26−1
@@ -194,6 +194,9 @@ showSignature result@{ name, info } =
194194 ValueAliasResult ->
195195 yellow ("(" <> unwrap name <> ")")
196196
197+ DataConstructorResult info' ->
198+ showDataConstructorSignature info' result
199+
197200 _ -> yellow $ unwrap name
198201
199202
@@ -294,11 +297,33 @@ showExternDataSignature { kind } { name } =
294297 keyword "foreign data" <>
295298 space <>
296299 yellow (unwrap name) <>
297− space <>
298300 syntax " :: " <>
299301 showType kind
300302
301303
304+showDataConstructorSignature
305+ :: forall rest
306+ . { dataDeclType :: DataDeclType
307+ , "type" :: Type
308+ }
309+ -> { name :: Identifier
310+ | rest
311+ }
312+ -> String
313+showDataConstructorSignature { dataDeclType, type: ctorType } { name } =
314+ ( keyword
315+ case dataDeclType of
316+ NewtypeDataDecl -> "newtype constructor"
317+ DataDataDecl -> "data constructor"
318+ ) <>
319+ space <>
320+ yellow (unwrap name) <>
321+ space <>
322+ syntax "::" <>
323+ space <>
324+ showType ctorType
325+
326+
302327leftShift :: Int -> String -> String
303328leftShift shift str =
304329 Array.intercalate "\n" $
src/Docs/Search/Main.purs+9−4
@@ -1,19 +1,19 @@
11-- | The main module of the CLI interface app.
22module Docs.Search.Main where
33
4−import Prelude
5−
4+import Docs.Search.Config as Config
65import Docs.Search.IndexBuilder as IndexBuilder
76import Docs.Search.Interactive as Interactive
8−import Docs.Search.Config as Config
97import Docs.Search.Types (PackageName(..))
108
9+import Prelude
10+
1111import Data.Generic.Rep (class Generic)
12−import Data.Show.Generic (genericShow)
1312import Data.List as List
1413import Data.List.NonEmpty as NonEmpty
1514import Data.Maybe (Maybe, fromMaybe, optional)
1615import Data.Newtype (unwrap)
16+import Data.Show.Generic (genericShow)
1717import Data.Unfoldable (class Unfoldable)
1818import Effect (Effect)
1919import Effect.Console (log)
@@ -85,6 +85,7 @@ buildIndex = ado
8585 ( long "generated-docs"
8686 <> metavar "DIR"
8787 <> value "./generated-docs/"
88+ <> help "Path to the generated documentation HTML that will be patched. Search app will be injected into each HTML document."
8889 )
8990 noPatch <- flag false true
9091 ( long "no-patch"
@@ -108,6 +109,7 @@ docsFilesOption = fromMaybe defaultDocsFiles <$>
108109 ( strOption
109110 ( long "docs-files"
110111 <> metavar "GLOB"
112+ <> help "Glob that captures `docs.json` files that should be used to build the index"
111113 )
112114 )
113115 )
@@ -119,6 +121,7 @@ bowerFilesOption = fromMaybe defaultBowerFiles <$>
119121 ( strOption
120122 ( long "bower-jsons"
121123 <> metavar "GLOB"
124+ <> help "Glob that captures `bower.json` files. These files are used to build dependency trees to compute package popularity scores based on how many dependants a package has."
122125 )
123126 )
124127 )
@@ -129,6 +132,7 @@ packageNameOption =
129132 ( long "package-name"
130133 <> metavar "PACKAGE"
131134 <> value (unwrap Config.defaultPackageName)
135+ <> help "Local package name as it should appear in the search results"
132136 )
133137
134138sourceFilesOption :: Parser (Array String)
@@ -138,6 +142,7 @@ sourceFilesOption = fromMaybe defaultSourceFiles <$>
138142 ( strOption
139143 ( long "source-files"
140144 <> metavar "GLOB"
145+ <> help "Path to project source files, used for more precise module indexing (see #62). Default: src/**/*.purs"
141146 )
142147 )
143148 )
src/Docs/Search/SearchResult.purs+2−1
@@ -22,7 +22,8 @@ data ResultInfo
2222 | ExternDataResult { kind :: Type }
2323 | TypeSynonymResult { arguments :: Array TypeArgument
2424 , type :: Type }
25− | DataConstructorResult { arguments :: Array Type }
25+ | DataConstructorResult { dataDeclType :: DataDeclType
26+ , type :: Type }
2627 | TypeClassMemberResult { type :: Type
2728 , typeClass :: QualifiedName
2829 , typeClassArguments :: Array TypeArgument }