[new release] odoc (5 packages) (3.0.0~beta1)

[jonludlam]

CHANGES:

• 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, Asset cli odoc#1170, Parse and resolve asset references odoc#1171, Media in odoc 3! odoc#1184, Add ability to call generate commands on asset units odoc#1185)

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

• 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, Add the ability to remap identifiers during HTML generation odoc#1189, Html remap odoc#1248)

• Option to compute occurrences of use of each identifiers The commands aggregate-occurrences and count-occurrences are added. (@panglesd, Collect occurrences information odoc#976, Add occurrence count in the json output for search engine odoc#1076, Count-occurrences: CLI consistency and driver support odoc#1206)

• Added the odoc classify command (@jonludlam, Driver odoc#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, Add `--suppress-warnings" to avoid inheriting warnings odoc#1260)

• Add clock emoji before @since tag (@yawaramin, Add clock emoji before 'since' tag odoc#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, Search bar navigation odoc#1088)

• Fix a big gap between the preamble and the content of a page (@EmileTrotignon, Remove margin of first child of odoc-content odoc#1147)

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

• Allow referencing of polymorphic constructors in polymorphic variant type aliases (@panglesd, Allow reference to polymorphic variants when possible odoc#1115)

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

• Add a frontmatter syntax for mld pages (@panglesd, Add a frontmatter to mld pages odoc#1187, Specify children order in frontmatter odoc#1193, Use a tag to declare the order of children odoc#1243, Use a tag to define short titles odoc#1246, Uniform treatment of sidebar odoc#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, Standalone markdown support odoc#1234)

• 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, Implicitly ended tags. odoc#1239) A @tag can now be followed by a paragraph or other elements.

• Updated colors for code fragments (@EmileTrotignon, change color to gruvbox theme odoc#1023)

• Fixed complexity of looking up .odoc files (@panglesd, Find odoc files in accessible path more efficiently odoc#1075)

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

• Reduce size of Odoc_html_frontend when compiled to javascript (@EmileTrotignon, Remove tyxml from odoc_html_frontend odoc#1072)

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

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

• Fix variant constructors being hidden if they contain hidden types (@jonludlam, Treat hidden representations differently odoc#1105)

• Fix rare assertion failure due to optional parameters (@jonludlam, Fix #1001 odoc#1272, issue Assertion failed on mutual recursion with optional arguments odoc#1001)

• Fix resolution of module synopses in {!modules} lists that require --open (@jonludlam, Fix an issue when resolving synopses in {!modules } odoc#1104}

• Fix top comment not being taken from includes often enough (@panglesd, Import top comment from top include of a hidden module odoc#1117)

• Fixed 404 links from search results (@panglesd, Fix href for aliased modules in search results odoc#1108)

• Fixed title content not being picked up across pages when rendering references (Use heading text for references to heading even across pages odoc#1116, @panglesd)

• Fix wrong links to standalone comments in search results (Fix wrong id being given to doc comments odoc#1118, @panglesd)

• Remove duplicated or unwanted comments with inline includes (@Julow, Remove unwanted or duplicate doc in expansions odoc#1133)

• Fix bug where source rendering would cause odoc to fail completely if it encounters invalid syntax (@jonludlam Docs CI compatibility odoc#1208)

• Add missing parentheses in 'val (let*) : ...' (@Julow, Add missing parentheses around identifier 'let*'  odoc#1268)

• Fix syntax highlighting not working for very large files (@jonludlam, @Julow, Fix stack overflow when highlighting large source files odoc#1277)