Medias in odoc

CHANGES.md

@@ -5,6 +5,7 @@
 - Improve jump to implementation in rendered source code, and add a
   `count-occurrences` flag and command to count occurrences of every identifiers
   (@panglesd, #976)
+- Add ability to reference assets (@panglesd, #1002)
 
 # 2.4.0
 

doc/ocamldoc_differences.mld

@@ -30,9 +30,11 @@ The following describes the changes between what [odoc] understands and what’s
 
 {3 Improvements}
 - [odoc] supports writing mathematics and tables with a specific syntax.
+- [odoc] supports the inclusion of medias such as audio, video and image.
 - [odoc] has a better mechanism for disambiguating references in comments. See 'reference syntax' later in this document.
 - Built-in support for standalone [.mld] files. These are documents using the OCamldoc markup, but they’re rendered as distinct pages.
 - Structured output: [odoc] can produce output in a structured directory tree rather a set of files.
+- [odoc] support the inclusion of assets in the structured directory tree.
 - A few extra tags are supported:
   + [@returns] is a synonym for [@return]
   + [@raises] is a synonym for [@raise]
@@ -56,6 +58,7 @@ Additionally we support extra annotations:
 - [instance-variable] refers to instance variables
 - [label] refers to labels introduced in anchors
 - [page] refers to [.mld] pages as outlined above
+- [asset] refers assets as outlined above
 - [value] is recognised as [val]
 
 {3 Referencing items containing hyphens or dots}

doc/odoc_for_authors.mld

@@ -393,13 +393,14 @@ The prefixes supported are:
 - [instance-variable]
 - [section] (and the equivalent deprecated prefix [label]) - for referring to headings
 - [page] - for referring to [.mld] pages
+- [asset] - for referring to assets
 
 In some cases the element being referenced might have a hyphen, a dot or a space in the name,
 e.g. if trying to refer to a page from a [.mld] file "1.2.3.mld". In this case, the
 element name should be quoted with double quote marks:
 
 {v
-{!page-"1.2.3"}
+{!page-"1.2.3"}, {!asset-"file.txt"}
 v}
 
 
@@ -610,6 +611,33 @@ would render as
 The light syntax has the advantages of being arguably more readable for small tables, when viewing the source file directly. However, its content is restricted (for instance, no new line is allowed).
 The heavy syntax is easier to write, can be more readable for big tables, and supports having any kind of content inside. It does not support alignment (yet).
 
+{2 Medias}
+
+Odoc 2.4 introduced new markup for medias. Medias are nestable blocks,
+so they can be put inside lists and tables, but they cannot be
+inlined, for instance in a link..
+
+There are currently three kinds of medias: image, audio, and
+video. Each of them can refer to the file either using an asset
+reference, or a direct link.
+
+The markup is [{<media>:link}], [{<media>!ref}],
+[{{<media>:link}Replacement text}] and [{{<media>:ref}Replacement text}],
+where [<media>] is either [image], [video] or [audio].
+
+The replacement text is used for backends that do not support medias
+(latex and man), and for when a reference is unresolved. In the case
+of an image, it is also used to generate an alternative text.
+
+Images are clickable and links to the image file.
+
+The following source:
+
+{[
+  renders as: {image:https://picsum.photos/200/300}
+]}
+
+renders as: {image:https://picsum.photos/200/300}
 
 {2 Stop Comments}
 

doc/parent_child_spec.mld

@@ -175,17 +175,17 @@ installed and might be used by a different driver.
 In order for drivers to build consistent documentation for a package, the
 following convention should be followed.
 
-- [.mld] pages are installed in a package's [share] directory, under the
+- [.mld] pages and assets are installed in a package's [share] directory, under the
   [odoc-pages] sub-directory.
-- A page is the parent of every installed pages. The driver can freely name this
+- A page is the parent of every installed pages and assets. The driver can freely name this
   page, for example it can be named after the package. In what follows, we
   refer to this page as the [pkg] page.
 - If there is an installed [index.mld] file, the driver has to use it as
   content for the [pkg] page.
 - If there is no installed [index.mld] page, the driver has to generate some
   content for the [pkg] page.
 
-This convention is followed by the
+This convention (excluding assets) is followed by the
 {{:https://github.com/ocaml-doc/voodoo}driver for ocaml.org},
 by the driver {{:https://erratique.ch/software/odig/doc/packaging.html}Odig}
 and by the build system {{:https://github.com/ocaml/dune}Dune}.

src/document/comment.ml

@@ -88,6 +88,7 @@ module Reference = struct
     | `InstanceVariable (p, f) ->
         render_unresolved (p :> t) ^ "." ^ InstanceVariableName.to_string f
     | `Label (p, f) -> render_unresolved (p :> t) ^ "." ^ LabelName.to_string f
+    | `Asset (p, f) -> render_unresolved (p :> t) ^ "." ^ AssetName.to_string f
 
   (* This is the entry point. *)
   let to_ir : ?text:Inline.t -> Reference.t -> Inline.t =
@@ -107,9 +108,9 @@ module Reference = struct
         in
         match Url.from_identifier ~stop_before:false id with
         | Ok url ->
-            let target = InternalLink.Resolved url in
-            let link = { InternalLink.target; content; tooltip } in
-            [ inline @@ Inline.InternalLink link ]
+            let target = Target.Internal (Resolved url) in
+            let link = { Link.target; content; tooltip } in
+            [ inline @@ Inline.Link link ]
         | Error (Not_linkable _) -> content
         | Error exn ->
             (* FIXME: better error message *)
@@ -123,9 +124,9 @@ module Reference = struct
             [ inline @@ Inline.Source s ]
         | Some content ->
             let link =
-              { InternalLink.target = Unresolved; content; tooltip = Some s }
+              { Link.target = Internal Unresolved; content; tooltip = Some s }
             in
-            [ inline @@ Inline.InternalLink link ])
+            [ inline @@ Inline.Link link ])
 end
 
 let leaf_inline_element : Comment.leaf_inline_element -> Inline.one = function
@@ -170,7 +171,7 @@ let rec inline_element : Comment.inline_element -> Inline.t = function
         | [] -> [ inline @@ Text target ]
         | _ -> non_link_inline_element_list content
       in
-      [ inline @@ Link (target, content) ]
+      [ inline @@ Link { target = External target; content; tooltip = None } ]
 
 and inline_element_list elements =
   List.concat
@@ -263,6 +264,38 @@ let rec nestable_block_element :
            and raise warnings *)
       in
       [ block @@ Table { data; align } ]
+  | `Media (href, media, content) ->
+      let content =
+        match (content, href) with
+        | [], `Reference path ->
+            let s = Reference.render_unresolved (path :> Comment.Reference.t) in
+            [ inline @@ Inline.Source (source_of_code s) ]
+        | [], `Link href -> [ inline @@ Inline.Source (source_of_code href) ]
+        | _ -> inline_element_list content
+      in
+      let url =
+        match href with
+        | `Reference (`Resolved r) -> (
+            let id =
+              Odoc_model.Paths.Reference.Resolved.(identifier (r :> t))
+            in
+            match Url.from_identifier ~stop_before:false id with
+            | Ok url -> Target.Internal (Resolved url)
+            | Error exn ->
+                (* FIXME: better error message *)
+                Printf.eprintf "Id.href failed: %S\n%!"
+                  (Url.Error.to_string exn);
+                Internal Unresolved)
+        | `Reference _ -> Internal Unresolved
+        | `Link href -> External href
+      in
+      let i =
+        match media with
+        | `Audio -> Block.Audio (url, content)
+        | `Video -> Video (url, content)
+        | `Image -> Image (url, content)
+      in
+      [ block i ]
 
 and paragraph : Comment.paragraph -> Block.one = function
   | [ { value = `Raw_markup (target, s); _ } ] ->
@@ -308,7 +341,14 @@ let tag : Comment.tag -> Description.one =
   | `See (kind, target, content) ->
       let value =
         match kind with
-        | `Url -> mk_value (Inline.Link (target, [ inline @@ Text target ]))
+        | `Url ->
+            mk_value
+              (Inline.Link
+                 {
+                   target = External target;
+                   content = [ inline @@ Text target ];
+                   tooltip = None;
+                 })
         | `File -> mk_value (Inline.Source (source_of_code target))
         | `Document -> mk_value (Inline.Text target)
       in

src/document/doctree.ml

@@ -65,9 +65,7 @@ end = struct
            | Entity _ as t -> return t
            | Linebreak as t -> return t
            | Styled (st, content) -> return (Styled (st, remove_links content))
-           | Link (_, t) -> t
-           | InternalLink { target = Resolved _; content = t; _ } -> t
-           | InternalLink { target = Unresolved; content = t; _ } -> t
+           | Link { target = _; content = t; _ } -> t
            | Source l ->
                let rec f = function
                  | Source.Elt t -> Source.Elt (remove_links t)
@@ -382,6 +380,9 @@ end = struct
      fun x ->
       match x.desc with
       | Inline x -> inline x
+      | Audio (_, x) -> inline x
+      | Video (_, x) -> inline x
+      | Image (_, x) -> inline x
       | Paragraph x -> inline x
       | List (_, x) -> List.exists block x
       | Table { data; align = _ } ->
@@ -400,8 +401,7 @@ end = struct
      fun x ->
       match x.desc with
       | Styled (_, x) -> inline x
-      | Link (_, x) -> inline x
-      | InternalLink x -> inline x.content
+      | Link { content = t; _ } -> inline t
       | Math _ -> true
       | Text _ | Entity _ | Linebreak | Source _ | Raw_markup _ -> false
     in

src/document/generator.ml

@@ -39,14 +39,14 @@ let type_var tv = tag "type-var" (O.txt tv)
 let enclose ~l ~r x = O.span (O.txt l ++ x ++ O.txt r)
 
 let resolved p content =
-  let link = { InternalLink.target = Resolved p; content; tooltip = None } in
-  O.elt [ inline @@ InternalLink link ]
+  let link = { Link.target = Internal (Resolved p); content; tooltip = None } in
+  O.elt [ inline @@ Link link ]
 
 let path p content = resolved (Url.from_path p) content
 
 let unresolved content =
-  let link = { InternalLink.target = Unresolved; content; tooltip = None } in
-  O.elt [ inline @@ InternalLink link ]
+  let link = { Link.target = Internal Unresolved; content; tooltip = None } in
+  O.elt [ inline @@ Link link ]
 
 let path_to_id path =
   match Url.Anchor.from_identifier (path :> Paths.Identifier.t) with
@@ -1868,8 +1868,7 @@ module Make (Syntax : SYNTAX) = struct
         let li ?(attr = []) name url =
           let link url desc =
             let content = [ Inline.{ attr = []; desc } ] and tooltip = None in
-            Inline.InternalLink
-              { InternalLink.target = Resolved url; content; tooltip }
+            Inline.Link { target = Internal (Resolved url); content; tooltip }
           in
           [ block ~attr @@ Block.Inline (inline @@ link url (Text name)) ]
         in

src/document/types.ml

@@ -5,12 +5,19 @@ module rec Class : sig
 end =
   Class
 
-and InternalLink : sig
-  type target = Resolved of Url.t | Unresolved
+and Link : sig
+  type t = { target : Target.t; content : Inline.t; tooltip : string option }
+end =
+  Link
+
+and Target : sig
+  type internal = Resolved of Url.t | Unresolved
+
+  type href = string
 
-  type t = { target : target; content : Inline.t; tooltip : string option }
+  type t = Internal of internal | External of href
 end =
-  InternalLink
+  Target
 
 and Raw_markup : sig
   type target = Odoc_model.Comment.raw_markup_target
@@ -36,8 +43,6 @@ end =
 and Inline : sig
   type entity = string
 
-  type href = string
-
   type t = one list
 
   and one = { attr : Class.t; desc : desc }
@@ -47,8 +52,7 @@ and Inline : sig
     | Entity of entity
     | Linebreak
     | Styled of style * t
-    | Link of href * t
-    | InternalLink of InternalLink.t
+    | Link of Link.t
     | Source of Source.t
     | Math of Math.t
     | Raw_markup of Raw_markup.t
@@ -90,6 +94,9 @@ and Block : sig
     | Verbatim of string
     | Raw_markup of Raw_markup.t
     | Table of t Table.t
+    | Image of Target.t * Inline.t
+    | Video of Target.t * Inline.t
+    | Audio of Target.t * Inline.t
 
   and list_type = Ordered | Unordered
 end =

src/document/utils.ml

@@ -33,8 +33,7 @@ and compute_length_inline (t : Types.Inline.t) : int =
     | Text s -> acc + String.length s
     | Entity _e -> acc + 1
     | Linebreak -> 0 (* TODO *)
-    | Styled (_, t) | Link (_, t) | InternalLink { content = t; _ } ->
-        acc + compute_length_inline t
+    | Styled (_, t) | Link { content = t; _ } -> acc + compute_length_inline t
     | Source s -> acc + compute_length_source s
     | Math _ -> assert false
     | Raw_markup _ -> assert false