Add `--suppress-warnings" to avoid inheriting warnings #1260

panglesd · 2024-12-12T14:17:04Z

Authors of documentation sometimes have warnings from other documentation "leak" in their API, due to eg includes from dependencies, or functor expansions, ... This mixes warnings you should act on, with warnings you can't do anything about.

This PR (taken from one of @jonludlam's branch) add a --suppress-warnings flag to tag the docs as not raising warnings. This tag is taken with the includes and expansions, so solve the issue.

No that they are easily available, the PR fixes the warnings reported on odoc's documentation.

The main difference with the taken commits are:

Other names (I used elements instead of docs otherwise that's a lot of docs.docs)
Formatting of unocamlformatted code

Otherwise, I not only cherry-picked the commits but also reviewed them, and it looks good.

When docstrings go are inherited, eg from an include or a functor expansion, warnings may be generated in one docs while the fix is in a dependency. This commit allows to tag each docstring with a boolean to indicate whether it comes from a unit with warnings enabled or disabled.

Julow

Looks good :)

Julow · 2024-12-13T09:23:38Z

doc/odoc.mld

@@ -58,6 +58,4 @@ The main other pages of this site:
 - {!page-ocamldoc_differences} outlines differences from OCamldoc.
 - {!page-dune} shows how to create docs using Dune.
 - {!page-parent_child_spec} delineates parent/child specifications.
- {!page-interface} describes [odoc]'s public-facing interface and their support guarantees.
- {!page-ocamlary} demonstrates the rendering of most of the OCaml constructs.
- {!page-api_reference} lists [odoc]'s API reference library.


Why are these removed ?

interface is not removed (the end of line was removed, I'll add it back)

api_reference was generated by odoc's old reference driver, but is not needed now that we have the sidebar (it was just a way to make the API discoverable)

ocamlary was removed with the library_mlds directory, but for the sane reason we do not need it: we can find it in the sidebar.

Julow · 2024-12-13T09:30:04Z

src/index/skeleton.ml

+      match u.content with
+      | Pack _ ->
+          { Odoc_model.Comment.elements = []; suppress_warnings = false }
+      | Module m -> m.doc


I don't think the new flag is useful in Entry.t. It could be changed to contain a Comment.elements instead.

I could do that in panglesd#35

Thanks, cherry picked as 998b787!

Julow · 2024-12-13T09:48:51Z

src/loader/cmt.mli

@@ -17,6 +17,7 @@
 val read_implementation :
  Odoc_model.Paths.Identifier.ContainerPage.t option ->
  string ->
+  bool ->


This PR adds one thing and I was still confused at this. This should be labelled.
Same in Cmti.

Julow · 2024-12-13T09:51:23Z

src/loader/doc_attr.ml

+  ( items,
+    ( { Comment.elements = d1; suppress_warnings = false },
+      { Comment.elements = d2; suppress_warnings = false } ),
+    tags )


This function should return a pair of elements instead of docs.

I now think this makes sense. We want to propagated suppress_warnings for the top-comments, which are either altered (part of it removed) or included in an other page.

This means that for any documentation file in a package, either mld or module interface, any module in the entire package can be referenced with or without a fully qualified path

panglesd · 2024-12-13T11:34:18Z

I think this is ready to be merged, once the CI is green!

jonludlam · 2024-12-13T12:19:16Z

CI is green enough :-)

@jonludlam

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 the `odoc classify` command (@jonludlam, ocaml/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, 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) ### 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) ### 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)

@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, 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 the `odoc classify` command (@jonludlam, ocaml/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, 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) - 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) - 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)

panglesd added a commit to panglesd/odoc that referenced this pull request Dec 12, 2024

Added changelog entry for ocaml#1260

5e65ca0

panglesd force-pushed the suppress_warnings branch from 182cb8b to 5e65ca0 Compare December 12, 2024 14:37

panglesd mentioned this pull request Dec 12, 2024

Try to resolve references in stage 0 #1261

Draft

Make driver suppress warnings for unselected packages

f40f393

panglesd added a commit to panglesd/odoc that referenced this pull request Dec 12, 2024

Added changelog entry for ocaml#1260

07d30c2

panglesd force-pushed the suppress_warnings branch from a559d00 to a3de36c Compare December 12, 2024 15:43

Julow approved these changes Dec 13, 2024

View reviewed changes

Julow mentioned this pull request Dec 13, 2024

Use Comment.elements in document and index panglesd/odoc#35

Closed

jonludlam and others added 6 commits December 13, 2024 12:24

Fix errors in odoc's docs

e0b87bf

Driver: Make pkg_args opaque and use maps

6bb79a5

Driver: Ensure all package libraries are available for linking

eefa58c

This means that for any documentation file in a package, either mld or module interface, any module in the entire package can be referenced with or without a fully qualified path

Added changelog entry for ocaml#1260

ec42df0

Compatibility

cd106cf

Promote mdx tests

345ef53

panglesd force-pushed the suppress_warnings branch from a3de36c to 345ef53 Compare December 13, 2024 11:24

Julow and others added 2 commits December 13, 2024 12:25

Use Comment.elements in document and index

998b787

Label boolean argument for loading functions

593b898

panglesd force-pushed the suppress_warnings branch from c63fc05 to 593b898 Compare December 13, 2024 11:33

jonludlam merged commit 6a3ed64 into ocaml:master Dec 13, 2024
12 of 13 checks passed

jonludlam pushed a commit that referenced this pull request Dec 13, 2024

Added changelog entry for #1260

9140338

jonludlam mentioned this pull request Jan 23, 2025

[new release] odoc (5 packages) (3.0.0~beta1) ocaml/opam-repository#27309

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `--suppress-warnings" to avoid inheriting warnings #1260

Add `--suppress-warnings" to avoid inheriting warnings #1260

panglesd commented Dec 12, 2024

Julow left a comment

Julow Dec 13, 2024

panglesd Dec 13, 2024

Julow Dec 13, 2024

Julow Dec 13, 2024

panglesd Dec 13, 2024 •

edited

Loading

Julow Dec 13, 2024

Julow Dec 13, 2024

Julow Dec 13, 2024

panglesd commented Dec 13, 2024

jonludlam commented Dec 13, 2024

Add `--suppress-warnings" to avoid inheriting warnings #1260

Add `--suppress-warnings" to avoid inheriting warnings #1260

Conversation

panglesd commented Dec 12, 2024

Julow left a comment

Choose a reason for hiding this comment

Julow Dec 13, 2024

Choose a reason for hiding this comment

panglesd Dec 13, 2024

Choose a reason for hiding this comment

Julow Dec 13, 2024

Choose a reason for hiding this comment

Julow Dec 13, 2024

Choose a reason for hiding this comment

panglesd Dec 13, 2024 • edited Loading

Choose a reason for hiding this comment

Julow Dec 13, 2024

Choose a reason for hiding this comment

Julow Dec 13, 2024

Choose a reason for hiding this comment

Julow Dec 13, 2024

Choose a reason for hiding this comment

panglesd commented Dec 13, 2024

jonludlam commented Dec 13, 2024

panglesd Dec 13, 2024 •

edited

Loading