3.0.0~beta1

CHANGES:

Highlight

• Hierarchical documentation (@jonludlam, @panglesd, @Julow)
  Pages can now be organized in a directory tree structure.
  Relative and absolute references are added:
  {!./other_page.label}, {!//other_page}.

• Improved sidebar and breadcrumbs navigation (@panglesd, @gpetiot)
  The documentation pages and the libraries of the entire package are shown on
  the left sidebar.

• Added support for images, videos, audio and other assets
  The syntax is {image!/reference/to/asset} or {image:URL} for images.
  The syntax for {video...} and {audio...} is the same.
  (@panglesd, @EmileTrotignon, #1170, #1171, #1184, #1185)

• Search using Sherlodoc (@panglesd, @EmileTrotignon, @Julow)
  A new search bar that supports full-text and type-based search.

Added

• Experimental driver (@jonludlam, @panglesd)
  The driver builds the documentation for a collection of Opam packages using
  the newer Odoc features. It supports linking external packages to ocaml.org
  and markdown files.
  This is experimental and will break in the future.

• Cross-package references (@panglesd, @Julow)
  Pages and modules from other packages can be referenced:
  {!/otherpackage/page}, {!/otherpackage/Module.t}.

• Option to remap links to other packages to ocaml.org or other site.
  See the --remap option of the driver or the --remap-file option of odoc html-generate.
  (@jonludlam, #1189, #1248)

• Option to compute occurrences of use of each identifiers
  The commands aggregate-occurrences and count-occurrences are added.
  (@panglesd, #976, #1076, #1206)

• Added the odoc classify command (@jonludlam, #1121)
  Helps driver detecting which modules belong to which libraries.

• Added --suppress-warnings to the CLI to remove warnings from a unit, even
  if they end up being raised in another unit through expansion
  (@jonludlam, #1260)

• Add clock emoji before @since tag (@yawaramin, #1089)

• Navigation for the search bar : use '/' to enter search, up and down arrows to
  select a result, and enter to follow the selected link. (@EmileTrotignon, #1088)

• Fix a big gap between the preamble and the content of a page (@EmileTrotignon, #1147)

• Add a marshalled search index consumable by sherlodoc (@EmileTrotignon, @panglesd, #1084)

• Allow referencing of polymorphic constructors in polymorphic variant type
  aliases (@panglesd, #1115)

• Added a home icon in the breacrumbs (@panglesd, #1251)
  It can be disabled with a CLI option.

• Add a frontmatter syntax for mld pages (@panglesd, #1187, #1193, #1243, #1246, #1251)
  Allows to specify the title of a page, the order of sub-pages and other
  behaviors in the sidebar.

• Added odoc-md to process standalone Markdown pages (@jonludlam, #1234)

Changed

• The command line interface changed to support the new features.

  • Packages and libraries: odoc link must now be aware of packages and
    libraries with the -L libname:path and -P pkgname:path options. The
    module search path should still be passed with the -I option.
    The current package should be specified with --current-package=pkgname.
  • Hierarchy: odoc compile now outputs .odoc in the directory tree
    specified with --output-dir=DIR and the parent identifier must be
    specified with --parent-id=PARENT.
    The option --source-parent-file is removed.
  • Source code: Implementations are compiled with compile-impl instead of
    with compile. The options --cmt=.. and --source-name=.. are removed.
    Source code pages are generated with html-generate-source.
  • Assets: The commands compile-asset, html-generate-asset are added.
    The option html-generate --asset is removed.
  • Sidebar: The index is built using compile-index. The sidebar data is
    extracted from the index with sidebar-generate and passed to
    html-generate --sidebar=...

• The syntax for @tag is now delimited (@panglesd, #1239)
  A @tag can now be followed by a paragraph or other elements.

• Updated colors for code fragments (@EmileTrotignon, #1023)

• Fixed complexity of looking up .odoc files (@panglesd, #1075)

• Normalize whitespaces in codespans (@gpetiot, #1085)
  A newline followed by any whitespaces is normalized as one space character.

• Reduce size of Odoc_html_frontend when compiled to javascript
  (@EmileTrotignon, #1072)

• Overhaul of module-type-of expansions and shadowing code (@jonludlam, #1081)

• Output file paths and labels in the man and latex backends changed to avoid
  name clashes (@Julow, #1191)

Fixed

• Fix variant constructors being hidden if they contain hidden types
  (@jonludlam, #1105)
• Fix rare assertion failure due to optional parameters
  (@jonludlam, #1272, issue #1001)
• Fix resolution of module synopses in {!modules} lists that require --open
  (@jonludlam, #1104}
• Fix top comment not being taken from includes often enough (@panglesd, #1117)
• Fixed 404 links from search results (@panglesd, #1108)
• Fixed title content not being picked up across pages when rendering references
  (#1116, @panglesd)
• Fix wrong links to standalone comments in search results (#1118, @panglesd)
• Remove duplicated or unwanted comments with inline includes (@Julow, #1133)
• Fix bug where source rendering would cause odoc to fail completely if it
  encounters invalid syntax (@jonludlam #1208)
• Add missing parentheses in 'val (let*) : ...' (@Julow, #1268)
• Fix syntax highlighting not working for very large files
  (@jonludlam, @Julow, #1277)