Support branch-relative paths for docs.to-html

Fixes #4402.

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/fix4402.md

@@ -0,0 +1,20 @@
+```ucm
+.> project.create test-4402
+test-4402/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-4402/main> add
+test-4402/main> docs.to-html some.ns /tmp/test-4402
+```

unison-src/transcripts/fix4402.output.md

@@ -0,0 +1,75 @@
+```ucm
+.> project.create test-4402
+
+  🎉 I've created the project test-4402.
+
+  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-4402/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-4402/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-4402/main> docs.to-html some.ns /tmp/test-4402
+
+```