Add option to force build before extracting doc

[shulhi]

Fix #8040

The rescript-tools doc extracts the docs from cmt files. cmt files require the source code to be rebuilt to refresh them. This adds an option to run the build before extracting the doc so the cmt files are always up to date.

@nojaf @cknitt I'm not sure if this something we want, but I feel this is helpful (or less misleading to the users). Users would expect running the tools will always work without rebuilding.

Another thing to consider is the change in the output when the flag is provided.

 rescript-demo main*​
 ❯ npx rescript-tools doc src/Demo.res --build
[1/3] 🧹 Cleaned 0/1 in 0.00s
[2/3] 🧱 Parsed 1 source files in 0.01s
[3/3] 🤺 Compiled 1 modules in 0.01s

✨ Finished Compilation in 0.02s

{
  "name": "Demo",
  "docstrings": [],
  "source": {
    "filepath": "src/Demo.res",
    "line": 1,
    "col": 1
  },
  "items": [
  {
    "id": "Demo.x",
    "kind": "value",
    "name": "x",
    "signature": "let x: int",
    "docstrings": ["Hello world!!!"],
    "source": {
      "filepath": "src/Demo.res",
      "line": 4,
      "col": 5
    },
    "detail":
    {
      "kind": "signature",
      "details": {
      "returnType": {
        "path": "int"
      }
    }
    }
  }]
}

If the downstream expects a proper JSON, this will break any downstream CLI tools that depends on this.

Marked this as draft as this needs a bit more polishing.

[pkg-pr-new]

Open in StackBlitz

rescript

npm i https://pkg.pr.new/rescript-lang/rescript@8119

@rescript/darwin-arm64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/darwin-arm64@8119

@rescript/darwin-x64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/darwin-x64@8119

@rescript/linux-arm64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/linux-arm64@8119

@rescript/linux-x64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/linux-x64@8119

@rescript/runtime

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/runtime@8119

@rescript/win32-x64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/win32-x64@8119

commit: b6e08f2

[nojaf]

If the downstream expects a proper JSON, this will break any downstream CLI tools that depends on this.

This is quite unusable.

I'm also not convinced we should fix this in a patched up way.
Would take a step back and consider making cmt recompute when doc strings changed instead.

[shulhi]

I'm also not convinced we should fix this in a patched up way. Would take a step back and consider making cmt recompute when doc strings changed instead.

I would agree on that, but the tools read from cmt which requires rebuild anyways to update them (i.e. cmt recompute when we run the build). The doc extraction reads from existing cmt.