Merge pull request #5111 from sellout/docs.to-html-project-support

.github/workflows/ci.yaml

@@ -264,6 +264,14 @@ jobs:
           ${{env.transcripts}}
           # Fail if any transcripts cause git diffs.
           git diff --ignore-cr-at-eol --exit-code unison-src/transcripts
+      - name: docs.to-html
+        if: steps.cache-transcript-test-results.outputs.cache-hit != 'true'
+        run: |
+          ${{env.ucm}} transcript unison-src/transcripts-manual/docs.to-html.md
+          # Fail if the output or generated docs differ.
+          git diff --ignore-cr-at-eol --exit-code \
+            unison-src/transcripts-manual/docs.to-html.output.md \
+            unison-src/transcripts-manual/docs.to-html
       - name: mark transcripts as passing
         if: steps.cache-transcript-test-results.outputs.cache-hit != 'true'
         run: |
@@ -411,7 +419,7 @@ jobs:
   build-jit-binary:
     name: build jit binary
     needs: generate-jit-source
-    uses: ./.github/workflows/ci-build-jit-binary.yaml    
+    uses: ./.github/workflows/ci-build-jit-binary.yaml
 
   test-jit:
     name: test jit

.github/workflows/update-transcripts.yaml

@@ -36,6 +36,9 @@ jobs:
           stack exec unison transcript unison-src/transcripts-manual/rewrites.md
       - name: transcripts
         run: stack exec transcripts
+      - name: docs.to-html
+        run: |
+          stack exec unison transcript unison-src/transcripts-manual/docs.to-html.md
       - name: save transcript changes
         uses: stefanzweifel/git-auto-commit-action@v5
         with:

scripts/check.sh

@@ -6,4 +6,5 @@ true \
   && stack exec transcripts \
   && stack exec unison transcript unison-src/transcripts-round-trip/main.md \
   && stack exec unison transcript unison-src/transcripts-manual/rewrites.md \
+  && stack exec unison transcript unison-src/transcripts-manual/docs.to-html.md \
   && stack exec cli-integration-tests

unison-cli/src/Unison/Codebase/Editor/HandleInput.hs

@@ -470,7 +470,7 @@ loop e = do
               Cli.respond $ Output.MarkdownOut (Text.intercalate "\n---\n" mdText)
             DocsToHtmlI namespacePath' sourceDirectory -> do
               Cli.Env {codebase, sandboxedRuntime} <- ask
-              absPath <- Cli.resolvePath' namespacePath'
+              absPath <- ProjectUtils.branchRelativePathToAbsolute namespacePath'
               branch <- liftIO $ Codebase.getBranchAtPath codebase absPath
               _evalErrs <- liftIO $ (Backend.docsInBranchToHtmlFiles sandboxedRuntime codebase branch sourceDirectory)
               pure ()

unison-cli/src/Unison/Codebase/Editor/Input.hs

@@ -208,7 +208,7 @@ data Input
   | ApiI
   | UiI Path'
   | DocToMarkdownI Name
-  | DocsToHtmlI Path' FilePath
+  | DocsToHtmlI BranchRelativePath FilePath
   | AuthLoginI
   | VersionI
   | ProjectCreateI Bool {- try downloading base? -} (Maybe ProjectName)

unison-cli/src/Unison/CommandLine/InputPatterns.hs

@@ -2768,19 +2768,21 @@ docsToHtml =
     "docs.to-html"
     []
     I.Visible
-    [("namespace", Required, namespaceArg), ("", Required, filePathArg)]
+    [("namespace", Required, branchRelativePathArg), ("", Required, filePathArg)]
     ( P.wrapColumn2
-        [ ( "`docs.to-html .path.to.namespace ~/path/to/file/output`",
-            "Render all docs contained within a namespace, no matter how deep,"
-              <> "to html files on a file path"
+        [ ( makeExample docsToHtml [".path.to.ns", "doc-dir"],
+            "Render all docs contained within the namespace `.path.to.ns`, no matter how deep, to html files in `doc-dir` in the directory UCM was run from."
+          ),
+          ( makeExample docsToHtml ["project0/branch0:a.path", "/tmp/doc-dir"],
+            "Renders all docs anywhere in the namespace `a.path` from `branch0` of `project0` to html in `/tmp/doc-dir`."
           )
         ]
     )
     \case
       [namespacePath, destinationFilePath] ->
         Input.DocsToHtmlI
-          <$> handlePath'Arg namespacePath
-          <*> unsupportedStructuredArgument "a file name" destinationFilePath
+          <$> handleBranchRelativePathArg namespacePath
+          <*> unsupportedStructuredArgument "a directory name" destinationFilePath
       _ -> Left $ showPatternHelp docsToHtml
 
 docToMarkdown :: InputPattern

unison-src/transcripts-manual/docs.to-html.md

@@ -0,0 +1,20 @@
+```ucm
+.> project.create test-html-docs
+test-html-docs/main> builtins.merge
+```
+
+```unison
+{{A doc directly in the namespace.}}
+some.ns.direct = 1
+
+{{A doc pretty deeply nested in the namespace.}}
+some.ns.pretty.deeply.nested = 2
+
+{{A doc outside the namespace.}}
+some.outside = 3
+```
+
+```ucm
+test-html-docs/main> add
+test-html-docs/main> docs.to-html some.ns unison-src/transcripts-manual/docs.to-html
+```

unison-src/transcripts-manual/docs.to-html.output.md

@@ -0,0 +1,75 @@
+```ucm
+.> project.create test-html-docs
+
+  🎉 I've created the project test-html-docs.
+
+  I'll now fetch the latest version of the base Unison
+  library...
+
+  Downloaded 14053 entities.
+
+  🎨 Type `ui` to explore this project's code in your browser.
+  🔭 Discover libraries at https://share.unison-lang.org
+  📖 Use `help-topic projects` to learn more about projects.
+  
+  Write your first Unison code with UCM:
+  
+    1. Open scratch.u.
+    2. Write some Unison code and save the file.
+    3. In UCM, type `add` to save it to your new project.
+  
+  🎉 🥳 Happy coding!
+
+test-html-docs/main> builtins.merge
+
+  Done.
+
+```
+```unison
+{{A doc directly in the namespace.}}
+some.ns.direct = 1
+
+{{A doc pretty deeply nested in the namespace.}}
+some.ns.pretty.deeply.nested = 2
+
+{{A doc outside the namespace.}}
+some.outside = 3
+```
+
+```ucm
+
+  Loading changes detected in scratch.u.
+
+  I found and typechecked these definitions in scratch.u. If you
+  do an `add` or `update`, here's how your codebase would
+  change:
+  
+    ⍟ These new definitions are ok to `add`:
+    
+      some.ns.direct                   : Nat
+      some.ns.direct.doc               : Doc
+      some.ns.pretty.deeply.nested     : Nat
+        (also named lib.base.data.Map.internal.ratio)
+      some.ns.pretty.deeply.nested.doc : Doc
+      some.outside                     : Nat
+        (also named lib.base.data.Map.internal.delta)
+      some.outside.doc                 : Doc
+
+```
+```ucm
+test-html-docs/main> add
+
+  ⍟ I've added these definitions:
+  
+    some.ns.direct                   : Nat
+    some.ns.direct.doc               : Doc
+    some.ns.pretty.deeply.nested     : Nat
+      (also named lib.base.data.Map.internal.ratio)
+    some.ns.pretty.deeply.nested.doc : Doc
+    some.outside                     : Nat
+      (also named lib.base.data.Map.internal.delta)
+    some.outside.doc                 : Doc
+
+test-html-docs/main> docs.to-html some.ns unison-src/transcripts-manual/docs.to-html
+
+```

unison-src/transcripts-manual/docs.to-html/direct/doc.html

@@ -0,0 +1 @@
+<article class="unison-doc"><span class="span"><span class="word">A doc directly in the namespace.</span></span><div class="tooltips" style="display: none;"></div></article>

unison-src/transcripts-manual/docs.to-html/pretty/deeply/nested/doc.html

@@ -0,0 +1 @@
+<article class="unison-doc"><span class="span"><span class="word">A doc pretty deeply nested in the namespace.</span></span><div class="tooltips" style="display: none;"></div></article>