We are pleased to announce release 1.4.0 of odoc, the new, Dune-friendly documentation generator for OCaml and ReasonML.
You can install odoc and generate docs for your Dune project with:
opam update
opam install odoc
dune build @doc
Then, view the docs by opening _build/default/_doc/_html/index.html
!
While release 1.4.0 has new features, it is mainly focused on stability and maintainability. See its full changelog here. The previous release, 1.3.0 last October, included a lot of new code. Because of concerns about its stability, we chose not to widely announce 1.3.0. So, this message serves as an announcement for both releases :) The full changelog for 1.3.0 can be found here.
In summary, compared with 1.2.0, odoc
now has:
- New appearance.
- Tables of contents on each page.
- Generation of docs in ReasonML syntax.
- Interop with BuckleScript.
- Parallel packaging for NPM and esy.
- New, error-recovering comment parser with helpful error messages.
- Many bugfixes.
- Compatibility with OCaml 4.08 (at least, the current beta releases).
- Much more streamlined development process, cleaner code, more tests and CI, etc.
For now, we plan to continue improving the stability of odoc and the quality of its output. In the longer term, odoc has two significant goals:
-
To replace ocamldoc as OCaml's primary documentation generator. At the core of odoc is a powerful cross-referencer, capable of fully handling the complexity of OCaml's module system. Shortcomings in ocamldoc's ability to resolve cross-references in complex projects were one of the original motivations for starting odoc.
-
To create centrally-hosted, cross-referenced, searchable online documentation for all the published packages in opam, a “
docs.ocaml.org
.”
Thanks to the odoc users and contributors, and happy documenting!
See full changelog
Changes
- All parsing errors are now recoverable warnings (#238).
- Page titles are now level-0 headings (
{0 ...}
), and top-level sections within a page are level-1 headings ({1 ...}
) (#217, Rizo Isrof). - Don't render definitions of externals (#275, Nik Graf).
- Disable programming ligatures (#248).
- Rename
--root-uri
option to--xref-base-uri
(#223, Rizo Isrof). - Deprecate redundant reference kind annotations (#246).
Additions
- Preliminary compatibility with the current 4.08 beta releases (#309, Jon Ludlam).
- Paragraph headings (
{4 ...}
) and subparagraph headings ({5 ...}
) (#217, Rizo Isrof). odoc support-files-targets
command (#232).- Recommend
bsdoc
for usingodoc
with BuckleScript (#269, Leandro Ostera).
Bugs fixed
- Improve breadcrumbs on
.mld
pages (#293, Daniel Buenzli). - Display tables of contents in nested module and class pages (#261, Rizo Isrof).
- Uncaught exception when parsing references to operators with
-
in them, such as@->
(#178). - Incorrect parsing of references to operators with
.
in them, such as*.
(#237). - Assertion failure when processing optional arguments in an
.ml
file with a type annotation, when that type annotation uses an alias of'a option
(#101). - Assertion failure when two modules with the same name are found by odoc (#148, Jon Ludlam).
- Verbatim blocks (
{v ... v}
) can now only be terminated if thev}
is immediately preceded by whitespace (#71, reported Daniel Buenzli). - Wrong column numbers for errors reported in comments (#227, #253).
- Restore parsing of ocamldoc-style reference kind annotations (#244).
- Ordinary
type
keyword instead ofand
rendered in HTML for mutually-recursive types (#105, reported @Fourchaux). nonrec
keyword not rendered (#249).and
not rendered for mutually-recursive modules, classes, and class types (#251).- Outer comment attached to a module rendered when the module is included (#87, Jon Ludlam).
- Polymorphic variant constructor documentation not rendered (#176, reported @steinuil).
- Variant constructor and record field documentation styled differently (#260, Jon Ludlam).
- Sloppy keyword markup in HTML output (#319).
- Rendering of multiple
constraint
clauses (#321). - Incorrect order of functor arguments (#261, Rizo Isrof).
odoc html
option-o
now creates the output directory if it does not exist #171, #264 Rizo Isrof).odoc html-targets
output now includes path prefix given through-o
option (#173, Rizo Isrof).- Allow
-I
and-o
options to refer to non-existent directories (#32, #170, Daniel Buenzli). - Make
odoc compile-targets
matchodoc compile
(#273, Daniel Buenzli). odoc compile-deps
does not work on.cmt
files (#162, Daniel Buenzli).odoc html-deps
now scans for.odoc
files recursively (#307, Daniel Buenzli).odoc html-targets
ignores stop comments (#276, Daniel Buenzli).odoc html-targets
andodoc html-deps
segfault on.mld
pages (#277, #282, Daneil Buenzli).--theme-uri
option not propagated to some subpages (#318, Thomas Refis).- Binary files not opened in binary mode (#281, Ulrik Strid).
Build and development
- Always print backtraces for unhandled exceptions (3d10feb).
- CI on macOS (#216, Leandro Ostera).
- Test runner improvements (#266, Rizo Isrof).
- Fix esy builds in Travis (#301, Jon Ludlam).
- Don't require
make
in the esy build (#308, Leandro Ostera). - Get rid of some large GADTs (#292, Jon Ludlam).
- Remove dependency on
bos
(#305, Daniel Buenzli). - Remove dependency on
rresult
(#306, Daniel Buenzli). - Remove dependency on
bisect_ppx
, previously present in development checkouts (#316).