Experimental command to format code blocks embedded in docstrings #7598
Conversation
|
Looking in to why CI fails. |
tools/src/tools.ml
Outdated
| lineCount := currentLine + 1; | ||
| match (lines, !currentCodeBlockContents) with | ||
| | l :: rest, None -> | ||
| if String.trim l = "```rescript" then ( |
There was a problem hiding this comment.
Maybe check with a lowercase compare?
Allowing ReScript as well.
There was a problem hiding this comment.
Lowercase language identifier is the standard for tagging md code blocks. But we should probably add support for ```res as well.
There was a problem hiding this comment.
Feels more like the thing you encountered the most in the wild rather than a hard standard.
https://github.github.com/gfm/#info-string does not mention casing.
zth
force-pushed
the
tools-format-code-blocks-in-docstrings
branch
from
f7f994f to
dc2cc93
Compare
…environments in CI
rescript
@rescript/darwin-arm64
@rescript/darwin-x64
@rescript/linux-arm64
@rescript/linux-x64
@rescript/win32-x64
commit: |
|
@nojaf some tweaking left, but please do play around with it if you want! |
|
Just played with this, looks good!
Not feeling strong about it, though. |
That is probably a case that should be covered by smart printing - when there is a newline between any two labeled args, break. |
| in | ||
| let astMapped = mapper.structure mapper structure in | ||
| Ok | ||
| ( Res_printer.print_implementation |
There was a problem hiding this comment.
nit pre-existing: there are many places in the code base where default_print_width is passed
I guess it would be cleaner for print_implementation to take an optional width argument.
| end | ||
| let formatRescriptCodeBlocks content ~transformAssertEqual ~displayFilename | ||
| ~addError ~markdownBlockStartLine = | ||
| let open Cmarkit in |
There was a problem hiding this comment.
perhaps it might be more readable having all uses of Cmarkit explicit
| hadCodeBlocks := true; | ||
|
|
||
| let currentLine = | ||
| meta |> Meta.textloc |> Textloc.first_line |> fst |> Int.add 1 |
There was a problem hiding this comment.
+ 1 less clever more explicit?
| | ["-h"] | ["--help"] -> logAndExit (Ok formatDocstringsHelp) | ||
| | path :: args -> ( | ||
| let isStdout = List.mem "--stdout" args in | ||
| let transformAssertEqual = List.mem "--transform-assert-equal" args in |
There was a problem hiding this comment.
Looks like this option is only mentioned here, and not shown in help or used in tests
There was a problem hiding this comment.
Yeah it was more a PoC to start out. But I think I'll add it to the help text (and tests) because it'll be useful for the stdlib stuff.
| let block _m = function | ||
| | Block.Code_block (codeBlock, meta) -> ( | ||
| match Block.Code_block.info_string codeBlock with | ||
| | Some ((("rescript" | "res"), _) as info_string) -> |
There was a problem hiding this comment.
do we ever have resi code blocks?
There was a problem hiding this comment.
I guess we could theoretically. Might be good to add support for it, I'll add it.
| let formattedContents, hadCodeBlocks = | ||
| formatRescriptCodeBlocks ~transformAssertEqual ~addError | ||
| ~displayFilename | ||
| ~markdownBlockStartLine:pexp_loc.loc_start.pos_lnum contents |
There was a problem hiding this comment.
Do we know that a code block always takes the whole line? I guess it's a safe assumption to make, at least after normal formatting.
There was a problem hiding this comment.
Yeah I think this should be fine. This is the line in the full source file where the markdown block starts (so the string expr itself). And even if the comment string is a single line, it'll be correct.
But, right now we only process fenced code blocks, and I believe they have to be multiline (at least one for the fenced start, and at least one for the fenced stop, + at least one for code then). So it should be fine.
Adds an experimental command to
toolsfor formatting ReScript code blocks in docstrings.I put it under
toolsjust because that was the easiest place to put it. Feedback gladly accepted on where to put it.I ran formatting on
Stdlib_Result.resiso you can see an example of the results easily.