Asset references

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

@@ -33,6 +33,7 @@ The following describes the changes between what [odoc] understands and what’s
 - [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 +57,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
+e.g. if trying to refer to a page from a [.mld] file "1.2.3.mld", or to an asset, like a [.txt] file "file.txt". 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}
 
 

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
-  [odoc-pages] sub-directory.
-- A page is the parent of every installed pages. The driver can freely name this
+- [.mld] pages and assets are installed in a package's [doc] directory, under the
+  [odoc-pages] sub-directory. This means that assets with the `.mld` extension are recognized as pages.
+- 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 =

src/model/names.ml

@@ -138,3 +138,4 @@ module LabelName = SimpleName
 module PageName = SimpleName
 module DefName = SimpleName
 module LocalName = SimpleName
+module AssetName = SimpleName

src/model/names.mli

@@ -101,3 +101,5 @@ module PageName : SimpleName
 module DefName : SimpleName
 
 module LocalName : SimpleName
+
+module AssetName : SimpleName

src/model/paths.ml

@@ -1058,6 +1058,10 @@ module Reference = struct
     module Page = struct
       type t = Paths_types.Resolved_reference.page
     end
+
+    module Asset = struct
+      type t = Paths_types.Resolved_reference.asset
+    end
   end
 
   type t = Paths_types.Reference.any
@@ -1143,4 +1147,8 @@ module Reference = struct
   module Page = struct
     type t = Paths_types.Reference.page
   end
+
+  module Asset = struct
+    type t = Paths_types.Reference.asset
+  end
 end

src/model/paths.mli

@@ -546,6 +546,10 @@ module rec Reference : sig
       type t = Paths_types.Resolved_reference.page
     end
 
+    module Asset : sig
+      type t = Paths_types.Resolved_reference.asset
+    end
+
     type t = Paths_types.Resolved_reference.any
 
     val identifier : t -> Identifier.t
@@ -631,6 +635,10 @@ module rec Reference : sig
     type t = Paths_types.Reference.page
   end
 
+  module Asset : sig
+    type t = Paths_types.Reference.asset
+  end
+
   type t = Paths_types.Reference.any
 
   type tag_any = Paths_types.Reference.tag_any

src/model/paths_types.ml

@@ -310,6 +310,8 @@ module Identifier = struct
   type reference_label = label
 
   type reference_page = page
+
+  type reference_asset = asset_file
 end
 
 module rec Path : sig
@@ -548,6 +550,7 @@ module rec Reference : sig
     | `TInstanceVariable
     | `TLabel
     | `TPage
+    | `TAsset
     | `TChildPage
     | `TChildModule
     | `TUnknown ]
@@ -720,9 +723,7 @@ module rec Reference : sig
   (** @canonical Odoc_model.Paths.Reference.Label.t *)
 
   type page =
-    [ `Resolved of Resolved_reference.page
-    | `Root of string * [ `TPage | `TUnknown ]
-    | `Dot of label_parent * string ]
+    [ `Root of string * [ `TPage | `TUnknown ] | `Dot of label_parent * string ]
   (** @canonical Odoc_model.Paths.Reference.Page.t *)
 
   type any =
@@ -742,8 +743,16 @@ module rec Reference : sig
     | `ClassType of signature * ClassTypeName.t
     | `Method of class_signature * MethodName.t
     | `InstanceVariable of class_signature * InstanceVariableName.t
-    | `Label of label_parent * LabelName.t ]
+    | `Label of label_parent * LabelName.t
+    | `Asset of page * AssetName.t ]
   (** @canonical Odoc_model.Paths.Reference.t *)
+
+  type asset =
+    [ `Resolved of Resolved_reference.asset
+    | `Root of string * [ `TAsset ]
+    | `Dot of label_parent * string
+    | `Asset of page * AssetName.t ]
+  (** @canonical Odoc_model.Paths.Reference.Asset.t *)
 end =
   Reference
 
@@ -908,5 +917,8 @@ and Resolved_reference : sig
     | `InstanceVariable of class_signature * InstanceVariableName.t
     | `Label of label_parent * LabelName.t ]
   (** @canonical Odoc_model.Paths.Reference.Resolved.t *)
+
+  type asset = [ `Identifier of Identifier.reference_asset ]
+  (** @canonical Odoc_model.Paths.Reference.Resolved.Asset.t *)
 end =
   Resolved_reference

src/model/reference.ml

@@ -15,16 +15,11 @@ let should_not_be_empty : what:string -> Location_.span -> Error.t =
  fun ~what ->
   Error.make "%s should not be empty." (Astring.String.Ascii.capitalize what)
 
-let not_allowed :
-    ?suggestion:string ->
-    what:string ->
-    in_what:string ->
-    Location_.span ->
-    Error.t =
- fun ?suggestion ~what ~in_what ->
-  Error.make ?suggestion "%s is not allowed in %s."
+let should_be_first :
+    ?suggestion:string -> what:string -> Location_.span -> Error.t =
+ fun ?suggestion ~what ->
+  Error.make ?suggestion "%s is not allowed to have a parent."
     (Astring.String.Ascii.capitalize what)
-    in_what
 
 let deprecated_reference_kind location kind replacement =
   deprecated_reference_kind kind replacement location |> Error.raise_warning
@@ -76,6 +71,7 @@ let match_extra_odoc_reference_kind (_location as loc) s :
       Some `TLabel
   | Some "module-type" -> Some `TModuleType
   | Some "page" -> Some `TPage
+  | Some "asset" -> Some `TAsset
   | Some "value" ->
       d loc "value" "val";
       Some `TValue
@@ -298,6 +294,26 @@ let parse whole_reference_location s :
             |> Error.raise_exception)
   in
 
+  let page (kind, identifier, location) tokens : Page.t =
+    let kind = match_reference_kind location kind in
+    match tokens with
+    | [] -> (
+        match kind with
+        | (`TUnknown | `TPage) as kind -> `Root (identifier, kind)
+        | _ -> expected [ "page" ] location |> Error.raise_exception)
+    | _ :: _ -> (
+        match kind with
+        | (`TUnknown | `TPage) as k ->
+            let suggestion =
+              match k with
+              | `TUnknown -> Printf.sprintf "'%s' should be first." identifier
+              | `TPage -> Printf.sprintf "'page-%s' should be first." identifier
+            in
+            should_be_first ~what:"Page label" ~suggestion location
+            |> Error.raise_exception
+        | _ -> expected [ "page" ] location |> Error.raise_exception)
+  in
+
   let start_from_last_component (kind, identifier, location) old_kind tokens =
     let new_kind = match_reference_kind location kind in
     let kind =
@@ -363,21 +379,19 @@ let parse whole_reference_location s :
         | `TLabel ->
             `Label
               (label_parent next_token tokens, LabelName.make_std identifier)
+        | `TAsset ->
+            `Asset (page next_token tokens, AssetName.make_std identifier)
         | `TChildPage | `TChildModule ->
             let suggestion =
               Printf.sprintf "'child-%s' should be first." identifier
             in
-            not_allowed ~what:"Child label"
-              ~in_what:"the last component of a reference path" ~suggestion
-              location
+            should_be_first ~what:"Child label" ~suggestion location
             |> Error.raise_exception
         | `TPage ->
             let suggestion =
               Printf.sprintf "'page-%s' should be first." identifier
             in
-            not_allowed ~what:"Page label"
-              ~in_what:"the last component of a reference path" ~suggestion
-              location
+            should_be_first ~what:"Page label" ~suggestion location
             |> Error.raise_exception)
   in
 

src/model_desc/paths_desc.ml

@@ -34,6 +34,8 @@ module Names = struct
 
   let labelname = To_string LabelName.to_string
 
+  let assetname = To_string AssetName.to_string
+
   let pagename = To_string PageName.to_string
 
   let parametername = To_string ModuleName.to_string
@@ -200,6 +202,7 @@ module General_paths = struct
       | `TType -> C0 "`TType"
       | `TUnknown -> C0 "`TUnknown"
       | `TValue -> C0 "`TValue"
+      | `TAsset -> C0 "`TAsset"
       | `TChildPage -> C0 "`TChildPage"
       | `TChildModule -> C0 "`TChildModule")
 
@@ -329,7 +332,9 @@ module General_paths = struct
               ((x1 :> r), x2),
               Pair (reference, Names.instancevariablename) )
       | `Label (x1, x2) ->
-          C ("`Label", ((x1 :> r), x2), Pair (reference, Names.labelname)))
+          C ("`Label", ((x1 :> r), x2), Pair (reference, Names.labelname))
+      | `Asset (x1, x2) ->
+          C ("`Asset", ((x1 :> r), x2), Pair (reference, Names.assetname)))
 
   and resolved_reference : rr t =
     Variant

src/xref2/component.ml

@@ -527,6 +527,8 @@ module Element = struct
   (* No component for pages yet *)
   type page = [ `Page of Identifier.Page.t * Odoc_model.Lang.Page.t ]
 
+  type asset = [ `Asset of Identifier.AssetFile.t ]
+
   type label_parent = [ signature | type_ | page ]
 
   type fragment_type_parent = [ signature | datatype ]
@@ -543,7 +545,8 @@ module Element = struct
     | extension
     | extension_decl
     | field
-    | page ]
+    | page
+    | asset ]
 
   let identifier : [< any ] -> Odoc_model.Paths.Identifier.t =
     let open Odoc_model.Paths.Identifier in
@@ -561,6 +564,7 @@ module Element = struct
     | `Extension (id, _, _) -> (id :> t)
     | `ExtensionDecl (id, _) -> (id :> t)
     | `Page (id, _) -> (id :> t)
+    | `Asset id -> (id :> t)
 end
 
 module Fmt = struct
@@ -1499,6 +1503,11 @@ module Fmt = struct
           (parent :> t)
           (LabelName.to_string name)
 
+  and model_resolved_asset_reference ppf
+      (`Identifier id : Odoc_model.Paths.Reference.Resolved.Asset.t) =
+    Format.fprintf ppf "%a" model_identifier
+      (id :> Odoc_model.Paths.Identifier.t)
+
   and model_reference ppf (r : Odoc_model.Paths.Reference.t) =
     let open Odoc_model.Paths.Reference in
     match r with
@@ -1562,6 +1571,23 @@ module Fmt = struct
         Format.fprintf ppf "%a.%s" model_reference
           (parent :> t)
           (LabelName.to_string name)
+    | `Asset (parent, name) ->
+        Format.fprintf ppf "%a.%s" model_reference
+          (parent :> t)
+          (AssetName.to_string name)
+
+  and model_asset_reference ppf (r : Odoc_model.Paths.Reference.Asset.t) =
+    let open Odoc_model.Paths.Reference in
+    match r with
+    | `Resolved r' ->
+        Format.fprintf ppf "r(%a)" model_resolved_asset_reference r'
+    | `Root (name, _) -> Format.fprintf ppf "unresolvedroot(%s)" name
+    | `Dot (parent, str) ->
+        Format.fprintf ppf "%a.%s" model_reference (parent :> t) str
+    | `Asset (parent, name) ->
+        Format.fprintf ppf "%a.%s" model_reference
+          (parent :> t)
+          (AssetName.to_string name)
 end
 
 module LocalIdents = struct

src/xref2/component.mli

@@ -491,6 +491,8 @@ module Element : sig
   (* No component for pages yet *)
   type page = [ `Page of Identifier.Page.t * Odoc_model.Lang.Page.t ]
 
+  type asset = [ `Asset of Identifier.AssetFile.t ]
+
   type label_parent = [ signature | type_ | page ]
 
   type fragment_type_parent = [ signature | datatype ]
@@ -507,7 +509,8 @@ module Element : sig
     | extension
     | extension_decl
     | field
-    | page ]
+    | page
+    | asset ]
 
   val identifier : [< any ] -> Identifier.t
 end
@@ -636,7 +639,13 @@ module Fmt : sig
   val model_resolved_reference :
     Format.formatter -> Odoc_model.Paths.Reference.Resolved.t -> unit
 
+  val model_resolved_asset_reference :
+    Format.formatter -> Odoc_model.Paths.Reference.Resolved.Asset.t -> unit
+
   val model_reference : Format.formatter -> Odoc_model.Paths.Reference.t -> unit
+
+  val model_asset_reference :
+    Format.formatter -> Odoc_model.Paths.Reference.Asset.t -> unit
 end
 
 module Of_Lang : sig