+6

doc/deprecated/dune

··· 1 1 + (install 2 2 + (section doc) 3 3 + (files 4 4 + (parent_child_spec.mld as odoc-pages/deprecated/parent_child_spec.mld) 5 5 + (index.mld as odoc-pages/deprecated/index.mld)) 6 6 + (package odoc))

+4

doc/deprecated/index.mld

··· 1 1 + {0 Deprecated features} 2 2 + 3 3 + Odoc 2.x had a different way to specify the hierarchy of the output pages. This still works, 4 4 + though it is deprecated. Documentation for the feature may be found {{!page-parent_child_spec}here}.

+5 -5

doc/driver.mld

··· 7 7 For this reason, just like for building any multifiles OCaml project, [odoc] 8 8 needs to be driven by a higher level tool. The driver will take care of calling 9 9 the [odoc] command with the right arguments throughout the different 10 10 - phases. Several drivers for [odoc] exist, such as: 11 11 - {{:https://dune.readthedocs.io/en/stable/documentation.html}dune} and 12 12 - {{:https://erratique.ch/software/odig}odig}. 10 10 + phases. The {{!/odoc-driver/page-index}odoc-driver} package contains a "reference driver", that is kept up-to-date 11 11 + with the latest development of [odoc], 13 12 14 14 - The [odoc] tool also contains a "reference driver", that is kept up-to-date 15 15 - with the latest development of [odoc]. 13 13 + Several drivers for [odoc] exist, such as: 14 14 + {{:https://dune.readthedocs.io/en/stable/documentation.html}dune} and 15 15 + {{!/odig/page-index}odig}. 16 16 17 17 This document explains how to drive [odoc], as of version 3. It is not needed to 18 18 know any of this to {e use} [odoc], it is targeted at driver authors, tools that

+7

doc/driver/dune

··· 1 1 (documentation 2 2 (package odoc-driver)) 3 3 + 4 4 + (install 5 5 + (section doc) 6 6 + (files 7 7 + odoc-config.sexp) 8 8 + (package odoc-driver)) 9 9 +

+3 -3

doc/driver/index.mld

··· 24 24 25 25 [odoc_driver] is actually three drivers: 26 26 27 27 - 1. [odoc_driver] - The standard driver. 28 28 - 2. [odoc_driver_voodoo] - The driver adapted for producing the documentation used by ocaml.org. 29 29 - 3. [odoc_driver_monorepo] - An experimental driver for producing documentation of a dune-managed monorepo. 27 27 + - [odoc_driver] - The standard driver. 28 28 + - [odoc_driver_voodoo] - The driver adapted for producing the documentation used by ocaml.org. 29 29 + - [odoc_driver_monorepo] - An experimental driver for producing documentation of a dune-managed monorepo. 30 30 31 31 What follows applies mostly to the first of these. 32 32

+1 -2

doc/dune

··· 9 9 ocamldoc_differences 10 10 odoc_for_authors 11 11 cheatsheet 12 12 - json 13 13 - parent_child_spec)) 12 12 + json)) 14 13 15 14 ; Uncomment to run mdx on the documentation's code blocks. 16 15 ; (mdx

+1 -1

doc/odoc-config.sexp

··· 1 1 (libraries fmt) 2 2 - (packages cmdliner) 2 2 + (packages odoc-driver cmdliner odig sherlodoc)

+4 -16

doc/odoc.mld

··· 1 1 - @children_order dune odoc_for_authors cheatsheet features ocamldoc_differences interface parent_child_spec driver json 2 2 - @short_title [odoc] 1 1 + @children_order odoc_for_authors cheatsheet dune features ocamldoc_differences interface driver json deprecated/ 2 2 + @short_title The odoc documentation generator 3 3 4 4 {0 The [odoc] documentation generator} 5 5 ··· 41 41 - an {e expander}, which can expand complex module-type expressions while preserving their structure, including comment, includes, and 42 42 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! 43 43 44 44 - {1 For Library Authors} 44 44 + {1 For Authors} 45 45 46 46 - For guidance on how to document your OCaml project, see {{!page-odoc_for_authors}[odoc] for authors}. 46 46 + For guidance on how to document your OCaml project, see {!page-odoc_for_authors}. 47 47 48 48 {1 For Integrators} 49 49 50 50 To integrate [odoc] into your tool, webpage or any other 51 51 setting, you'll need to understand {{!page-driver}how to drive [odoc]}. 52 52 - 53 53 - {1 Page Index} 54 54 - 55 55 - The main other pages of this site: 56 56 - - {!page-odoc_for_authors} gives information for [odoc] authors. 57 57 - - {!page-cheatsheet} provides a quick quide for [odoc] markdown. 58 58 - - {!page-features} explores [odoc]'s language features. 59 59 - - {!page-driver} describes how [odoc] produces documentation. 60 60 - - {!page-ocamldoc_differences} outlines differences from OCamldoc. 61 61 - - {!page-dune} shows how to create docs using Dune. 62 62 - - {!page-parent_child_spec} delineates parent/child specifications. 63 63 - - {!page-interface} describes [odoc]'s public-facing interface and their support guarantees.

+112 -51

doc/odoc_for_authors.mld

··· 15 15 'drivers' of [odoc] at time of writing, each with their own strengths and 16 16 weaknesses: 17 17 18 18 + - {{!/odoc-driver/page-index}The reference driver} is the most up-to-date driver, 19 19 + and incorporates all of the features of odoc. It is also used for the docs 20 20 + published on ocaml.org. It does not feature fast rebuilds, nor keeping a 21 21 + switch-wide cache of documentation. Install the package to document via 22 22 + [opam] and run 23 23 + {v 24 24 + $ odoc_driver <pkg> 25 25 + v} 26 26 + to build the docs. The output will appear in the directory `_html` by default. 18 27 - {{:https://dune.build/}Dune} is the best way to view docs while 19 28 developing your project. We have a {{!page-dune}page} describing 20 29 how to use it, but the short version is: ··· 27 36 {v 28 37 $ odig doc odig 29 38 v} 30 30 - - {{!page-driver}The reference driver} is the simplest driver, useful if you 31 31 - want to see how to integrate it with your own projects. 32 32 - - {{:https://github.com/ocaml-doc/voodoo}Voodoo} is the driver used to create 33 33 - the docs for {{:https://ocaml.org/packages}the OCaml website}. 39 39 + 40 40 + {1:packagedocs Documenting a package} 41 41 + 42 42 + Documentation in OCaml is grouped together by {i package}. Each package may contain 43 43 + a number of documentation pages, organised into a hierarchy, and if the 44 44 + package contains {i libraries}, their interfaces form the rest of the package documentation. 45 45 + The pages are written in a subset of the usual {{!page-ocamldoc_differences}odoc markup}, 46 46 + and the libraries are documented via in-line special comments in the source. 47 47 + Conceptually, the docs for every library are {i contained within} the docs of its package. 48 48 + 49 49 + {2 Quickstart} 50 50 + 51 51 + When a package is built with [dune], the simplest way to include docs in your package is 52 52 + to create a [doc] dir, write [doc/index.mld] file containing the documentation for your 53 53 + package: 54 54 + 55 55 + {v 56 56 + {0 My package documentation} 57 57 + 58 58 + This is the documentation for my package! 59 59 + v} 60 60 + 61 61 + then create the following [doc/dune] file: 62 62 + 63 63 + {v 64 64 + (documentation) 65 65 + v} 66 66 + 67 67 + More mld files can be added as necessary to the [doc] directory, and they will be included 68 68 + also. 69 69 + 70 70 + This will work if you've only got one package defined in your dune project. If you've got 71 71 + more than one, you'll need to let dune know which package the docs are associated with: 72 72 + 73 73 + {v 74 74 + (documentation 75 75 + (package my_package)) 76 76 + v} 77 77 + 78 78 + Any assets you have will also need to be handled, and as this is a new feature in odoc 3, 79 79 + at time of writing dune does not have a convenient syntax for this. However, it still can 80 80 + be done, so if, for example, you have an image [asset.jpg] that you'd like to include in your 81 81 + doc, you can add the following to your [doc/dune] file: 82 82 + 83 83 + {v 84 84 + (install 85 85 + (section doc) 86 86 + (files (asset.jpg as odoc-pages/asset.jpg))) 87 87 + v} 88 88 + 89 89 + Odoc 3.0 introduces a per-package configuration file, {{!section-config-file}odoc-config.sexp}, which is important if you'd like your 90 90 + documentation to link to the docs of other packages or libraries. If your documentation needs 91 91 + this configuration file, this will also need to be installed as follows: 92 92 + 93 93 + {v 94 94 + (install 95 95 + (section doc) 96 96 + (files odoc-config.sexp)) 97 97 + v} 34 98 35 99 {1:interfaces Documenting Your Interfaces} 36 100 37 37 - [odoc] is built to produce documentation for your {e libraries}, and the unit of 38 38 - organisation is the {e module}. Documentation is written by putting 101 101 + As well as doc pages, [odoc] is built to produce documentation for your {e libraries}, 102 102 + and the unit of organisation for these is the {e module}. Documentation is written by putting 39 103 {{!special_comments}special comments} into the source of the {e module interface} or, 40 104 less commonly, your {e module implementation}. 41 105 ··· 399 463 - [odoc]: [ {!module-Foo.type-bar} ] - each element in the path may be prefixed by its type. This is 400 464 useful if there are ambiguous elements in any part of the path, e.g., in this case perhaps there is a 401 465 module type [Foo]. 466 466 + - [odoc3]: [ {!/library_name/Module} ] - this is a path to them module [M] in library [library_name]. 467 467 + This is useful if the module name is ambiguous, e.g., if there are two modules [M] in different libraries. 468 468 + You may need to add the library to the per-package config file. 469 469 + - [odoc3]: [ {!/package/path/to/page-foo} ] - this is a path to a page [foo] in the package [package]. 470 470 + The package will need to be added to the per-package config file. 402 471 403 472 The prefixes supported are: 404 473 - [module] ··· 663 732 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). 664 733 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). 665 734 666 666 - {2:media Medias} 735 735 + {2:media Media} 667 736 668 668 - Odoc 3.0 introduced new markup for medias. Medias are nestable blocks, 737 737 + Odoc 3.0 introduced new markup for media. Media are nestable blocks, 669 738 so they can be put inside lists and tables, but they cannot be 670 739 inlined, for instance in a link. 671 740 672 672 - There are currently three kinds of medias: image, audio, and 741 741 + There are currently three kinds of media: image, audio, and 673 742 video. Each of them can refer to the file either using an asset 674 743 reference, or a direct link. 675 744 ··· 681 750 The markup for videos and audios is similar, replacing [image] by respectively 682 751 [video] and [audio]. 683 752 684 684 - The replacement text is used for backends that do not support medias 753 753 + The replacement text is used for backends that do not support media 685 754 (latex and man), and for when a reference is unresolved. In the case 686 755 of an image, it is also used to generate an alternative text. 687 756 ··· 878 947 complementary notes. An alternative would be to consider splitting into 879 948 multiple files. 880 949 881 881 - Finally, documentation pages should start with a level-0 heading, see 882 882 - {!section-"page-title"}. Level-0 headings should not be used elsewhere. 950 950 + Finally, documentation pages should start with a level-0 heading: 951 951 + 952 952 + {v 953 953 + {0 Title of the page} 954 954 + v}. 955 955 + 956 956 + Level-0 headings should not be used elsewhere. 883 957 884 958 The syntax for declaring sections is as follows: 885 959 ··· 932 1006 See {!page-a.foo} for details 933 1007 v} 934 1008 935 935 - {1:doc-pages Writing Documentation Pages} 1009 1009 + {1:config-file Configuration file} 936 1010 937 937 - Files with the [.mld] extension are called {e documentation pages} and should 938 938 - be used to complement API references with tutorials or guides. They are 939 939 - particularly suitable for OCaml and Reason because cross-references to 940 940 - definitions, both in the current package and for external packages, are 941 941 - supported. 1011 1011 + [odoc] 3.0 introduced a per-package configuration file, [odoc-config.sexp]. This file is required if you 1012 1012 + wish to make use of the cross-package linking feature, or sometimes if you wish to link to other libraries. 942 1013 943 943 - {2 Markup} 1014 1014 + As an example, here is [odoc]'s configuration file: 944 1015 945 945 - The format of these [.mld] files is simply text that should be marked-up with 946 946 - the usual [odoc] markup as described on this page. A documentation page can be seen 947 947 - as a single regular docstring in a separate file. 1016 1016 + {v 1017 1017 + (libraries fmt) 1018 1018 + (packages odoc-driver cmdliner odig) 1019 1019 + v} 948 1020 949 949 - {2 Page Title} 1021 1021 + This file applies to all pages and all modules of all libraries in a package. With this config file, the 1022 1022 + modules of the [fmt] library, and the pages of the [odoc-driver], [cmdliner] and [odig] packages can be 1023 1023 + linked to via the following syntax: 950 1024 951 951 - When defining a documentation page, make sure to supply a page title, as one is 952 952 - not generated by default (unlike for API reference documents where the module 953 953 - or module type name is used). The level-0 heading must be used for that 954 954 - purpose. For example: 1025 1025 + {v 1026 1026 + {!/fmt/module-Fmt} 1027 1027 + {!/odoc-driver/page-index} 1028 1028 + v} 955 1029 956 956 - {@text[ 957 957 - {0 My page} 958 958 - ... 959 959 - ]} 960 960 - 961 961 - Only one title is allowed per page. The following heading levels should be in 962 962 - the range from 1 to 5 (inclusive). Don't worry, [odoc] will generate a warning 963 963 - if you accidentally forget to include multiple titles. 964 964 - 965 965 - {2 Usage} 966 966 - 967 967 - The recommended way to setup documentation pages for your project is by using 968 968 - the Dune build system. It will automatically find and generate HTML for all 969 969 - [.mld] files in your project. See 970 970 - {{:https://dune.readthedocs.io/en/latest/documentation.html#documentation-stanza} 971 971 - Dune's configuration instructions} for more details. 972 972 - 973 973 - {2 Referencing Pages} 974 974 - 975 975 - Currently the generated HTML pages are not be automatically referenced in the 976 976 - index page. You must manually add links to point to the pages in your document. 1030 1030 + Important note: In order for this to work on ocaml.org, it is necessary that the tool used to build the 1031 1031 + docs is aware that extra packages are required. If the package is already a dependency, then nothing needs 1032 1032 + to be done. If it can be added without introducing dependency cycles, it can be added to the normal 1033 1033 + dependencies field. If it would otherwise introduce a cycle into the dependencies, then it must be added 1034 1034 + to an extra field. In the case of odoc, because the docs of [odoc] wish to link to the docs of [odoc-driver], 1035 1035 + but [odoc-driver] depends on odoc, the following must be added to the [odoc]'s opam file: 977 1036 978 978 - For example, if you have a page called [my_page.mld], you can create a 979 979 - link to it with [{{!page-my_page}My page}] in your [index.mld] or 980 980 - anywhere else in your documentation. 1037 1037 + {v 1038 1038 + x-extra-doc-deps: [ 1039 1039 + "odoc-driver" {>= "3.0.0"} 1040 1040 + ] 1041 1041 + v}

doc/parent_child_spec.mld doc/deprecated/parent_child_spec.mld

+6

odoc.opam

··· 62 62 ("ocaml" {< "4.07.0" & with-test} | "bisect_ppx" {with-test & > "2.5.0"}) 63 63 ] 64 64 65 65 + x-extra-doc-deps: [ 66 66 + "odoc-driver" {= version} 67 67 + "sherlodoc" {= version} 68 68 + "odig" 69 69 + ] 70 70 + 65 71 build: [ 66 72 ["dune" "subst"] {dev} 67 73 [

-1

src/driver/bin/odoc_driver_voodoo.ml

··· 30 30 31 31 let all = Packages.remap_virtual all in 32 32 33 33 - Logs.debug (fun m -> m "all: %a" Fmt.Dump.(list Packages.pp) all); 34 33 let partial = 35 34 match all with 36 35 | [ p ] ->