Odoc 3 announcement

# Odoc 3 announcement to discuss On behalf of the odoc team, I'm thrilled the announce the release of odoc 3.0.0 beta 1. This release has been cooking for a long time - it's been more than a year since odoc 2.4 landed, and a huge amount of work has gone into this. Thanks to the many others who contributed, either by code or by comments: @juloo, @panglesd, @EmileTrotignon, @gpetiot, @trefis, @sabine, @dbuenzli, @yawaramin, and more. With this release we're including a driver that knows how to use all of the exciting new features of odoc. This driver has been used to create the [docs site for the various odoc tools](https://ocaml.github.io/odoc/). Here are a selected set of features: - :droplet: Rendered source! Jump from any item in the documentation straight to its rendered source; no matter how much of OCaml's complex module system you are using. - :mag: Search by type! Our detective sherlodoc will find your lost value given its type. - :warning: Convenient warnings! Warnings are now clearly visible and useful, no longer buried among your dependencies’ warnings. - :arrow_heading_up: Self host your documentation, but [link to ocaml.org](https://ocaml.github.io/odoc/odoc-driver/#remapping-dependencies) for your dependencies. - :100: More sidebars! Odoc 3 features a [global sidebar](https://ocaml.github.io/odoc/odoc/odoc_for_authors.html#page-tags), allowing you to discover the most hidden corner of underground documentation. - :exploding_head: Image support! This cutting-edge feature now allows you to [add images](https://ocaml.github.io/odoc/odoc/odoc_for_authors.html#media) to your documentation. Video and audio come for free. - :spider_web: [Fully cross-package links](https://ocaml.github.io/odoc/odoc/odoc_for_authors.html#links_and_references)! The OCaml docs are now a true spider web. Prepare to catch bugs, and eat them. - :cop: Hierarchical documentation pages! We use a modular language. We don't want a flat namespace for pages. - :building_construction: The build dependencies are friendlier with incremental build systems, allowing better shared build caches. - :heart: Quality of life improvements! Many improvements have been piling up since we started odoc 3. For instance: `Add clock emoji before @since tag (@yawaramin, #1089)`! More explanation of these features is available at the odoc site, where we have documentation [for authors](https://ocaml.github.io/odoc/odoc/odoc_for_authors.html), for [users of `odoc_driver`](https://ocaml.github.io/odoc/odoc-driver/index.html), a [cheatsheet](https://ocaml.github.io/odoc/odoc/cheatsheet.html), and [differences from ocamldoc](https://ocaml.github.io/odoc/odoc/ocamldoc_differences.html). ## How can you help? We need your feedback, both as authors and as users of documentation! Try things out using the new driver: ```shell $ opam install odoc-driver # don't forget to `opam update` $ odoc_driver <package list> # For instance: `$ odoc_driver brr odoc` $ $YOUR_BROWSER _html/index.html ``` Many of those features' implementations are not set in stone, but first versions. Please leave comments, either in this thread or as issues in the repository. So, navigate already written documentation, and update your own docs to use the new features! --- Documentation links: - Hierarchical pages: missing? - Sidebar ordering: https://ocaml.github.io/odoc/odoc/odoc_for_authors.html#page-tags - Image support: https://ocaml.github.io/odoc/odoc/odoc_for_authors.html#media and unfortunately no `(install ...)` example link - Cross package links: - for config file: syntax https://ocaml.github.io/odoc/odoc/odoc_for_authors.html#config-file and for install https://ocaml.github.io/odoc/odoc/odoc_for_authors.html#quickstart - For reference syntax: https://ocaml.github.io/odoc/odoc/odoc_for_authors.html#links_and_references - `--remap`: https://ocaml.github.io/odoc/odoc-driver/index.html#remapping-dependencies --- The odoc team is releasing a beta version of its third major version! It took a lot of time and work, but we are finally close. Last "minor" release was more than one year ago, so it's a relief to finally bring all contributions to the public! Thanks to the many who contributed, either by code or by comments: @jonludlam, @juloo, @panglesd, @EmileTrotignon, @gpetiot, @trefis, @sabine, @dbuenzli, @yawaramin, ... This release contains a lot of new features, but many need special support from the driver: for instance, they require special CLI flags. As a consequence, the usual drivers for odoc (`odig`, `dune`, the `voodoo` driver for ocaml.org) won't enable them out of the box. The good news is that `odoc` 3 is still compatible with those drivers. To keep a driver in sync with the addition of new features, the `odoc` team now maintains its own (experimental) driver, in the same repository. You can use it to test the new features! ```shell $ opam install odoc-driver # don't forget to `opam update` $ odoc_driver <package list> # For instance: `$ odoc_driver brr odoc` $ $YOUR_BROWSER _html/index.html ``` Note well that however, this driver is meant to be used to test odoc. It is not a replacement for `dune` or `odig`, which will hopefully be extended to support odoc 3. Here are a selected set of features, with more explanation below: - :100: More sidebars! Odoc 3 features a global sidebar, allowing you to discover the most hidden corner of underground documentation. - :exploding_head: Image support! This cutting-edge feature allows you to add images to your documentation - no less. Video and audio come for free. - :droplet: Rendered source! Jump from any item in the documentation straight to its rendered source; no matter how much of OCaml's complex module system you are using. - :spider_web: Cross package links! The OCaml docs are now a true spider web. Prepare to catch bugs, and eat them. - :cop: Hierarchical documentation! We use a modular language. We don't want a flat namespace for pages. - :warning: Convenient warnings! Warnings are now clearly visible and useful, no longer buried among your dependencies’ warnings. - :mag: Search by type! Our detective sherlodoc will find your lost value given its type. - :building_construction: The build dependencies are friendlier with incremental build systems, allowing better shared build caches. - :heart: Quality of life improvements! Many improvements have been piling up since we started odoc 3. For instance: `Add clock emoji before @since tag (@yawaramin, #1089)`! - :arrow_heading_up: Self host your documentation, but link to ocaml.org for your dependencies. - :package: Odoc gives its driver better support for separating modules by library, fixing previously ambiguous links. We need your feedback, as users and authors of documentation! While we hope the CLI won't change anymore, many of those features' implementation are not set in stone, but first versions. So, leave comments, either in this thread or as issues in the repository. So, navigate already written documentation, and update them to use the new features! <details> <summary>More details on the points above.</summary> Some things come for free (eg, rendered source), some others need support from you (eg, ordering the sidebar). I detail below the how you can use some of the new features! ### Hierarchical documentation All pages installed in `<opam-root>/doc/odoc-pages/` will be picked by the driver, will be placed in the hierarchy with respect to the subfolder they are in. So the `<opam-root>/doc/odoc-pages/usecases/web.mld` will be rendered in a `usecase` folder. However, dune install mld pages flatly. You need to use an install stanza: ``` (install (section doc) (files (web.mld as odoc-pages/usecases/web.mld))) ``` Check out an [example](https://github.com/ocaml/odoc/blob/master/doc/deprecated/dune) of this on odoc's doc! ### Ordering the sidebar The ordering the pages in the sidebar is done through a tag to put at the beginning of your `index.mld` page: ``` @children_order intro quick_start hard_stuff ``` For an example see how `odoc` [uses it](https://github.com/ocaml/odoc/blob/master/doc/odoc.mld#L1)! ### Image support To include an image in your doc, you need to install it in the right opam directory first. In `dune`: ``` (install (section doc) (files (logo.png as odoc-pages/logo.png))) ``` Then, in an mld file, use the `{image!...}` reference: ``` {i Finally}, image support! {image!logo.png} ``` Check out an example of this in `odoc`'s [dune file](https://github.com/ocaml/odoc/blob/master/doc/dune#L51) and [documentation](https://github.com/ocaml/odoc/blob/master/doc/cheatsheet.mld#L176)! ### Cross package linking If you want to reference a page from one package to another, use the `{!/pkgname/pagename}` syntax: ``` See {!/brr/ffi_manual} for how these bindings were designed. ``` You can reference any other package or library, even if they depend on you, without circular dependency! However, you need to declare which library/package you want to include, in a config file named `odoc-config.sexp`: ``` (libraries ...) (packages ...) ``` that you need to install ``` (install (files odoc-config.sexp) (section doc)) ``` Check out `odoc`'s [config file](https://github.com/ocaml/odoc/blob/master/doc/odoc-config.sexp), [how it's installed](https://github.com/ocaml/odoc/blob/master/doc/odoc-config.sexp) and the [cross references](https://github.com/ocaml/odoc/blob/master/doc/cheatsheet.mld#L81) in the cheatsheet! (Note that you'll need to explicitly mention that you need the docs that you are referencing: `odoc_driver -p yourpackage -p brr`. This caveat will soon be fixed.) ### Convenient warnings Whenever you build your docs for a specific package, the dependencies' warnings won't be shown to you. So in: ``` odoc_driver opam yourpackage ``` all warnings shown to you should be actionable, go fix them! ### Host your package documentation If you want to host your package documentation, simply use the `--remap` argument! The driver will still build all doc in order to check that links are valid, but it will only generate the html files for the selected packages, not the dependencies. Links to the dependencies will be redirected to ocaml.org. </details> ### How you can help! We need feedback! The best way to help is to try out `odoc_driver` on some packages and let us know if there's anything that looks wrong or broken or just could be improved. ### Next steps We are aware of a few bugs, that are not blockers but that we need to fix. - Rendered source have limitation (source needs to be installed which is not always the case, works on preprocessed source, ...) https://github.com/ocaml/odoc/issues/1289 https://github.com/ocaml/odoc/issues/1288 - Sometimes rendered source features do not work well, in particular jump to def (see https://github.com/ocaml/odoc/issues/1287) - Dependency warnings may slip through (TODO: needs example to open issue) - Image's size cannot be defined https://github.com/ocaml/odoc/issues/1286 The next step for us is to replace `voodoo` with `odoc_driver` to generate the docs for ocaml.org, making OCaml users benefit from all new features without any action from their part. The next-next step is to rewrite `dune build @doc` rules to replace `odoc_driver`.

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.