Skip to content

Add png, pdf and jpeg image support to the latex backend#1297

Merged
panglesd merged 4 commits intoocaml:masterfrom
Octachron:image_support_for_latex
Feb 18, 2025
Merged

Add png, pdf and jpeg image support to the latex backend#1297
panglesd merged 4 commits intoocaml:masterfrom
Octachron:image_support_for_latex

Conversation

@Octachron
Copy link
Copy Markdown
Member

@Octachron Octachron commented Jan 28, 2025 •
edited
Loading

This small PR adds support for images to the latex backed for png, pdf, and jpeg internal assets.

As a side-note, I am slightly surprised that there is no support for width information on the media tags since both image and video are hard to place properly without fixing their size.

@panglesd
Copy link
Copy Markdown
Collaborator

panglesd commented Jan 29, 2025

Thanks a lot for the PR!

Yes, I agree that it is the first thing we should do for images. (#1286)

The main problem is deciding the syntax. There is no existing syntax for attributes so we have to create something new. I can't find issues with the discussion, it must have happened elsewhere, but we could not find a consensus on the syntax and decided to start without it (in the worst case, images themselves can be resized I think).

I'll restart the discussion in #1286 with some propositions soon.

panglesd
panglesd approved these changes Jan 29, 2025
View reviewed changes
Copy link
Copy Markdown
Collaborator

@panglesd panglesd left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me!

I'm curious about the choice of extensions: shouldn't jpg, and capitalized extensions, be allowed as well?
I suspect the list of supported format depends on the latex implementation.

Maybe the list taken from here could be be a valid choice:

.pdf,.png,.jpg,.mps,.jpeg,.jbig2,.jb2,.PDF,.PNG,.JPG,.JPEG,.JBIG2,.JB2

Also I think it needs ocamlformatting! (maybe we should use this action?)

Comment thread src/latex/generator.ml Outdated
@dbuenzli
Copy link
Copy Markdown
Contributor

dbuenzli commented Jan 29, 2025

both image and video are hard to place properly without fixing their size.

I don't have this in my head but I think this is no longer the case with the CSS object-fit property. If we want to have responsive web pages it's actually better if we avoid people specifying explicit absolute image sizes (it's also brittle if you change the image aspect ratio).

@panglesd
Copy link
Copy Markdown
Collaborator

panglesd commented Jan 29, 2025

I'm not sure to understand! object-fit decides how images are placed in their bounding box.

But if the user can't decide the dimension of the bounding box, it does not help much?

Also, it is hard for odoc to decide on a "good size for all": eg vg has small images, but in other contexts a big image makes sense.

Am I missing something?

@dbuenzli
Copy link
Copy Markdown
Contributor

dbuenzli commented Jan 29, 2025

IIRC for responsive images you basically want users to define one dimension with a relative unit. If it's horizontal it should be a percentage of the measure. If it's vertical a multiple of the leading, capped so that it doesn't overflow the measure. That's for running text but if you have a table for example then your box may already have constraints at which point (again IIRC) object-fit comes handy.

@dbuenzli
Copy link
Copy Markdown
Contributor

dbuenzli commented Jan 29, 2025

Basically user should work with the assumption that the css has:

img, picture, video, canvas, svg { max-width: 100%; display: block }

@Octachron
Copy link
Copy Markdown
Member Author

Octachron commented Jan 29, 2025

I have added support for all image formats supported by pdftex by default.

@panglesd panglesd force-pushed the image_support_for_latex branch from 4d8ef02 to f19cdda Compare February 18, 2025 12:06
panglesd
panglesd approved these changes Feb 18, 2025
View reviewed changes
Copy link
Copy Markdown
Collaborator

@panglesd panglesd left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

I rebased to fix a conflict and put the changelog entry into the "unreleased" section.

Will merge as soon as the CI finishes green.

@panglesd panglesd merged commit b1af426 into ocaml:master Feb 18, 2025
jonludlam added a commit to jonludlam/opam-repository that referenced this pull request Mar 18, 2025
@jonludlam
[new release] odoc (6 packages) (3.0.0)
fc2c447 
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,
  ocaml/odoc#1170, ocaml/odoc#1171, ocaml/odoc#1184, ocaml/odoc#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, ocaml/odoc#1189, ocaml/odoc#1248)

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

- Added an `extract-code` subcommand to extract code blocks from mld/mli files
  (@panglesd, ocaml/odoc#1326)

- Added the `odoc classify` command (@jonludlam, ocaml/odoc#1121)
  Helps driver detecting which modules belong to which libraries.
- Added `--warnings-tag` options to the CLI to silence warnings from a unit,
  even if they end up being raised in another unit through expansion
  (@jonludlam, ocaml/odoc#1260)
- Add clock emoji before `@since` tag (@yawaramin, ocaml/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,
  ocaml/odoc#1088)
- Fix a big gap between the preamble and the content of a page
  (@EmileTrotignon, ocaml/odoc#1147)
- Add a marshalled search index consumable by sherlodoc (@EmileTrotignon,
  @panglesd, ocaml/odoc#1084)
- Allow referencing of polymorphic constructors in polymorphic variant type
  aliases (@panglesd, ocaml/odoc#1115)
- Added a home icon in the breacrumbs (@panglesd, ocaml/odoc#1251)
  It can be disabled with a CLI option.
- Add a frontmatter syntax for mld pages (@panglesd, ocaml/odoc#1187, ocaml/odoc#1193, ocaml/odoc#1243,
  ocaml/odoc#1246, ocaml/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, ocaml/odoc#1234)
- Added CSS selectors to style version and and nav links when they appear
  within page titles, as produced by odig (@katrinafyi, ocaml/odoc#1290)
- Added support for (local) images in the latex backend (@Octachron, ocaml/odoc#1297)

### 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, ocaml/odoc#1239)
  A `@tag` can now be followed by a paragraph or other elements.

- Updated colors for code fragments (@EmileTrotignon, ocaml/odoc#1023)
- Fixed complexity of looking up `.odoc` files (@panglesd, ocaml/odoc#1075)
- Normalize whitespaces in codespans (@gpetiot, ocaml/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, ocaml/odoc#1072)
- Overhaul of module-type-of expansions and shadowing code (@jonludlam, ocaml/odoc#1081)
- Output file paths and labels in the man and latex backends changed to avoid
  name clashes (@Julow, ocaml/odoc#1191)
- Added a `header` field to the json output (@panglesd, ocaml/odoc#1314)
- Changed indentation rules for code block and verbatim content (@panglesd,
  ocaml/odoc#1317)
- odoc-parser: Store raw content in verbatim and code block, and expose a
  function to process it (@panglesd, ocaml/odoc#1325)

### Fixed

- Fix variant constructors being hidden if they contain hidden types
  (@jonludlam, ocaml/odoc#1105)
- Fix rare assertion failure due to optional parameters
  (@jonludlam, ocaml/odoc#1272, issue ocaml/odoc#1001)
- Fix resolution of module synopses in {!modules} lists that require --open
  (@jonludlam, ocaml/odoc#1104}
- Fix top comment not being taken from includes often enough (@panglesd, ocaml/odoc#1117)
- Fixed 404 links from search results (@panglesd, ocaml/odoc#1108)
- Fixed title content not being picked up across pages when rendering references
  (ocaml/odoc#1116, @panglesd)
- Fix wrong links to standalone comments in search results (ocaml/odoc#1118, @panglesd)
- Remove duplicated or unwanted comments with inline includes (@Julow, ocaml/odoc#1133)
- Fix bug where source rendering would cause odoc to fail completely if it
  encounters invalid syntax (@jonludlam ocaml/odoc#1208)
- Add missing parentheses in 'val (let*) : ...' (@Julow, ocaml/odoc#1268)
- Fix syntax highlighting not working for very large files
  (@jonludlam, @Julow, ocaml/odoc#1277)
- Fix backtrace on invalid input in compile-deps (@jonludlam, ocaml/odoc#1313)
- Fix bug in our CSS hitting verbatim blocks in tags (@jonludlam, ocaml/odoc#1312)
- Fix issue ocaml/odoc#610 where `odoc html-fragment` wasn't rendering headings correctly
  (@jonludlam, ocaml/odoc#1306)
jonludlam added a commit to jonludlam/opam-repository that referenced this pull request Mar 18, 2025
@jonludlam
[new release] odoc (6 packages) (3.0.0)
7a7310d 
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,
  ocaml/odoc#1170, ocaml/odoc#1171, ocaml/odoc#1184, ocaml/odoc#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, ocaml/odoc#1189, ocaml/odoc#1248)

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

- Added an `extract-code` subcommand to extract code blocks from mld/mli files
  (@panglesd, ocaml/odoc#1326)

- Added the `odoc classify` command (@jonludlam, ocaml/odoc#1121)
  Helps driver detecting which modules belong to which libraries.
- Added `--warnings-tag` options to the CLI to silence warnings from a unit,
  even if they end up being raised in another unit through expansion
  (@jonludlam, ocaml/odoc#1260)
- Add clock emoji before `@since` tag (@yawaramin, ocaml/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,
  ocaml/odoc#1088)
- Fix a big gap between the preamble and the content of a page
  (@EmileTrotignon, ocaml/odoc#1147)
- Add a marshalled search index consumable by sherlodoc (@EmileTrotignon,
  @panglesd, ocaml/odoc#1084)
- Allow referencing of polymorphic constructors in polymorphic variant type
  aliases (@panglesd, ocaml/odoc#1115)
- Added a home icon in the breacrumbs (@panglesd, ocaml/odoc#1251)
  It can be disabled with a CLI option.
- Add a frontmatter syntax for mld pages (@panglesd, ocaml/odoc#1187, ocaml/odoc#1193, ocaml/odoc#1243,
  ocaml/odoc#1246, ocaml/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, ocaml/odoc#1234)
- Added CSS selectors to style version and and nav links when they appear
  within page titles, as produced by odig (@katrinafyi, ocaml/odoc#1290)
- Added support for (local) images in the latex backend (@Octachron, ocaml/odoc#1297)

### 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, ocaml/odoc#1239)
  A `@tag` can now be followed by a paragraph or other elements.

- Updated colors for code fragments (@EmileTrotignon, ocaml/odoc#1023)
- Fixed complexity of looking up `.odoc` files (@panglesd, ocaml/odoc#1075)
- Normalize whitespaces in codespans (@gpetiot, ocaml/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, ocaml/odoc#1072)
- Overhaul of module-type-of expansions and shadowing code (@jonludlam, ocaml/odoc#1081)
- Output file paths and labels in the man and latex backends changed to avoid
  name clashes (@Julow, ocaml/odoc#1191)
- Added a `header` field to the json output (@panglesd, ocaml/odoc#1314)
- Changed indentation rules for code block and verbatim content (@panglesd,
  ocaml/odoc#1317)
- odoc-parser: Store raw content in verbatim and code block, and expose a
  function to process it (@panglesd, ocaml/odoc#1325)

### Fixed

- Fix variant constructors being hidden if they contain hidden types
  (@jonludlam, ocaml/odoc#1105)
- Fix rare assertion failure due to optional parameters
  (@jonludlam, ocaml/odoc#1272, issue ocaml/odoc#1001)
- Fix resolution of module synopses in {!modules} lists that require --open
  (@jonludlam, ocaml/odoc#1104}
- Fix top comment not being taken from includes often enough (@panglesd, ocaml/odoc#1117)
- Fixed 404 links from search results (@panglesd, ocaml/odoc#1108)
- Fixed title content not being picked up across pages when rendering references
  (ocaml/odoc#1116, @panglesd)
- Fix wrong links to standalone comments in search results (ocaml/odoc#1118, @panglesd)
- Remove duplicated or unwanted comments with inline includes (@Julow, ocaml/odoc#1133)
- Fix bug where source rendering would cause odoc to fail completely if it
  encounters invalid syntax (@jonludlam ocaml/odoc#1208)
- Add missing parentheses in 'val (let*) : ...' (@Julow, ocaml/odoc#1268)
- Fix syntax highlighting not working for very large files
  (@jonludlam, @Julow, ocaml/odoc#1277)
- Fix backtrace on invalid input in compile-deps (@jonludlam, ocaml/odoc#1313)
- Fix bug in our CSS hitting verbatim blocks in tags (@jonludlam, ocaml/odoc#1312)
- Fix issue ocaml/odoc#610 where `odoc html-fragment` wasn't rendering headings correctly
  (@jonludlam, ocaml/odoc#1306)
jonludlam added a commit to jonludlam/opam-repository that referenced this pull request Mar 18, 2025
@jonludlam
[new release] odoc (5 packages) (3.0.0)
6102f15 
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,
  ocaml/odoc#1170, ocaml/odoc#1171, ocaml/odoc#1184, ocaml/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, ocaml/odoc#1189, ocaml/odoc#1248)

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

- Added an `extract-code` subcommand to extract code blocks from mld/mli files
  (@panglesd, ocaml/odoc#1326)

- Added the `odoc classify` command (@jonludlam, ocaml/odoc#1121)
  Helps driver detecting which modules belong to which libraries.
- Added `--warnings-tag` options to the CLI to silence warnings from a unit,
  even if they end up being raised in another unit through expansion
  (@jonludlam, ocaml/odoc#1260)
- Add clock emoji before `@since` tag (@yawaramin, ocaml/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,
  ocaml/odoc#1088)
- Fix a big gap between the preamble and the content of a page
  (@EmileTrotignon, ocaml/odoc#1147)
- Add a marshalled search index consumable by sherlodoc (@EmileTrotignon,
  @panglesd, ocaml/odoc#1084)
- Allow referencing of polymorphic constructors in polymorphic variant type
  aliases (@panglesd, ocaml/odoc#1115)
- Added a home icon in the breacrumbs (@panglesd, ocaml/odoc#1251)
  It can be disabled with a CLI option.
- Add a frontmatter syntax for mld pages (@panglesd, ocaml/odoc#1187, ocaml/odoc#1193, ocaml/odoc#1243,
  ocaml/odoc#1246, ocaml/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, ocaml/odoc#1234)
- Added CSS selectors to style version and and nav links when they appear
  within page titles, as produced by odig (@katrinafyi, ocaml/odoc#1290)
- Added support for (local) images in the latex backend (@Octachron, ocaml/odoc#1297)

- 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, ocaml/odoc#1239)
  A `@tag` can now be followed by a paragraph or other elements.

- Updated colors for code fragments (@EmileTrotignon, ocaml/odoc#1023)
- Fixed complexity of looking up `.odoc` files (@panglesd, ocaml/odoc#1075)
- Normalize whitespaces in codespans (@gpetiot, ocaml/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, ocaml/odoc#1072)
- Overhaul of module-type-of expansions and shadowing code (@jonludlam, ocaml/odoc#1081)
- Output file paths and labels in the man and latex backends changed to avoid
  name clashes (@Julow, ocaml/odoc#1191)
- Added a `header` field to the json output (@panglesd, ocaml/odoc#1314)
- Changed indentation rules for code block and verbatim content (@panglesd,
  ocaml/odoc#1317)
- odoc-parser: Store raw content in verbatim and code block, and expose a
  function to process it (@panglesd, ocaml/odoc#1325)

- Fix variant constructors being hidden if they contain hidden types
  (@jonludlam, ocaml/odoc#1105)
- Fix rare assertion failure due to optional parameters
  (@jonludlam, ocaml/odoc#1272, issue ocaml/odoc#1001)
- Fix resolution of module synopses in {!modules} lists that require --open
  (@jonludlam, ocaml/odoc#1104}
- Fix top comment not being taken from includes often enough (@panglesd, ocaml/odoc#1117)
- Fixed 404 links from search results (@panglesd, ocaml/odoc#1108)
- Fixed title content not being picked up across pages when rendering references
  (ocaml/odoc#1116, @panglesd)
- Fix wrong links to standalone comments in search results (ocaml/odoc#1118, @panglesd)
- Remove duplicated or unwanted comments with inline includes (@Julow, ocaml/odoc#1133)
- Fix bug where source rendering would cause odoc to fail completely if it
  encounters invalid syntax (@jonludlam ocaml/odoc#1208)
- Add missing parentheses in 'val (let*) : ...' (@Julow, ocaml/odoc#1268)
- Fix syntax highlighting not working for very large files
  (@jonludlam, @Julow, ocaml/odoc#1277)
- Fix backtrace on invalid input in compile-deps (@jonludlam, ocaml/odoc#1313)
- Fix bug in our CSS hitting verbatim blocks in tags (@jonludlam, ocaml/odoc#1312)
- Fix issue ocaml/odoc#610 where `odoc html-fragment` wasn't rendering headings correctly
  (@jonludlam, ocaml/odoc#1306)
@jonludlam jonludlam mentioned this pull request Mar 18, 2025
Merged
mseri added a commit to ocaml/opam-repository that referenced this pull request Mar 20, 2025
@mseri
[new release] odoc (5 packages) (3.0.0) (#27641)
270794d 
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,
  ocaml/odoc#1170, ocaml/odoc#1171, ocaml/odoc#1184, ocaml/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, ocaml/odoc#1189, ocaml/odoc#1248)

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

- Added an `extract-code` subcommand to extract code blocks from mld/mli files
  (@panglesd, ocaml/odoc#1326)

- Added the `odoc classify` command (@jonludlam, ocaml/odoc#1121)
  Helps driver detecting which modules belong to which libraries.
- Added `--warnings-tag` options to the CLI to silence warnings from a unit,
  even if they end up being raised in another unit through expansion
  (@jonludlam, ocaml/odoc#1260)
- Add clock emoji before `@since` tag (@yawaramin, ocaml/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,
  ocaml/odoc#1088)
- Fix a big gap between the preamble and the content of a page
  (@EmileTrotignon, ocaml/odoc#1147)
- Add a marshalled search index consumable by sherlodoc (@EmileTrotignon,
  @panglesd, ocaml/odoc#1084)
- Allow referencing of polymorphic constructors in polymorphic variant type
  aliases (@panglesd, ocaml/odoc#1115)
- Added a home icon in the breacrumbs (@panglesd, ocaml/odoc#1251)
  It can be disabled with a CLI option.
- Add a frontmatter syntax for mld pages (@panglesd, ocaml/odoc#1187, ocaml/odoc#1193, ocaml/odoc#1243,
  ocaml/odoc#1246, ocaml/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, ocaml/odoc#1234)
- Added CSS selectors to style version and and nav links when they appear
  within page titles, as produced by odig (@katrinafyi, ocaml/odoc#1290)
- Added support for (local) images in the latex backend (@Octachron, ocaml/odoc#1297)

- 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, ocaml/odoc#1239)
  A `@tag` can now be followed by a paragraph or other elements.

- Updated colors for code fragments (@EmileTrotignon, ocaml/odoc#1023)
- Fixed complexity of looking up `.odoc` files (@panglesd, ocaml/odoc#1075)
- Normalize whitespaces in codespans (@gpetiot, ocaml/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, ocaml/odoc#1072)
- Overhaul of module-type-of expansions and shadowing code (@jonludlam, ocaml/odoc#1081)
- Output file paths and labels in the man and latex backends changed to avoid
  name clashes (@Julow, ocaml/odoc#1191)
- Added a `header` field to the json output (@panglesd, ocaml/odoc#1314)
- Changed indentation rules for code block and verbatim content (@panglesd,
  ocaml/odoc#1317)
- odoc-parser: Store raw content in verbatim and code block, and expose a
  function to process it (@panglesd, ocaml/odoc#1325)

- Fix variant constructors being hidden if they contain hidden types
  (@jonludlam, ocaml/odoc#1105)
- Fix rare assertion failure due to optional parameters
  (@jonludlam, ocaml/odoc#1272, issue ocaml/odoc#1001)
- Fix resolution of module synopses in {!modules} lists that require --open
  (@jonludlam, ocaml/odoc#1104}
- Fix top comment not being taken from includes often enough (@panglesd, ocaml/odoc#1117)
- Fixed 404 links from search results (@panglesd, ocaml/odoc#1108)
- Fixed title content not being picked up across pages when rendering references
  (ocaml/odoc#1116, @panglesd)
- Fix wrong links to standalone comments in search results (ocaml/odoc#1118, @panglesd)
- Remove duplicated or unwanted comments with inline includes (@Julow, ocaml/odoc#1133)
- Fix bug where source rendering would cause odoc to fail completely if it
  encounters invalid syntax (@jonludlam ocaml/odoc#1208)
- Add missing parentheses in 'val (let*) : ...' (@Julow, ocaml/odoc#1268)
- Fix syntax highlighting not working for very large files
  (@jonludlam, @Julow, ocaml/odoc#1277)
- Fix backtrace on invalid input in compile-deps (@jonludlam, ocaml/odoc#1313)
- Fix bug in our CSS hitting verbatim blocks in tags (@jonludlam, ocaml/odoc#1312)
- Fix issue ocaml/odoc#610 where `odoc html-fragment` wasn't rendering headings correctly
  (@jonludlam, ocaml/odoc#1306)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@panglesd panglesd panglesd approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@Octachron @panglesd @dbuenzli