diff --git a/doc/deprecated/dune b/doc/deprecated/dune new file mode 100644 index 0000000000..402f7e40da --- /dev/null +++ b/doc/deprecated/dune @@ -0,0 +1,6 @@ +(install + (section doc) + (files + (parent_child_spec.mld as odoc-pages/deprecated/parent_child_spec.mld) + (index.mld as odoc-pages/deprecated/index.mld)) + (package odoc)) diff --git a/doc/deprecated/index.mld b/doc/deprecated/index.mld new file mode 100644 index 0000000000..a1b3ee96e5 --- /dev/null +++ b/doc/deprecated/index.mld @@ -0,0 +1,4 @@ +{0 Deprecated features} + +Odoc 2.x had a different way to specify the hierarchy of the output pages. This still works, +though it is deprecated. Documentation for the feature may be found {{!page-parent_child_spec}here}. diff --git a/doc/parent_child_spec.mld b/doc/deprecated/parent_child_spec.mld similarity index 100% rename from doc/parent_child_spec.mld rename to doc/deprecated/parent_child_spec.mld diff --git a/doc/driver.mld b/doc/driver.mld index 775ec8c3b7..720fb40ce1 100644 --- a/doc/driver.mld +++ b/doc/driver.mld @@ -7,12 +7,12 @@ through several distinct phases until the HTML output is generated. For this reason, just like for building any multifiles OCaml project, [odoc] needs to be driven by a higher level tool. The driver will take care of calling the [odoc] command with the right arguments throughout the different -phases. Several drivers for [odoc] exist, such as: -{{:https://dune.readthedocs.io/en/stable/documentation.html}dune} and -{{:https://erratique.ch/software/odig}odig}. +phases. The {{!/odoc-driver/page-index}odoc-driver} package contains a "reference driver", that is kept up-to-date +with the latest development of [odoc], -The [odoc] tool also contains a "reference driver", that is kept up-to-date -with the latest development of [odoc]. +Several drivers for [odoc] exist, such as: +{{:https://dune.readthedocs.io/en/stable/documentation.html}dune} and +{{!/odig/page-index}odig}. This document explains how to drive [odoc], as of version 3. It is not needed to know any of this to {e use} [odoc], it is targeted at driver authors, tools that diff --git a/doc/driver/dune b/doc/driver/dune new file mode 100644 index 0000000000..9a1a4e0be5 --- /dev/null +++ b/doc/driver/dune @@ -0,0 +1,7 @@ +(documentation + (package odoc-driver)) + +(install + (section doc) + (files odoc-config.sexp) + (package odoc-driver)) diff --git a/doc/driver/index.mld b/doc/driver/index.mld new file mode 100644 index 0000000000..e9d09d2dee --- /dev/null +++ b/doc/driver/index.mld @@ -0,0 +1,93 @@ +{0 The odoc reference driver} + +{1 Quickstart} + +To produce HTML documentation for your package [pkg] and its dependencies, first ensure that it is installed in your +opam switch, then run: + +{@sh[ +odoc_driver +]} + +The output will appear in the directory `_html` by default. + +{1 Introduction} + +[odoc_driver] is a tool that can be run to create and validate HTML documentation for OCaml packages. +This includes the documentation comments in the interfaces and implementations of the modules, as well +as [mld] files and their associated assets. In addition, the source code of the modules, if available, +will be rendered with syntax highlighting and links. Also included is per-package search powered by +{{!/sherlodoc/page-index}Sherlodoc}, and a global sidebar allowing easy navigation around the docs. It +has a small number of options to allow for modification of the layout of what's produced. + +{2 Drivers} + +[odoc_driver] is actually three drivers: + +- [odoc_driver] - The standard driver. +- [odoc_driver_voodoo] - The driver adapted for producing the documentation used by ocaml.org. +- [odoc_driver_monorepo] - An experimental driver for producing documentation of a dune-managed monorepo. + +What follows applies mostly to the first of these. + +{2 Documentation errors} + +[odoc_driver] will report errors that it discovers while generating documentation. In order that these +errors can be fixed easily, it will ony report errors that are found within the packages that are selected +on the command line, as opposed to those found in dependency packages. The errors will be reported on +completion of the run. For example: + +{@sh[ +$ odoc_driver odoc-parser +Deciding which packages to build... +Performing module-level dependency analysis... +Starting the compilation process... +Documentation generation complete. Results are in _html/ +Output from commands: +/tmp/odoc-5f6831/odoc-parser/odoc-parser/odoc_parser.odoc +--------------------------------------------------------- +File "src/parser/odoc_parser.mli", line 45, characters 30-45: +Warning: Failed to resolve reference unresolvedroot(parse_coment) Couldn't find "parse_coment" +]} + +which highlights + +{2 Remapping dependencies} + +When producing documentation for OCaml projects, there are often links to types, modules, values and +other items defined in other packages. In order that a complete set of documentation files is produced +therefore, by default the documentation of the dependencies is produced. This may not always be +desirable, so an option has been added to redirect links that would otherwise have gone to dependency +documentation such that they instead link to the equivalent documentation page hosted on +{{:ocaml.org}https://ocaml.org}. In order to enable this, pass the argument [--remap] to [odoc_driver]. + +When run in this mode, the main index page will by default only list those packages whose documentation +has been built. + +{2 Overriding the main index} + +The main index by default is a simple list of the packages that have been documented. This can be +overridden by the `--index-mld` flag, which takes a path to an [mld] formatted file that will be used +in place of the autogenerated one. All packages and all libraries are included in the scope of this +page and therefore any built package can be linked to via the syntax + +{[ +{!//page-index} +]} + +and any library can be linked to via the syntax + +{[ +{!//} +]} + +{2 JSON output} + +When the option [--json-output] is passed to the driver, instead of producing HTML files it +will instruct odoc to produce json output where the HTML would otherwise be. See the {{!/odoc/page-json}odoc documentation} +for this feature. + +The per-page JSON output is written into the HTML output directory alongside where the HTML pages would ordinarily be, +and the per-package sidebar is written to the package directory (ie, for package [odoc], with html output dir set to +the default [_html], the sidebar JSON file is [_html/odoc/sidebar.json]. + diff --git a/doc/driver/odoc-config.sexp b/doc/driver/odoc-config.sexp new file mode 100644 index 0000000000..1f541f6f45 --- /dev/null +++ b/doc/driver/odoc-config.sexp @@ -0,0 +1 @@ +(packages odoc sherlodoc) diff --git a/doc/dune b/doc/dune index 417271a65d..68f04cb0e8 100644 --- a/doc/dune +++ b/doc/dune @@ -9,7 +9,7 @@ ocamldoc_differences odoc_for_authors cheatsheet - parent_child_spec)) + json)) ; Uncomment to run mdx on the documentation's code blocks. ; (mdx diff --git a/doc/json.mld b/doc/json.mld new file mode 100644 index 0000000000..90156b9083 --- /dev/null +++ b/doc/json.mld @@ -0,0 +1,121 @@ +{0 JSON output} + +In order to embed the output of odoc within another website, +the html generator for odoc has a mode where instead of producing HTML files, it will produce JSON files +where the HTML files would have been. For example, if the HTML generator would have produced a file +[/x/y/z/index.html], then when the [--as-json] flag is passed to [odoc html-generate], it will instead +write the file [/x/y/z/index.html.json]. + +In addition, there is a per-package 'global' sidebar json file. + +{1 Example page JSON} + +{@json[ +{ + "type": "documentation", + "uses_katex": false, + "breadcrumbs": [ + { + "name": "🏠", + "href": "../../../index.html", + "kind": "leaf-page" + }, + { + "name": "ocaml-base-compiler", + "href": "../../index.html", + "kind": "leaf-page" + }, + { + "name": "stdlib", + "href": null, + "kind": "leaf-page" + }, + { + "name": "Stdlib", + "href": "#", + "kind": "module" + } + ], + "toc": [ + { + "title": "Exceptions", + "href": "#exceptions", + "children": [] + }, + { + "title": "Integer arithmetic", + "href": "#integer-arithmetic", + "children": [ + { + "title": "Bitwise operations", + "href": "#bitwise-operations", + "children": [] + } + ] + }, + "source_anchor": "../../src/stdlib/stdlib.ml.html", + "preamble": "

The OCaml Standard library.

This module is automatically opened at the beginning of each compilation. All components of this module can therefore be referred by their short name, without prefixing them by Stdlib.

In particular, it provides the basic operations over the built-in types (numbers, booleans, byte sequences, strings, exceptions, references, lists, arrays, input-output channels, ...) and the standard librar +y modules.

", + "content": "

Exceptions

Sourceval raise : exn -> 'a
< +p>Raise the given exception value

], [class], [class-type], [file] or [source] +- [toc] contains the table-of-contents for the page. This consists of a list of objects containing fields [title], [href] and [children]. [title] is a string containing HTML. [href] is the anchor in the page, and [children] is a list of more of these entries representing the sub-items in the table-of-contents. +- [source_anchor] is the URL of the corresponding source file, if it exists. +- [preamble] is a string containing HTML for the preamble of the page. +- [content] is a string containing HTML for the main content of the page. + +The data contained in these JSON files can be used to embed the HTML as rendered by odoc into a more complex site. +The main requirement is that it is expected that an HTML page will exist at every location where a JSON file has been written. +This is to ensure that relative links work. + + +{1 Example sidebar json} + +{@json[ +[ + { + "node": { + "url": "ocaml-base-compiler/index.html", + "kind": "leaf-page", + "content": "ocaml-base-compiler" + }, + "children": [ + { + "node": { + "url": null, + "kind": null, + "content": "compiler-libs.bytecomp" + }, + "children": [ + { + "node": { + "url": "ocaml-base-compiler/compiler-libs.bytecomp/Bytegen/index.html", + "kind": "module", + "content": "Bytegen" + }, + "children": [] + }, + { + "node": { + "url": "ocaml-base-compiler/compiler-libs.bytecomp/Bytelibrarian/index.html", + "kind": "module", + "content": "Bytelibrarian" + }, + "children": [] + ... +]} + +The 'global' sidebar JSON file consists of a list of objects, each containing a [node] field and a [children] field. +The [node] field contains an object containing a [url], [kind] and [content]. The [kind] page is similar to that in the breadcrumbs above. +The [content] field is an HTML string, and the [url] field is a string. \ No newline at end of file diff --git a/doc/odoc-config.sexp b/doc/odoc-config.sexp index 2b07de72ba..6618575e08 100644 --- a/doc/odoc-config.sexp +++ b/doc/odoc-config.sexp @@ -1,2 +1,2 @@ (libraries fmt) -(packages cmdliner) +(packages odoc-driver cmdliner odig sherlodoc) diff --git a/doc/odoc.mld b/doc/odoc.mld index 5d4ee6e454..fffd805ca5 100644 --- a/doc/odoc.mld +++ b/doc/odoc.mld @@ -1,5 +1,5 @@ -@children_order dune odoc_for_authors cheatsheet features ocamldoc_differences interface parent_child_spec driver -@short_title [odoc] +@children_order odoc_for_authors cheatsheet dune features ocamldoc_differences interface driver json deprecated/ +@short_title The odoc documentation generator {0 The [odoc] documentation generator} @@ -41,23 +41,11 @@ module types, and more. So if you've ever been baffled by exactly what the [t] w - an {e expander}, which can expand complex module-type expressions while preserving their structure, including comment, includes, and more. If you've ever wondered what values there are in your module [M : Base.Applicative.S with type t := u], [odoc] will show you! -{1 For Library Authors} +{1 For Authors} -For guidance on how to document your OCaml project, see {{!page-odoc_for_authors}[odoc] for authors}. +For guidance on how to document your OCaml project, see {!page-odoc_for_authors}. {1 For Integrators} To integrate [odoc] into your tool, webpage or any other setting, you'll need to understand {{!page-driver}how to drive [odoc]}. - -{1 Page Index} - -The main other pages of this site: -- {!page-odoc_for_authors} gives information for [odoc] authors. -- {!page-cheatsheet} provides a quick quide for [odoc] markdown. -- {!page-features} explores [odoc]'s language features. -- {!page-driver} describes how [odoc] produces documentation. -- {!page-ocamldoc_differences} outlines differences from OCamldoc. -- {!page-dune} shows how to create docs using Dune. -- {!page-parent_child_spec} delineates parent/child specifications. -- {!page-interface} describes [odoc]'s public-facing interface and their support guarantees. diff --git a/doc/odoc_for_authors.mld b/doc/odoc_for_authors.mld index e9bd2ef927..ddb7a81776 100644 --- a/doc/odoc_for_authors.mld +++ b/doc/odoc_for_authors.mld @@ -15,6 +15,17 @@ To generate documentation for your project, you will almost always be using 'drivers' of [odoc] at time of writing, each with their own strengths and weaknesses: +- {{!/odoc-driver/page-index}The reference driver} is the most up-to-date driver, + and incorporates all of the features of odoc. It is written to build the docs + locally as well as those published on ocaml.org. It does not feature fast rebuilds, + nor keeping a switch-wide cache of documentation. Install the driver and the package to document via + [opam] and run +{v +$ opam install odoc-driver +$ odoc_driver +v} + to build the docs. The output will appear in the directory `_html` by default. + Full documentation is available in the {{!/odoc-driver/page-index}reference driver package}. - {{:https://dune.build/}Dune} is the best way to view docs while developing your project. We have a {{!page-dune}page} describing how to use it, but the short version is: @@ -27,15 +38,70 @@ v} {v $ odig doc odig v} -- {{!page-driver}The reference driver} is the simplest driver, useful if you - want to see how to integrate it with your own projects. -- {{:https://github.com/ocaml-doc/voodoo}Voodoo} is the driver used to create - the docs for {{:https://ocaml.org/packages}the OCaml website}. + +{1:packagedocs Documenting a package} + +Documentation in OCaml is grouped together by {i package}. Each package may contain +a number of documentation pages, organised into a hierarchy, and if the +package contains {i libraries}, their interfaces form the rest of the package documentation. +The pages are written in a subset of the usual {{!page-ocamldoc_differences}odoc markup}, +and the libraries are documented via in-line special comments in the source. +Conceptually, the docs for every library are {i contained within} the docs of its package. + +{2 Quickstart} + +When a package is built with [dune], the simplest way to include docs in your package is +to create a [doc] dir, write [doc/index.mld] file containing the documentation for your +package: + +{v +{0 My package documentation} + +This is the documentation for my package! +v} + +then create the following [doc/dune] file: + +{v +(documentation) +v} + +More mld files can be added as necessary to the [doc] directory, and they will be included +also. + +This will work if you've only got one package defined in your dune project. If you've got +more than one, you'll need to let dune know which package the docs are associated with: + +{v +(documentation + (package my_package)) +v} + +Any assets you have will also need to be handled, and as this is a new feature in odoc 3, +at time of writing dune does not have a convenient syntax for this. However, it still can +be done, so if, for example, you have an image [asset.jpg] that you'd like to include in your +doc, you can add the following to your [doc/dune] file: + +{v +(install + (section doc) + (files (asset.jpg as odoc-pages/asset.jpg))) +v} + +Odoc 3.0 introduces a per-package configuration file, {{!section-config-file}odoc-config.sexp}, which is important if you'd like your +documentation to link to the docs of other packages or libraries. If your documentation needs +this configuration file, this will also need to be installed as follows: + +{v +(install + (section doc) + (files odoc-config.sexp)) +v} {1:interfaces Documenting Your Interfaces} -[odoc] is built to produce documentation for your {e libraries}, and the unit of -organisation is the {e module}. Documentation is written by putting +As well as doc pages, [odoc] is built to produce documentation for your {e libraries}, +and the unit of organisation for these is the {e module}. Documentation is written by putting {{!special_comments}special comments} into the source of the {e module interface} or, less commonly, your {e module implementation}. @@ -399,6 +465,11 @@ This is useful if there are several identifiers [bar] in module [Foo], e.g., a t - [odoc]: [ {!module-Foo.type-bar} ] - each element in the path may be prefixed by its type. This is useful if there are ambiguous elements in any part of the path, e.g., in this case perhaps there is a module type [Foo]. +- [odoc3]: [ {!/library_name/Module} ] - this is a path to them module [M] in library [library_name]. +This is useful if the module name is ambiguous, e.g., if there are two modules [M] in different libraries. +You may need to add the library to the per-package config file. +- [odoc3]: [ {!/package/path/to/page-foo} ] - this is a path to a page [foo] in the package [package]. +The package will need to be added to the per-package config file. The prefixes supported are: - [module] @@ -663,13 +734,13 @@ 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:media Medias} +{2:media Media} -Odoc 3.0 introduced new markup for medias. Medias are nestable blocks, +Odoc 3.0 introduced new markup for media. Media 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 +There are currently three kinds of media: image, audio, and video. Each of them can refer to the file either using an asset reference, or a direct link. @@ -681,7 +752,7 @@ relative or absolute. The markup for videos and audios is similar, replacing [image] by respectively [video] and [audio]. -The replacement text is used for backends that do not support medias +The replacement text is used for backends that do not support media (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. @@ -878,8 +949,13 @@ contents and thus should be used to introduce examples, comments, or other complementary notes. An alternative would be to consider splitting into multiple files. -Finally, documentation pages should start with a level-0 heading, see -{!section-"page-title"}. Level-0 headings should not be used elsewhere. +Finally, documentation pages should start with a level-0 heading: + +{v +{0 Title of the page} +v}. + +Level-0 headings should not be used elsewhere. The syntax for declaring sections is as follows: @@ -932,49 +1008,36 @@ you can use the following syntax: See {!page-a.foo} for details v} -{1:doc-pages Writing Documentation Pages} - -Files with the [.mld] extension are called {e documentation pages} and should -be used to complement API references with tutorials or guides. They are -particularly suitable for OCaml and Reason because cross-references to -definitions, both in the current package and for external packages, are -supported. - -{2 Markup} - -The format of these [.mld] files is simply text that should be marked-up with -the usual [odoc] markup as described on this page. A documentation page can be seen -as a single regular docstring in a separate file. +{1:config-file Configuration file} -{2 Page Title} +[odoc] 3.0 introduced a per-package configuration file, [odoc-config.sexp]. This file is required if you +wish to make use of the cross-package linking feature, or sometimes if you wish to link to other libraries. -When defining a documentation page, make sure to supply a page title, as one is -not generated by default (unlike for API reference documents where the module -or module type name is used). The level-0 heading must be used for that -purpose. For example: +As an example, here is [odoc]'s configuration file: -{@text[ -{0 My page} -... -]} - -Only one title is allowed per page. The following heading levels should be in -the range from 1 to 5 (inclusive). Don't worry, [odoc] will generate a warning -if you accidentally forget to include multiple titles. - -{2 Usage} +{v +(libraries fmt) +(packages odoc-driver cmdliner odig) +v} -The recommended way to setup documentation pages for your project is by using -the Dune build system. It will automatically find and generate HTML for all -[.mld] files in your project. See -{{:https://dune.readthedocs.io/en/latest/documentation.html#documentation-stanza} -Dune's configuration instructions} for more details. +This file applies to all pages and all modules of all libraries in a package. With this config file, the +modules of the [fmt] library, and the pages of the [odoc-driver], [cmdliner] and [odig] packages can be +linked to via the following syntax: -{2 Referencing Pages} +{v +{!/fmt/module-Fmt} +{!/odoc-driver/page-index} +v} -Currently the generated HTML pages are not be automatically referenced in the -index page. You must manually add links to point to the pages in your document. +Important note: In order for this to work on ocaml.org, it is necessary that the tool used to build the +docs is aware that extra packages are required. If the package is already a dependency, then nothing needs +to be done. If it can be added without introducing dependency cycles, it can be added to the normal +dependencies field. If it would otherwise introduce a cycle into the dependencies, then it must be added +to an extra field. In the case of odoc, because the docs of [odoc] wish to link to the docs of [odoc-driver], +but [odoc-driver] depends on odoc, the following must be added to the [odoc]'s opam file: -For example, if you have a page called [my_page.mld], you can create a -link to it with [{{!page-my_page}My page}] in your [index.mld] or -anywhere else in your documentation. +{v +x-extra-doc-deps: [ + "odoc-driver" {>= "3.0.0"} +] +v} diff --git a/odoc.opam b/odoc.opam index 66485b6395..db12ddc3bb 100644 --- a/odoc.opam +++ b/odoc.opam @@ -62,6 +62,12 @@ depends: [ ("ocaml" {< "4.07.0" & with-test} | "bisect_ppx" {with-test & > "2.5.0"}) ] +x-extra-doc-deps: [ + "odoc-driver" {= version} + "sherlodoc" {= version} + "odig" +] + build: [ ["dune" "subst"] {dev} [ diff --git a/src/driver/bin/odoc_driver_voodoo.ml b/src/driver/bin/odoc_driver_voodoo.ml index 6449484f39..ab1f823c03 100644 --- a/src/driver/bin/odoc_driver_voodoo.ml +++ b/src/driver/bin/odoc_driver_voodoo.ml @@ -30,7 +30,6 @@ let run package_name blessed actions odoc_dir odocl_dir let all = Packages.remap_virtual all in - Logs.debug (fun m -> m "all: %a" Fmt.Dump.(list Packages.pp) all); let partial = match all with | [ p ] -> diff --git a/src/driver/odoc.ml b/src/driver/odoc.ml index 654e96010a..f3783751f8 100644 --- a/src/driver/odoc.ml +++ b/src/driver/odoc.ml @@ -55,11 +55,6 @@ let compile ~output_dir ~input_file:file ~includes ~suppress_warnings ~parent_id in let cmd = cmd % "--parent-id" % Id.to_string parent_id in let cmd = if suppress_warnings then cmd % "--suppress-warnings" else cmd in - let dirname = Id.to_fpath parent_id |> Fpath.filename in - let cmd = - if Fpath.filename file = "index.mld" then cmd % "--short-title" % dirname - else cmd - in let desc = Printf.sprintf "Compiling %s" (Fpath.to_string file) in ignore @@ Cmd_outputs.submit diff --git a/src/html/generator.ml b/src/html/generator.ml index eb497143cc..bda70c0e24 100644 --- a/src/html/generator.ml +++ b/src/html/generator.ml @@ -672,7 +672,7 @@ module Page = struct | Some url -> Some (Link.href ~config ~resolve url) | None -> None in - Html_fragment_json.make ~sidebar ~config + Html_fragment_json.make ~config ~preamble:(items ~config ~resolve preamble :> any Html.elt list) ~breadcrumbs ~toc ~url ~uses_katex ~source_anchor content subpages else diff --git a/src/html/html_fragment_json.ml b/src/html/html_fragment_json.ml index 535f0297ea..3c7d822bb9 100644 --- a/src/html/html_fragment_json.ml +++ b/src/html/html_fragment_json.ml @@ -41,15 +41,14 @@ let json_of_sidebar config sidebar = | None -> `Null | Some sidebar -> `String (json_of_html config sidebar) -let make ~config ~preamble ~url ~breadcrumbs ~sidebar ~toc ~uses_katex - ~source_anchor content children = +let make ~config ~preamble ~url ~breadcrumbs ~toc ~uses_katex ~source_anchor + content children = let filename = Link.Path.as_filename ~config url in let filename = Fpath.add_ext ".json" filename in let json_to_string json = Json.to_string json in let source_anchor = match source_anchor with Some url -> `String url | None -> `Null in - let global_toc = json_of_sidebar config sidebar in let content ppf = Format.pp_print_string ppf (json_to_string @@ -59,7 +58,6 @@ let make ~config ~preamble ~url ~breadcrumbs ~sidebar ~toc ~uses_katex ("uses_katex", `Bool uses_katex); ("breadcrumbs", json_of_breadcrumbs config breadcrumbs); ("toc", json_of_toc toc); - ("global_toc", global_toc); ("source_anchor", source_anchor); ("preamble", `String (json_of_html config preamble)); ("content", `String (json_of_html config content)); diff --git a/src/html/html_fragment_json.mli b/src/html/html_fragment_json.mli index bfedee616b..363f83e838 100644 --- a/src/html/html_fragment_json.mli +++ b/src/html/html_fragment_json.mli @@ -5,7 +5,6 @@ val make : preamble:Html_types.div_content Html.elt list -> url:Odoc_document.Url.Path.t -> breadcrumbs:Types.breadcrumbs -> - sidebar:Html_types.div_content Html.elt list option -> toc:Types.toc list -> uses_katex:bool -> source_anchor:string option -> diff --git a/test/integration/html_opts.t/run.t b/test/integration/html_opts.t/run.t index 84828c716b..7be8ef7926 100644 --- a/test/integration/html_opts.t/run.t +++ b/test/integration/html_opts.t/run.t @@ -22,7 +22,7 @@ Generate --as-json embeddable HTML fragment output: $ odoc html-generate test.odocl -o html --as-json --indent $ cat html/test/Test/index.html.json - {"type":"documentation","uses_katex":false,"breadcrumbs":[{"name":"🏠","href":"../../index.html","kind":"leaf-page"},{"name":"test","href":"../index.html","kind":"page"},{"name":"Test","href":"#","kind":"module"}],"toc":[{"title":"Section 1","href":"#section-1","children":[]},{"title":"Section 2","href":"#section-2","children":[]}],"global_toc":null,"source_anchor":null,"preamble":"

Test

","content":"

Section 1

\u000A
\u000A \u000A type t\u000A
\u000A

Section 2

\u000A
\u000A \u000A type u\u000A
\u000A
"} + {"type":"documentation","uses_katex":false,"breadcrumbs":[{"name":"🏠","href":"../../index.html","kind":"leaf-page"},{"name":"test","href":"../index.html","kind":"page"},{"name":"Test","href":"#","kind":"module"}],"toc":[{"title":"Section 1","href":"#section-1","children":[]},{"title":"Section 2","href":"#section-2","children":[]}],"source_anchor":null,"preamble":"

Test

","content":"

Section 1

\u000A
\u000A \u000A type t\u000A
\u000A

Section 2

\u000A
\u000A \u000A type u\u000A
\u000A
"} $ odoc html-targets test.odocl -o html --as-json --indent html/test/Test/index.html.json diff --git a/test/integration/json_expansion.t/run.t b/test/integration/json_expansion.t/run.t index f27e6867b0..3d554b7d62 100644 --- a/test/integration/json_expansion.t/run.t +++ b/test/integration/json_expansion.t/run.t @@ -18,10 +18,10 @@ Test the JSON output in the presence of expanded modules. $ odoc html-generate --as-json -o html main.odocl $ cat html/Main/index.html.json - {"type":"documentation","uses_katex":false,"breadcrumbs":[{"name":"🏠","href":"../index.html","kind":"leaf-page"},{"name":"Main","href":"#","kind":"module"}],"toc":[],"global_toc":null,"source_anchor":null,"preamble":"","content":"
module A : sig ... end
"} + {"type":"documentation","uses_katex":false,"breadcrumbs":[{"name":"🏠","href":"../index.html","kind":"leaf-page"},{"name":"Main","href":"#","kind":"module"}],"toc":[],"source_anchor":null,"preamble":"","content":"
module A : sig ... end
"} $ cat html/Main/A/index.html.json - {"type":"documentation","uses_katex":false,"breadcrumbs":[{"name":"🏠","href":"../../index.html","kind":"leaf-page"},{"name":"Main","href":"../index.html","kind":"module"},{"name":"A","href":"#","kind":"module"}],"toc":[],"global_toc":null,"source_anchor":null,"preamble":"","content":"
module B : sig ... end
"} + {"type":"documentation","uses_katex":false,"breadcrumbs":[{"name":"🏠","href":"../../index.html","kind":"leaf-page"},{"name":"Main","href":"../index.html","kind":"module"},{"name":"A","href":"#","kind":"module"}],"toc":[],"source_anchor":null,"preamble":"","content":"
module B : sig ... end
"} $ cat html/Main/A/B/index.html.json - {"type":"documentation","uses_katex":false,"breadcrumbs":[{"name":"🏠","href":"../../../index.html","kind":"leaf-page"},{"name":"Main","href":"../../index.html","kind":"module"},{"name":"A","href":"../index.html","kind":"module"},{"name":"B","href":"#","kind":"module"}],"toc":[],"global_toc":null,"source_anchor":null,"preamble":"","content":""} + {"type":"documentation","uses_katex":false,"breadcrumbs":[{"name":"🏠","href":"../../../index.html","kind":"leaf-page"},{"name":"Main","href":"../../index.html","kind":"module"},{"name":"A","href":"../index.html","kind":"module"},{"name":"B","href":"#","kind":"module"}],"toc":[],"source_anchor":null,"preamble":"","content":""} diff --git a/test/integration/json_expansion_with_sources.t/run.t b/test/integration/json_expansion_with_sources.t/run.t index 317f5dd63c..1f57f5887b 100644 --- a/test/integration/json_expansion_with_sources.t/run.t +++ b/test/integration/json_expansion_with_sources.t/run.t @@ -38,13 +38,13 @@ Test the JSON output in the presence of expanded modules. $ odoc html-generate --as-json -o html main.odocl $ cat html/Main/index.html.json - {"type":"documentation","uses_katex":false,"breadcrumbs":[{"name":"🏠","href":"../index.html","kind":"leaf-page"},{"name":"Main","href":"#","kind":"module"}],"toc":[],"global_toc":null,"source_anchor":"../src/main.ml.html","preamble":"","content":"
Sourcemodule A : sig ... end
"} + {"type":"documentation","uses_katex":false,"breadcrumbs":[{"name":"🏠","href":"../index.html","kind":"leaf-page"},{"name":"Main","href":"#","kind":"module"}],"toc":[],"source_anchor":"../src/main.ml.html","preamble":"","content":"
Sourcemodule A : sig ... end
"} $ cat html/Main/A/index.html.json - {"type":"documentation","uses_katex":false,"breadcrumbs":[{"name":"🏠","href":"../../index.html","kind":"leaf-page"},{"name":"Main","href":"../index.html","kind":"module"},{"name":"A","href":"#","kind":"module"}],"toc":[],"global_toc":null,"source_anchor":"../../src/a.ml.html","preamble":"","content":"
Sourcemodule B : sig ... end
"} + {"type":"documentation","uses_katex":false,"breadcrumbs":[{"name":"🏠","href":"../../index.html","kind":"leaf-page"},{"name":"Main","href":"../index.html","kind":"module"},{"name":"A","href":"#","kind":"module"}],"toc":[],"source_anchor":"../../src/a.ml.html","preamble":"","content":"
Sourcemodule B : sig ... end
"} $ cat html/Main/A/B/index.html.json - {"type":"documentation","uses_katex":false,"breadcrumbs":[{"name":"🏠","href":"../../../index.html","kind":"leaf-page"},{"name":"Main","href":"../../index.html","kind":"module"},{"name":"A","href":"../index.html","kind":"module"},{"name":"B","href":"#","kind":"module"}],"toc":[],"global_toc":null,"source_anchor":"../../../src/a.ml.html#module-B","preamble":"","content":""} + {"type":"documentation","uses_katex":false,"breadcrumbs":[{"name":"🏠","href":"../../../index.html","kind":"leaf-page"},{"name":"Main","href":"../../index.html","kind":"module"},{"name":"A","href":"../index.html","kind":"module"},{"name":"B","href":"#","kind":"module"}],"toc":[],"source_anchor":"../../../src/a.ml.html#module-B","preamble":"","content":""} $ cat html/src/a.ml.html.json {"type":"source","breadcrumbs":[{"name":"🏠","href":"../index.html","kind":"leaf-page"},{"name":"src","href":"index.html","kind":"page"},{"name":"a.ml","href":"#","kind":"source"}],"global_toc":null,"content":"
1\u000Amodule B = struct end\u000A
"}