Try   HackMD

…

tags: minutes

odoc Dev Meetings

2025-01-22

## What's been going on?

PRs merged: 1283 1281 1282 1280 1278 1279 1277 1276 1275

PRs opened: 1284

Release plan:

  1. Merge #1284
    1.5 Merge changes to CHANGES?
  2. tag and release to opam-repository 3.0.0-beta1
  3. generate docs with odoc_driver (without remap) and push to ocaml.github.io/odoc
  4. announce beta on discuss.ocaml.org (https://hackmd.io/b6NCEbsbS0mTz6K-0rAczA)

## suppress_warnings

turn this into a string tag rather than a boolean

2025-01-15

Participants

What's been going on?

Merged PRs:

New PRs:

Menhir work:

  • Going well! just about done
  • Location problems to be fixed, but should be simple.
  • Can do tech talk!

Release

TODO before release:

  • source rendering PR (@julow)
  • minor bits of the monorepo PR
  • documentation of driver

Release plan:

  • Tag beta release
  • Update docs-ci to use this tag
  • Get a build of ocaml.org using this on staging.ocaml.org
  • Build docs
    …time passes… (~1-2 days?)
  • Release to opam-repository
  • Announce post on discuss

2025-01-08

Participants

2024-12-18

Participants

What's been going on?

New PRs:

  • Try to resolve references in stage 0 (1261)

Merged PRs:

'dune mode'

  • had a quick demo
  • maybe rename it to 'monorepo mode'

Other

  • problems with odoc-md - footnotes, some location errors

2024-12-11

Participants

What's been going on?

New PRs:

  • Vendor Sherlodoc
    By @julow - this is using a git subtree so is effectively copying in the sherlodoc repo with all of its history

Merged PRs:

The futher-voodoo PR has been rebased and some more commits from the docs-ci branch pulled in.

Testing

  • A lot of testing has been going on - mainly using the docs-ci branch.
  • Testing has started in earnest on the 'dune-style' mode, which will require some fixes before release.

Sherlodoc update

  • Consensus:

  • Take core engine of sherlodoc into the odoc repo, and out of the sherlodoc repo, which will only retain the frontend code.

  • The versions of all packages will the same , ie., we will release sherlodoc-3.0.0 soon!

  • could move the indexing code clientside to save on space when transferring the javascript blob.

2024-12-04

Participants

What's been going on?

New PR:

Existing PRs:

  • Dedicated sidebar file

    • This one is the prerequisite for the 'uniform treatment of sidebar' PR. Some review has happened

  • HTML remap

    • Some review and some fixes following the review
    • Probably ready to merge

Issues

  • More fields in @doc-json
    • This one is of interest - it was a request for there to be some more fields included in the '–as-json' output. Let's have a quick chat about it.

Other

The issue discussed last week of errors from dependency packages was investigated by @jonludlam, and a PR will be incoming soon. The change involves putting a suppress-warnings field here. This is set when initially reading the cmt/cmti/cmi file, and is preserved when doing expansions. We then use it while resolving references to decide whether or not to keep the warnings.

This will largely solve https://github.com/ocaml/odoc/issues/1127 and, along with the html-remap branch, will also solve https://github.com/ocaml/odoc/issues/1120.

As an 'experience report' I used this to check the build of odoc's documentation, and found a bunch of real errors that I could actually do something about, and now on my branch there are no errors!

Fields in --as-json output

Issue #1134 requests more fields in the json output.

Easy ones:

  • title - this is pretty straightforward to get
  • sherlodoc path to db.js - maybe easy?

Trickier ones:

  • package - odoc doesn't know. The driver does, of course, and we could easily write a different json file with this sort of data in.
  • version - ditto
  • objects - not quite sure what's wanted here.

Search for ocaml.org

  • We have sherlodoc, obviously
  • It's really big! Previous search index (used for client-side search) is ~1/10 the size of the sherlodoc index
    • e.g. old index for core is ~1Mb compressed, new is 9Mb compressed.
    • Why?
  • What to do? We could mimic the old index?
    • Conclusion: Yes, let's do this!

2024-11-27

Participants

What's been going on?

In odoc, doesn't look like much has been going on:

Merged PRs:

Opened PRs:

  • Further Voodoo
    Following on from the reorg of the hierarchy, this contains some
    more minor fixes for voodoo mode.

New issues:

Because the focus has been on ocaml.org integration:

  • Docs pages rendering OK
  • Sidebar coming from odoc "natively"
    • required some fixes on the sidebar PR!
  • Breadcrumbs not yet fixed
    • (they aren't using short title yet)
    • Not removed the 'library' logic yet
  • source rendering working, but without syntax highlighting

Also

  • Reference resolution work:

to fix this issue

Annoying problems in stdlib:

map.mli reference to bindings is ambiguous here
set.mli reference to elements is ambiguous here

might be worth taggin the location with whther warnings are enabled or not

multiple roots can be enabled!
source files are now also in the sidebar

Sherlodoc

is always broken!

  • TODO: have a meeting with arthur ASAP.
  • @julow preferes subtree to submodule, copy-and-paste vendring also fine
  • @panglesd suggests git subrepo as a solution too

2024-11-20

Participants

## What's been going on?

…

Uniform treatment of sidebar

2024-11-13

Participants

What's been going on?

Merged PRs:

  • Driver: package and library arguments
    • This is essentally about tracking dependencies - either using ocamlfind META files to track library dependencies, or by using opam to track package-level dependencies. As an example of the difference, the former would never generate docs for dune unless you're using one of dune's libraries, whereas the latter would almost certainly produce docs for dune.
  • Update ocaml/setup-ocaml to v3
    • Thanks to @smorimoto and @panglesd for their work on this!
  • Document Url.from_identifier result return type
    • The very confusing function has had some more docs added to it. Work is ongoing to make the function itself more sensible (see the PR removing core types and exceptions from identifiers below, #1242)
  • New driving page
    • @panglesd has been doing the important work of documenting what the driver is doing to generate the docs.
  • Represent sidebar TOC as a Tree
    • @gpetiot split the large PR by @panglesd refactoring the sidebar into smaller, more digestible chunks. This was the second, following #1228. The third and final is listed below.
  • Split odoc_driver into 3 sub-commands
    • Running the driver in the various different modes was getting confusing. @gpetiot has split it into 3, though this is at the expense of some usability.
  • Driver: New hierarchy
    • This simplifies the hierarchy of the output trees by default, as agreed previously.
  • Allow more hierarchy to be compatible with -L and -P
    • Prerequisite for the above.

New PRs:

Ongoing work:

  • Standalone markdown support

    • Been reviewed and rebased. No comments from daniel. No news is good news?

  • Usability improvements for odoc_driver

    • Showing doc errors from odoc, but only 'actionable' ones - ie, from the packages you've selected to document
    • Only producing HTML for the packages you've selected, and have the links to other packages redirect to ocaml.org

What's the plan?

  • Deliver to JS a mode of odoc_driver that can run on 'minijane' and produce reasonable output. This has to include handling of markdown docs within the tree with links between pages.

  • Produce a version of ocaml.org on the staging server (https://staging.ocaml.org/ or similar) with a beta version of odoc 3 that can be tried by the community.

  • By the end of the quarter :-)

Implicitly ended tags

As discovered by @panglesd when implementing the new tag behaviour, lists already had a mode where they were ended by a blank line, tag or heading. A consequence of this was a slightly odd interaction between the new 'one block item only' behaviour and the behaviour of lists. Consequently he suggested we reuse this behaviour for the ending of tags, and has made PR 1239 implementing this.

Everyone is happy with the idea of ending tags in the same way that list items are ended.

2024-11-06

Participants

What's been going on?

  • Markdown input PR created #1234
  • PR for allowing the simplified hierarchy to be used #1233
  • The sidebar PR is being broken down into easier-to-review commits
    • Tree module - merged: #1228
    • Sidebar, ongoing: #1232
  • PR for specifying dependencies via opam packages rather than just ocamlfind META dependencies #1229
  • PR for the new simplified hierarchy #1236
  • Merged PR tidying variables in driver: #1235
  • Merged PR fixing unresolved links in docs pages #1231
  • More ideas on tags #1226
  • Started work on making odoc-driver show user-useful warnings from your docs
  • Further progress on error-recovery in menhir parser

Tags

Much discussion on the tags issue.

Suggestion 7: curly brace immediately after the tag

@return{ foo bar 

this is a longer return tag

}

@raise Failure if it fails
..
}

Suggestion '6' adds new extensible blocks and inlines {%% block %} and {% inline %} but custom tags is the previously existing feature that satisfies this problem (not inlines though). It was noted that {%...%} is currently used for inline HTML and the like.

General agreement that it's quite nice not to have to alter the beginning of your tag in order to have it span multiple blocks.

Also remaining greppable is good, so no @{return.

There are issues with parsing - we need to make sure that error reporting works well - in particular the importance of the whitespace here:

@tag{ [verbatim] this is an extended tag}

@frontmatter {[ code block, not an extended tag ]}

2024-10-30

Participants

What's been going on?

  • Prototype of different hierarchy published
  • Merged the big CI branch
  • Discussions on tags
    • @panglesd did a more in-depth review of the tags with multiple blocks CI run
    • 3 possibilities of tag breaking, discussion on issue
    • A few possibilities of how to group things within 1 tag too
  • Working on markdown input

Alternate layout

for e.g. base

ocaml.org/p/base/latest/index.html <- index.mld from the package docs
ocaml.org/p/base/latest/base/Base/index.html <- module Base

Looks like we should go ahead with the simpler structure.

Decisions

  • Use simpler structure
  • Use tags in index.mld pages to control breadcrumbs and redirects - using odoc namespaced tags for these internal use cases
  • Old structure should still be possible - ie, don't make any assumptions about the layout within odoc.
  • discussions on tag extent are still ongoing on the tickets. Please engage there!

2024-10-23

Participants

What's been going on

x-extra-doc-deps: [
  "core" {= "0.17.1"}
]

​​​​- Backport of the OCaml 5.3 fix to the odoc 2.4 branch
​​​​    - Should release odoc 2.4.4 soon
​​​​- Occurrences is working at JS!

2024-10-16

Participants

What's been going on

  • Merged changes to occurrences CLI
  • Lots of discussion on the frontmatter PR!
  • Milestone on GH to track release
    • Suggestion: Release 3.0-beta with 'beta' ocaml.org (ie, staging.ocaml.org or similar)
    • Ask for feedback specifically on the cross-package stuff / source rendering etc
  • Sidebar work
    • 'Deep json' and some HTML changes too
  • Started improvements to the index pages

Frontmatter

Some notes here: https://hackmd.io/HGi28Ga1SCOIBppfkgG7kw

2024-10-09

Participants

What's been going on

  • Merged PRs
    • OCaml 5.3.0 compat
    • Config file for extra libs/packages
    • Specify children order in frontmatter
  • PRs in flight
    • Frontmatter syntax
    • Docs CI fixes
    • Documentation for driving odoc
    • count-occurrence CLI
  • Menhir progress

What needs to be done:

  • Markdown rendering, including turning links into references somehow
  • "Deeper" sidebar json
  • Dune-style mode improvements
    • Think about layout more - exactly what do we want as output?
  • Separate compile/link phases for voodoo mode
  • Opam metadata for extra packages for references
  • Better breadcrumbs
  • Better index pages (e.g. direct links to modules from the libraries index page)
  • A way to 'open' modules in mlds
  • Investigate server-side search
  • Bug fixes:

2024-09-25

Participants

What's been going on?

  • Initial work on dune rules
    • Moved from –parent to –parent-id (in @doc-new)
    • Some refactoring
    • It's a big task!
  • Agreement on frontmatter syntax:
(children
  tutorial
  file1
  examples/
  examples)
  
(open Stdlib)
---
{0 Title}

blabla
  • Agreement on sidebar for OCaml.org integration
  • Good progress on menhir parser

Extra packages for linking todo:

e.g. request from Vesa:

So… If I have a single dune-project that specifies multiple packages

​picos -(depends on)-> exn_bt
​picos_std -(depends on)-> picos
​picos_stdio -(depends on)-> picos
​picos_stdio_cohttp -(depends on)-> picos_stdio
​picos_lwt -(depends on)-> picos

then how do I reference modules defined in one package from the documentation in another package?
These packages and modules are designed to work together. So, for example, to provide an example that uses a specific module from a specific package, e.g. picos_std, I want to use, in the documentation, modules from other packages, e.g. picos_stdio , even though there is no transitive dependency between those packages (that is actually the magic juice of the whole thing - that these things interoperate without depending on each other - and the main reason this whole thing even exists).
I can do that easily with the dune mdx stanza (I just specify the libraries used), but how do I provide links for the reader of the documentation?

  • split odoc_driver into compile/link phases
  • split docs-ci into compile/link phases
  • agree on how to specify extra packages in opam file / switch metadata for docs linking

2024-09-18

Participants

What's been going on?

  • Minor bug-fixing work on odoc / the driver, from the docs-ci builds

Questions:

  • What to do with libraries where units are present in more than one library?
  • What to do with virtual libraries?

2024-09-11

Participants

What's been going on?

  • Working on integration with docs-ci for building package docs for ocaml.org
    • Realised that the 'cross package' feature is going to require separation of compile/link phases in odoc_driver
    • Some bug fixes in odoc
  • Good progress on replacing the current odoc-parser with a menhir parser - many more tests passing
    • concentrating on positive test right now rather than the tests of the failure cases
  • Defining and implementing a config file for specifying extra package and library dependencies: odoc-config.sexp in <opam root>/doc/pkgname/
    • PR opened (#1194)

FunOcaml next week

  • @panglesd doing a presentation on writing docs for your ocaml packages!
  • Noticed that odoc's docs are missing from ocaml.org!

2024-08-28

Participants

What's been going on?

  • Merged asset referencing PR (#1184)
  • Merged frontmatter PR (using code block, as agreed last week) (#1187)
  • Merged separated commands PR (ie, odoc html-generate-source etc) (#1188)
  • PR created to fix libraries available during link of libraries (#1192)
  • Merged 2 PR with some model cleanups (#1177, #1176)
  • Merged HTML remap PR (#1189)
  • Merged PR to generate index pages (#1183)
  • PR created for better breadcrumbs (#1190)
  • Working on page reordering (for Table of Contents)
  • Menhir rules

Question on usefulness of mini-jane

  • Still useful as a reference, as existence proof that a good output is possible
  • Not going to be used as-is by JS

2024-08-21

Participants

  • @jonludlam
  • @paul-elliot
  • @luke-maurer
  • @xVIgSu9rREWaUrm7A6vRsA (Sabine)
  • @julow

Splitting commands into more specific ones

  • To help with command-line arguments - some only make sense for particular types of inputs
  • e.g. html-generate becomes html-generate, html-generate-impl and html-generate-asset with different arguments to each

What's been happening?

  • Assets
    • New compile command
    • Linking not required
    • New pipeline makes old pipeline obsolete, and needs removing
  • Frontmatter on mlds
    • PR made, using normal codeblock with a specific tag 'meta'
    • line-based key-value pairs
    • @julow suggests a syntax more similar to markdown (ie, –- delimited)
    • decision: merge PR as-is to unblock things that depend on it, revisit concrete syntax before release.
  • External pages
    • PR open for review
  • Remapping
    • In order to publish your library's docs on your website without unresolved links but without having to publish the docs for all of your dependencies
  • Driver work
    • Replacing voodoo in docs-ci with odoc-driver
  • Breadcrumbs
  • Media
    • Alt-text - decision: should be just plain text (maybe with balanced braces?)

Things to do before release:

  • Decide how to specify package dependencies, including how to query it
  • Decide on short titles for breadcrumbs/sidebar
  • Dune rules
  • Ocaml.org integration

2024-07-31

Participants

  • @julow
  • @paul-elliot

What's been happening?

Odoc 3:

  • Reviewed, finished and merged the multiple input driver PR.
  • Reviewed, finished and merged the asset compilation and resolution.
  • Generating the external pages needed some refactoring: separating the odoc compilation unit from the "package" abstraction. Opened https://github.com/ocaml/odoc/pull/1179.

General work:

2024-07-24

Participants

  • @julow
  • @paul-elliot

What's been happening?

Odoc 3:

General work:

2024-07-17

Participants

  • @jonludlam
  • @paul-elliott
  • @lukemaurer
  • @emile

'Extra pages' meeting

https://hackmd.io/dzznXP17Tj-ybUbuxdKwPw

Conclusions

(taken from linked page above, copied here for convenience)

  • We do not want yet to provide a way to user to write any new page (in the opam installed doc building convention)
  • No way in user-written pages to link to driver-generated pages such as package landing page. For driver-generated pages, we can link to driver-generated pages using "fake" -P with driver-generated names.
  • Landing page for packages is like in ocaml.org (README etc) in the "convention for buliding opam installed packages"
  • Breadcrumbs:
    • We use info from our own -P/-L to generate a not clickable breadcrumbs with "Lib: <library name>"
    • For now: Package: <package name> >> Lib: <library name> >> ?
    • Then experiment with our driver and the odoc CLI to shorten everything (urls, breadcrumbs) when the library name and package name are the same
    • Do we want a "Top" >> at the beginning for odoc driver/dune docs/odig/Jane Street usecases? Not for now?! If we do it, it should depends on options passed to the html driver.
    • No breadcrumbs for the hierarchy pages (the one outside of a packagem such as the list of packages)
    • For "package relevant pages" (list of libraries, package landing page, library landing page):
      • Use --current-package to have Package: <package name> for package landing page and library lists.
      • Use --current-package and maybe -L or --current-lib to have Package: <package name> >> Library: <libname> for library landing page.
      • EXPERIMENT!
  • Sidebar
    • For package-relevant pages:
      • Same global sidebar as package pages
    • For other pages:
      • No global sidebar?
    • Jane usecase:
      • We need to be careful to make the sidebar useful. Depends on how "packages" are created from JS repo: the global sidebar might be uselessest or uselesser if the packages are too big or too small.
      • This package grouping should be based on the filesystem hierarchy.

Mini-jane

  • Docs will be put in labelled 'docsets', labelled with the name of the open-source package if it's open, something internal if not
  • We can collaborate via mini-jane, aim to have a early alpha by the end of August. JS UX people can then get involved!

What's been happening?

Odoc 3:

  • Working on the driver to use different inputs - will be useful for mini jane, also for replacing large parts voodoo.
  • Finishing and merging reference parsing/resolving PRs, and the second sidebar PR
  • Adding external pages (ie, non-package pages including landing pages and hierarchy pages)
  • Asset referencing PR is being rebased
  • Work in progress on implementing Assets CLI

General work:

2024-07-10

Participants

  • @emile
  • @paul-elliot
  • @julow
  • @lukemaurer

Minijane

  • Got a repository that resembles the 'jane' monorepo
  • Compiles with dune
  • we should make our driver work on a monorepo that looks like that

What's been happening

  • @jonludlam visit to JS
  • variants work merged PR 1115
  • Lots of review work
    • Indexes were turned into marshalled types - merged
    • Sidebar PR rewritten to use index - review happened, unmerged yet
    • Sidebar CSS work, to be pushed soon
    • Path reference parsing reviewed
  • New intern at JS working on Sherlodoc
    • Emile has offered to help if anything can be done in public
  • A bit more on Voodoo compatibility

What's going to happen

  • Sidebar to merged soon
  • References to pages to be merged soon
  • References to modules to be PR'd soon
  • Resuming work on assets soon

2024-07-03

Participants

  • @sabine
  • @paul-elliot
  • @julow

Windows CI

  • Has been run! Didn't completely fail!
  • Some relatively minor issues to fix, mostly fairly obvious
  • We'll only merge the CI changes once it's passing.

What's been happening?

  • Work on making sure the new odoc driver will be able to handle the jobs that voodoo currently does to generate output compatible with the needs of ocaml.org
  • Reviewed search PR
  • Sidebar PR addressing review comment
  • current-package option
  • Work on resolving of local references
  • JS: Occurrence counting deployment and syncing with master

2024-06-26

Participants

  • @jonludlam
  • @sabine
  • @julow
  • @lukemaurer

Parameterised paths discussion

  • Presentation of the branch 'parameterised-paths' which unifies the cpath.ml types and the paths_types.ml types.
  • Compilation speed extremely slow (40s -> 15 minutes!!)
  • Runtime equivalent
  • Complexity of tools.ml reduced
  • Opportunities for optimisations

What's been done in the past week

  • Work on parameterised paths (unification of cpath.ml and paths_types.ml)
    • This will lead to a simplification of the code (though not the types!) and opportunities for optimisations.
  • PR for parser for broken parsing of ][ in code
  • Advanced reference resolution:
    • Option for CLI to pass in the current package name (for Bunzli-style // references)
    • Will make the semantics slightly less package-centric
  • JS working on deployment for occurrences, and pulling in recent changes in master for new CLI command compile-impl

2024-06-05

Participants

2024-05-29

Participants

  • @jonludlam
  • @panglesd
  • @sabine-s (sabine!)
  • @emile
  • @lukemaurer

New markup discussion

Paul-Elliot has written up some suggestions: https://hackmd.io/ETSOAmetTI-E3vrDk3Bfrw

  • Admonitions: all in favour, but with a limited set: Note and Warning
  • Quotes: all in favour
  • Definition lists: all in favour!
    • with links
    • can this be merged with existing lists?
  • Code spans: Some discussion - perhaps make it more a semantic block like 'pre'? No agreement yet!
  • Details : all in favour!
  • Strikethrough: all in favour!
  • Footnote: Question: where do they go? especially in modules / includes / etc
  • Toc: good idea - questions about which tocs can be accessed!
  • productionlists - just a code block with a 'better' highlighter?

Reference resolution

Problem:










module Foo : struct
  type t
  
  module type Bar = sig
    (** Reference to {!t} *)
  end
end

module Baz : Foo.Bar

Currently as references are resolved only at link time, the reference in Bar won't resolve inside the expansion in Baz.

To fix this, I think we need to be resolving references more like paths, at compile time. For example, in the above, we'd resolve {!t} during the compilation of Bar. At the point we then expand Baz, we'd look up Foo in the environment, which at that point would contain the compiled signature for Foo (and so Foo.Bar as well).

However: what do we do with forward references? e.g.:










module Foo : struct
  module type Bar = sig
    (** Reference to {!t} *)
  end

  type t
end

module Baz : Foo.Bar

2024-05-22

Participants

  • @panglesd
  • @lukemaurer
  • (sabine!)

Module-type-of fixes: merged!, driver merged

  • Current status: believed fixes the crashes at JS
  • Mostly improved output
  • Some shadowed idents still appearing and some extra

Daniel's comments on the proposal

I don't think I entirely got where this metadata block is supposed to be and what exactly has to be mentioned. But it's likely that if I'm making references on other packages I don't want to repeat that information in every mld document. Shouldn't this simply contain toc for .mld pages and the other field rather live in a global metadata file, e.g. at the root of odoc-pages, or even, in META files (which are extensible) ?
As a driver author I don't want to parse this metadata block. If the driver will need that info odoc should be able to extract it for me in a simple from like e.g. we have for deps (I don't mind lines based, json or sexp).
I'm wondering if, rather than installing .mld we should not start installing some form of compiled, say .mldt, files, this could help for example with issue
Warnings to unresolved references make odoc unusable #1120
I'm not sure I fully understood the discussion about libraries and bread crumbs. But just bear in mind that most of the time having people go through index page -> library page -> module is going to be horribly clicky and unsusable1. In 95% of the cases it will be more than enough to have one section per library on the package landing page with and their module indexes here. Here are a few examples of what I consider reasonably usable landing pages brr, webs, zipc, bytesrw.

  • We want a package-global metadata file with stuff relevant to all pages, e.g. deps
  • Not to be read/written by odoc the binary
  • We'll do the '//' thing
  • How does everyone feel about progressive enhancement?
  • Ocaml.org experience suggests sidebar is huge and slow!

2024-05-15

Participants

  • ?
Before:
{!/pkgname/something}
{!//this/is/my/root}

After "Now, ":" is used to separate the named root from the actual path":
Rule is :
- There is a / -> path
- There is no / -> local search
- There is a "pkgname:" -> do the resolving inside pkgname
- There is no ":" -> same as "yourpkg:"

{!pkgname:page-global}
{!pkgname:/path/page-local}

{!/this/is/my/root}

{!pkgname:foo} -> local search within package

2024-05-01

Participants

  • @jonludlam

2024-04-17

## Ordering of work

  • Make sure CLI work is done first!

Participants

Odoc 3.0 work

Assets again

CLI description

Markdown support

  • https://github.com/ocaml/odoc/pull/1110

  • Agreement that being able to consume standalone gfm pages is a good thing.

  • Could possibly lint for markdown-ish comments?

  • Argument against - adding links to API docs from gfm pages will be annoying

    • URI scheme?
      • [link](odoc:module-Foo.type-bar)
    • Links shortcuts
      • [link][!module-Foo.type-bar]
      • [!module-Foo.type-bar]

  • Use 'full' reference syntax rather than 'asset path'

  • cmarkit comes with a ocaml 4.14 lower bound, and we're happy with that for odoc, helps with maintenance!

  • 2.4 will probably live on for a while with critical bug fixes only, and retain the lower bound of 4.02

Next items

  • Sidebar
  • Search / Occurrences
  • Support files

Module-type-of problems

Odoc 2.4.2

Syntax for comments

Let's try this:
(* *)

first, and if it's too annoying let's do this:
`{@comment[

]}
`

2024-04-10

Participants

Odoc 3.0 status

Assets

https://hackmd.io/08MIstgdRWOLVlLFFJJEvQ

  • decisions:
    • Use more restricted parsing in assets references (ie, no special treatment of - and .)
    • investigate also the idea of making the parsing in usual references more accepting of pre-hyphen idents that it doesn't understand.

Source rendering

https://hackmd.io/c6u6V9NORH6c3K_DyR3NVg

  • generally OK, need to rewrite to publish

Markdown support

Current direction is to support handling of markdown files and nothing else (yet).

The use of cmarkit is being trialled, and this is bringing some constraints on the version of ocaml supported (cmarkit currently requires ocaml >= 4.14)

Paul-elliot to do some more investigation

Module-type-of fixes

  • docs run at JS still running

2.4.2 release

Wait for https://github.com/ocaml/ocaml/pull/13001 which might make API changes to OCaml's shapes.

2024-03-27

Participants

Odoc 3 referencing etc doc

Next docs:

  • Assets - paul elliott to drive
  • Source rendering - @jonludlam to do

Markdown support

  • paul elliot to work on this - markdown files, not markdown in mlis or the like.
  • odoc links could be uri style: odoc:module-Foo or similar

OCaml 5.2 release

  • backport changes

JS status

  • rules being investigated and understood!
  • still need to try the module-type-of PR since the async_kernel fix

2024-03-13

Participants

Resolved questions:

Unresolved questions:

2024-02-16

Participants

Proposal for ocaml.org (https://hackmd.io/Q1t-0xH9RRibUTnMj5OfGg)

  • Review requested
    • Still in flux right now
    • Feedback would be very useful
    • Meeting next wednesday 21st at 1pm UK, 2pm France

JS feedback?

  • Server issues
  • Occurrence info is top priority right now

Releases

  • 2.4.2 with 5.2 compat
  • 3.0? with new build-system-friendly, ocaml.org-friendly, source-rendering-friendly features!

Longer-term musings

2024-01-18

Participants

Proposal for ocaml.org (https://hackmd.io/Q1t-0xH9RRibUTnMj5OfGg)

  • @jonludlam is keen on having a way to hand-write the sidebar contents
  • @julow suggests it can still be autogenerated
    • worried about extra maintenance
    • can forget pages

2024-01-04

Participants

Odoc 2.4 released!

Hints of some unexpected output differences with 2.3.1 maybe? Will investigate and report back

PR changing how source rendering is driven

  • also need to look at parent-child stuff

2023-12-07

Participants

Odoc 2.4 release

Module type of progress

  • Looking generally good
  • Feedback from JS would be really useful!
  • Questions
    • OK to remove fallback signatures from includes?
    • OK to hide everything with a double underscore?
  • Performance: Need to confirm perf impact
  • 'module_type_of_size' test 'fixed'
  • Dune rules are broken

2023-11-09

Participants

New releases

  • Odoc 2.3.1 / Odoc 2.2.2
    • Fixed OCaml 5.1 compatibility

module type of fixes progress

Merged stuff

  • Improvements to profiling
    • maybe add bonsai to the set of tests?

Releases

  • Agreed to release soon, with search / media / assets

Source rendering pipeline

  • Produce a design for us to agree on
  • Contact daniel and say that the pipeline might change
  • mark the command line as unstable

Assets PR

  • Only change asset handling in this PR
  • Second PR to do page children

Something to think about

How to reference a module in a package?
Can't do just page-pkg.module-A as this isn't the hierarchy that ocaml.org uses
Perhpas the sidebad for navigation might help?

2023-10-26

Participants

Odoc 2.3 status

  • Released!
  • Bugs :-(

PRs in progress

Handle differences in sig_class for OCaml 5.1. (to master branch)

  • bugfix from 2.2 branch
  • need to cherry pick another commit

change color to gruvbox theme

  • keep the newly organised colour definitions
  • drop the actual colours

Micro-optimize Ident.compare

  • Should just be merged

Doc: parent-child convention for installed packages

  • Just doc what we've got, note the problems with it, not try to design v2 yet.

Medias in odoc

  • alt-text and unresolved image/placeholders need to be decided

Asset references

  • try to do the resolution the other way, and see if it looks better

Move the sidebar to be stuck to left of the content

  • Jules to have another look

Collect occurrences information

  • PR to split into more easily reviewable smaller PRs
  • trefis will npot review the changes to paths and resolve, but will review the other parts (the typedtree traversal)

Support for search in odoc

  • Ready re-review (jon)

HTML: Match rendering of polymorphic variant with normal variants

  • to be reviewed/rebased and merged

Humanist font fallbacks

  • Jules to close this in favour of another to remove the existing fallbacks

Preformatted elements fallback to UA monospace

  • Jules to follow up

Include missing preformatted text elements

  • Closed

Remove expansion from "unexpanded" module type of

Add hidden attribute

  • go back to leo's comment about why - and explain why!

Fix references to extension declarations

  • quick review pass then merge

Fix rendering of references to label

  • quick review pass then merge

Allow to omit parent type in constructor reference

  • quick review pass then merge

Luke's visit to Cambridge

2023-07-13

Participants

2023-07-06

participants

Source code rendering anchors

  • Don't release 2.3 until we have reliable anchors

  • Release 2.2.1 with OCaml 5.1 compat ASAP

  • Probably do need the location map from the shapes for the feature.

Hidden tag

  • Some work ahas happened to do this, it's quite hard though
  • Perhaps at the same time replace the root of references with the identifier

2023-06-01

Participants

@jonludlam

News

Dune rules PR sent: https://github.com/ocaml/dune/pull/7840
Tables PR merged: https://github.com/ocaml/odoc/pull/893

Vendoring odoc-parser

  • @Julow's preferred approach
    • copy module source
    • create new dune fules
  • @jonludlam's suggests approach of opam-monorepo - clone odoc-parser, remove .git, add to repo with README
  • Further opinions sought

Module-type-of problem

  • Suggestion: add a new constructor in the AST to represent the ascription operation - maybe in the TypeOf values or in the paths - and defer expansion until later (outside of subst)

Source rendering

when processing cmt files, we sometimes get hidden types that dnt go through the canonical aliases. We could try to keep track of moule aliases so we can have another go at finding a non-hidden path for a resolved hidden path.

2023-05-04

Participants

@jonludlam
@emile

Discussed the difficulty of searching within module aliases, as these are not expanded by odoc

Sherlodoc prototype:
https://github.com/EmileTrotignon/odoc/commit/7320faa82780f2cab7acd308cccc5aa0352318a3
https://github.com/art-w/sherlodoc/commit/f7765ff2e2efc7f0ffde79fa115d501c5371221e

2023-04-20

Participants

@jonludlam
@julow
@sabine
@panglesd
@lubegasimon
@lukemaurer

Metadata

  • Metadata came up during the discussions about tables. @jonludlam wanted a more generic way to declare metadata rather than coming up with a new mechanism every time we need something.

  • We have metadata! @-tags!

  • ocamldoc has extensible @-tags! https://v2.ocaml.org/manual/ocamldoc.html#sss%3Aocamldoc-custom-tags

  • Looks to me like they're 'block' tags, ie, can only come at the end of a block of text. ie:

type ocamldoc_tag =
...
  | `Custom of string * nestable_block_element with_location list

so perhaps not so good for alignment, where you want to have alignment at the start of the contents of the tag?

  • Suggestion: @foo{ blah blah } to delimit the content?

  • Concretely, for tables, we could do:

  1. {td @meta{left} hello}
    • pro: delimited extended tag - ie, odoc-parser does not know about the tag '@meta', it comes as something like: `Tag (`CustomTag ("meta", [`Paragraph (`Word "left")]))
    • con: a bit verbose

alternatively:

  1. {td @left hello}
    • pro: lightweight
    • should odoc-parser parse this as
      • `Tag (`Custom ("left", [`Paragraph (`Word "hello")])) :: []
      • `Tag `Left :: `Paragraph (`Word "hello") :: []
      • ?

Suggestions from julow:

How about explicitly attaching to the tags:

{{!ref}markup}
{{td attr=value} ...}

avoids the problem of the scope of the tag being not obvious.
Tags become attributes that can be used for future syntaxes (eg. images).

  • not blocking merge/release of tables in odoc

Custom-delimited code blocks

Code blocks are currently:

{@ocaml[
...code here...
]}

this is annoying when your code has ]} in it! e.g.:

{@ocaml[
type t = {x:int list}
let v = {x=[1;2;3]}
]}

solution - similar to custom string delimiters in OCaml - let s = {hi| "|} |hi}:

{foo@ocaml[

type t = {x:int list}
let v = {x=[1;2;3]}

]foo}

can then also have the metadata:

{foo@ocaml env=e1 nondeterministic[

]foo}

mdx

  • mdx now supports mld files

  • mdx has always had a problem putting errors in:

{[
 |let x = {
]}

becomes:

{[
  let x = {
]}```mdx-error
Line 2, characters 1-3:
Error: Syntax error
```

and then mdx fails to parse the updated file!

File "_none_", line 64, characters 2-14:
Paragraph should begin on its own line.

Need a way to put an error in in such a way that we can take it out again when the problem is fixed!

Additional thoughts: Did an experiment with mdx where we could output more interesting stuff than just text, e.g. images/tables/math/etc. Similar problem, need to be able to associate the output with the input so when the output changes we know what to delete.

Solution: delimited custom tags :-)

{@ocaml[
let x = {
]}
@output{
{@mdx-error[
Line 2, characters 1-3:
Error: Syntax error
]}
}

  • outcome of discussion

Probably best to go with plan A - extend the code block with the output:

{delim@ocaml env=e1[ ...code... ]@delim@[ ...results... ]@}
  • Rafal worked on adding support for the [@@hidden] attribute
    PR: https://github.com/ocaml/odoc/pull/950
    What are the pro and cons of the attribute vs a new tag ? (for which Rafal made a PR to odoc-parser)
    @jonludlam to read through things and comment

Search

  • experimenting with json output

  • todo: sabine/paul-elliot to put quick-n-dirty identifier list into voodoo.

2023-03-23

Participants

@jonludlam
@panglesd
@lukemaurer

Source rendering

  • Merged! @jonludlam having a quick go at the voodoo side of things
  • Double check about resolving inter-module links, whether this will require changing the pipeline.

Tables rendering

  • Work going on in both odoc-parser and odoc.
  • latex support finished now, new package 'array' needed in preamble.
  • man page support, tables in tables unsupported!

Transparent ascription

  • progress to report?

Release questions

  • vendor odoc-parser? anything else??

2023-03-09

Participants

@jonludlam, @julow, @gpetiot, @lukemaurer, @panglesd

Source rendering

  • Review ongoing, some minor fixes here and there, and more explanation text in the driver
  • Merge soon!

Tables rendering

  • odoc-parser PR merged, odoc PR needs review now.
  • some question about what goes in the preable for latex - suggest to ping @octachron for his opinion.

Transparent ascription

  • @luke has hit issues with fragmap, @jonludlam needs to take a look

odoc-parser new syntax

  • @jonludlam to make an issue to talk about it

What's next?

  • 2.3 with source rendering and tables
  • 2.4 with uses-counting and …?

2023-02-09

Participants

@jonludlam @lukemaurer @panglesd @gpetiot

Source rendering

Issue with source parents:

  • parents are specified via include path and reference, e.g. -I foo --parent page-bar
  • source parents are also specified on the same invocation
  • Problem happens if the source parent and the module parent both have the same name

Question to answer: Why didn't we specify by filename in the first place?

Solutions:

  1. Specify source parent by filename. We'd probably also want to allow specifying the module parent by filename too for consistency.

Backup plan:

  1. Disambiguate the parents by finding the one with the currently module/source file as child.

2023-01-12

2022-12-15

  • don't ever release odoc-parser and odoc at different times
  • coming up: tables / images / code-block outputs
  • source rendering with links
  • identifier for ranked search
  • class expansion currently is wrong, eio will need this
    • lablgtk / js_of_ocaml / ppxlib are all impacted

Separate meeting:

  • more separate source treatment than in the current PR
  • closer to how merlin works
  • thoughts about pipeline:
    • possible separate first step to process cmt files?
    • don't try to force into current pipline/driver flow

2022-12-01

  • New release 2.2 almost there, 1 bug found last minute

  • Delayed working coming after 2.2

  • Transparent ascription work on hold until JS is on 4.14

  • source rendering

    • branch/pr created
    • figuring out how wrapped modules will work

2022-11-17

2022-11-03

Sabine

  • Been working on ocaml.org - got 1 PR out and ready to be merged, another waiting on that one. Possibly one more…? This is on the critical path for next release of odoc.

Dune integration

  • JonL been working on dune support for generating docs for all packages not just ones in your tree.

Jump to definition for docs

  • Julow to write some brief design docs for how things are going to work.

2022-10-20

2022-09-08

Progress

  • Limited progress over summer
  • Math PR merged!

New syntax / linear docs

There was some discussion on discuss: https://discuss.ocaml.org/t/outreachy-december-2022/10336

Which mentioned the math syntax PR. I'd like to follow up the math PR with some more missing syntax. What follows is a not-deeply-considered-yet starting point for discussion:

images

Possibilities:

  • {image foo.png}

Path to image taken to be the same as the parent page of the topmost module. Need alt text?

body of the image starts with [a-z]+: so it's treated as a URL (?)

  • {image "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUA
    AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO
    9TXL0Y4OHwAAAABJRU5ErkJggg=="}

tables

No idea about syntax yet

source 'results'

We have markup for source:

{@ocaml[ ]}

and a PR to ocaml-mdx to evaluate these. It might be nice to have a results section too:

{@ocaml[ print_endline "Hello, world" ]@result[ Hello, world! ]}

which mdx could then correct as necessary, or print error messages?

PR for source rendering

  • approach needs to be discussed, will have a discussion about this after ICFP.

Performance / memory usage:

2022-07-14

Progress since last time

  • Lots of PRs merged, including most of the optimisation PRs
  • odoc-parser 1.0.1/odoc 2.1.1 released with OCaml 5.0 support
  • odoc-parser 2.0.0 released with math support
  • math PR in progress

Other optimisations

  • alias chain shortcut - it should be possible to correctly skip to the end of a chain of aliases when finding expansions

  • Delayed improvements - needs more work

mdx support for mld files

Correcting documentation of internals

  • Started this work, PR to come.

Next meeting

Thursday September 8th?

2022-06-16

Attendees

Optimisations

Several PRs made, some reviewed and merged, some still under review, 1 more to come

  • The one to come: 'Delayed' improvements is the sticking point, will submit without that change.

Other PRs

  • handle comments on class constraint and inherit

    • waiting for big PRs to go in

  • v3 html

    • Need a minor edit then a solution to the json problem

  • math support

    • I'm all for it!

OCaml version support

  • dbuenzli has suggested dropping support for OCaml < 4.08
  • I'd prefer to do this once we've implemented the features we want for ocaml.org (ie, uses for search and source rendering)
  • thoughts?

Release

  • Release required for OCaml 5.0

2022-05-05

Attendees

Optimisations

  • tried to push through the Delayed changes

    • initially made it slower
    • doing the changes in all the obvious places got us back more-or-less to where we started

  • Backed out the hash-consing work

    • faster to do memoising checks in tools.ml
    • slower to build them
    • overall slower

  • Coalesced expand_tools.ml into tools.ml

    • currently being tested by Luke

Overall picture, a bit disappointing on all but the pathological cases.

2022-04-21

Attendees

Jane Street optimisations

  • @jonludlam spent a week at Jane Street looking at the problems they're facing
  • Discussed several optimisation opportunities with @lpw25 and @LukeMaurer
  • Trialed a few, with some good progress, work continued after the week was up

Specific changes:

  • BUG: hidden calculations weren't quite right
  • BUG: self canonical calculation not quite right (hidden by the hidden calculation bug!)
  • RENDERING: inline includes no longer wrapped in a div
  • BUG: includes of the form include sig ... end were handled by simply inlining the contents. This is incorrect in the presence of shadowed items.
  • OPTIMISATION: Remove map merges in conversions to/from Components
  • OPTIMISATION: Remove canonical constructor from resolved references (unused)
  • OPTIMISATION: Change the 'Cpath' canonical constructor so that it's always a global path
  • OPTIMISATION: New alias constructors that only have one side resolved, chosen according to a heuristic (very simple right now, slightly better one has been discussed)
  • OPTIMISATION: Hash-consing paths - useful for sharing, but also for memoisation
  • OPTIMISATION: Slightly better identifiers - can't quite do hash-consing but we can make it better than it currently is

The above has all been tested, there's currently still an issue with the include sig ... end fix, which I'd like to fix before making the PR.

Further (untested) optimisation in progress:

  • Better usage of the 'Delayed' type - currently even simple resolution ends up doing a lot of substitution which is ultimately unnecessary and thrown away. We've got the 'Delayed' type in there which is very basic and simply suspends the computation, but we can do better!

2022-03-24

Attendees

  • @jonludlam
  • @lubegasimon
  • @paul-elliot
  • @lpw25
  • @lukemaurer

Hacking week next week

  • @jonludlam working on making odoc work for Jane Street, expecting to make some PRs.

2022-03-10

Attendees

odoc 2.2

  • v3 html PR

    • contentious bit: adding yojson/sexplib dependency. Thoughts?

  • shadowing bugfix

    • random hack (literally!) - need a proper fix. Problem is down to clashes between shadowed identifiers. Needs some thought!

  • @julow's PR on class inherit and constraint

    • needs some review, but not much

  • @jonludlam to be working less on odoc

2022-02-24

Attendees

odoc 2.2

  • CI problems - cmdliner / dune / opam lint

  • Fix for overly aggressive optimisation

    • potential fix for JS's Not_found?

  • math odoc-parser PR given gentle prod, updated since

  • deprecated/alert tags PR merged

    • Uses raw text rather than a type, unlike ocamldoc PR

  • Improved layout for datatypes

  • markdown?

    • been on hold, need to start again
    • quite unusual markdown output, need to get feedback.

  • v3 - style output

  • deprecation of ocamldoc

    • no missing features in odoc we thing
    • check about index pages
    • big thing would be to make ocamldoc not rely on the typedtree
    • probably target ocaml 5.1

2022-02-10

Attendees

odoc 2.1

  • Released!

odoc 2.2

  • deprecated tags / thread safety tags
  • math support
  • markdown output

odoc 2.3?

  • Support including ml/mli files in the output
  • Generate ranked indexes for search

2022-01-27

Attendees

odoc 2.1 progress

Most items merged. Missing:

  • markdown backend
    • removed. work still required, then discussion about exact output format
  • canonical fix
    • going in real soon now
  • command-line tool for resolving references
  • class type path fixes

Expansion inlining via javascript

2022-01-13

Attendees

odoc 2.1 progress

  • Backtrace problem discovered by @lukemaurer while testing the module alias chains fix
    • Since been repro'd on 2.0.2 so not a new issue
    • @lukemaurer is working on a minimal repro (tricky, though!)
  • Progess on @canonical problems (@jonludlam) (https://github.com/ocaml/odoc/issues/724), PR soon
  • Suggestion: Merge outstanding bugfix PRs (plus the one above) and release 2.1 soon.
    • rationale: other items in the list are 'nice to have', and I'd like to see the improved layout released.
  • markdown backend now being led by @julow

Expansion inlining prototype work

  • @panglesd has done some prototyping work on the inlining of module expansions. He says:

I've been experimenting a little with support for inlining expansions in their parent page: https://github.com/ocaml/odoc/issues/564.

I have implemented an inlining supporting both the summary and the inlined expansion, via a foldable item: see here for a version of Base docs where everything is inlined. (The expansion page is kept even when inlined)

However, I'm a little bit concerned about giving the authors the ability to (foldably) inline without constraint: some will use it all the time, other will never use it, and that might confuse the reader.

I came up with the following idea (see here for the Base docs compiled with this solution):

  • Every expansion (of level 0) is inlined, up to a certain size (decided by odoc, not the author) (fixed to 400px in the example)
  • Expansions of level 1 (expansions inside expansions) are not inlined
  • Expansions that "overflow" the odoc-fixed size have a "+" indicating it, clicking it links to the expansion page
  • Authors can only decide if an expansion is open or closed by default.

Additional information:

  • Inlining everything: Base grows from 12Mo to 21Mo
  • Inlining first level expansions: Base grows from 12Mo to 18Mo. This can be reduced if we add only a shorter prefix of long expansions."

2021-12-16

odoc 2.1 progress

Inline modules proposal

Proposal from @panglesd:

"Do you think that having modules both:
in a dedicated page,
inlined in the parent page, with the inlining hidden by default, but "unfoldable" in a similar way include can be folded and unfolded.
This way, no links are broken (they always refer to the dedicated page), and the decision of how to read the doc is up to the reader.
The problem I see with that is that clicking on a link in the inlined module would link to the dedicated page."

  • don't want to break existing links
  • suggestion from @lukemaurer - put a redirect page where the module would be
  • punt this feature to 2.2 so discussion can continue

2021-12-02

Attendees

Release of odoc 2.0.1 / 2.0.2

  • 2.0.2 == 2.0.1 with OCaml 4.14 compatibility

odoc 2.1

Project here: https://github.com/ocaml/odoc/projects/5

Anything missing from this release? Support for language tags and mdx metadata in code blocks?

Tags for multicore safety - @octachron to find some examples

odoc 2.2

Project here: https://github.com/ocaml/odoc/projects/7

Main items:

  • –keep-code equivalent (with links)
  • Generation of metadata to support indexing/search

There is an 'odoc-dev' team whose membership is:

  • @avsm
  • @trefis
  • @jonludlam
  • @dbuenzli
  • @ryyppy (Patrick Ecker)
  • @lpw25
  • @aantron

and 'external contributors':

  • @julow
  • @lubegasimon
  • @ostera
  • @rizo

Notable, @drup is missing

2021-11-18

Attendees

Question: Should we autogenerate identifiers for sections without explicit anchors?

ie. {1 Heading} can be referenced by {!heading} - should this work? (vs {1:anchor Heading} and {!anchor})?

Question has arisen in the context of warning about linking to ambiguous labels.

2.0.1 release

Issues tracked here: https://github.com/ocaml/odoc/projects/6

2.1 release

Issues tracked here: https://github.com/ocaml/odoc/projects/5

Markdown backend

  • @lubega-simon and @Julow continuing to work on the PR

Formatting of long types/module types

  • @panglesd making good progress, preview posted.

2021-11-04

Attendees

References to outside of module types must be fully qualified

https://github.com/ocaml/odoc/issues/750

Issue is that when making an expansion, all references are resolved in the context of that expansion rather than the original definition site. Therefore all references to things outside of the expansion currently need to be fully qualified to ensure they point to the intended place. Example:

https://github.com/ocaml/ocaml/blob/45612f14afc1abaa19d8585ec1f48c3cbbfbc652/stdlib/map.mli#L242

Possible solutions:

  • Resolve references in expansions in the context of their original definition point (ie, fix the problem)

  • Require references resolved in expansions to be either resolved to a point within the expansion or to be fully qualified (ie, detect the problem)

  • Make references more like paths in the loader - resolve the identifier at the bottom of the reference.

  • also might have to resolve root modules later as well

2.0.1 release

Issues tracked here: https://github.com/ocaml/odoc/projects/6

2.1 release

Issues tracked here: https://github.com/ocaml/odoc/projects/5

Markdown backend

  • in progress, @lubegasimon and @Julow working on this mainly

Formatting fixes for long types/module types

  • in progress, @panglesd working on it

2021-10-21

Attendees

Release observations

Outreachy

  • no applicants yet!

Markdown backend

  • ongoing

Dune integration

  • started up again

2021-10-07

Attendees

Release status

2.0.0 released! Announcement made on discuss.ocaml.org

2.1 status

Project board made to track issues, started to populate it:

https://github.com/ocaml/odoc/projects/5

Intended to be a (much) smaller release (~3 months?)

Main features:

  • markdown renderer (@lubega-simon working through PR review comments right now)
  • inline expansions
  • better layout for long types/module types
  • bug fixes
  • responsiveness

Outreachy project

Outreachy project has been submitted, waiting for applicants now. Project text:

"Create a tool to show differences in the output of odoc.

Odoc is a documentation generator for OCaml code. It works by analysing the compilation artefacts of a library, extracting specially formatted documentation comments and producing output in a variety of formats, most commonly HTML.

The recent refresh of the OCaml website has included a goal of producing documentation for all versions of all packages, which has involved creating a CI pipeline that runs odoc on all packages it can compile. The output of this effort can be seen on the documentation tabs of the packages available on https://v3.ocaml.org/packages.

This project is to produce a tool to work on the output of this pipeline primarily to find differences between different versions of the same package. The tool will be built as a library with a command-line interface in the first instance. This will eventually be used to highlight differences between versions in the OCaml website, and thus a stretch goal is to begin the design and integration of this tool into the website."

2021-09-23

Attendees

Release status

Bugs fixed since last time:

Bugs

Markdown backend status

  • PR #723
    • Addressed PR reviews and suggestions
      • added --generate-links option to enable rendering of links in markdown. (links are disabled by default)
      • Removed confusing constructors, e.g Command, Env
      • improved module items indentation (Thanks Jules for the input)
      • end keyword was treated as not part of source code rather plain text, but it's now treated right, and indented right for submodules
      • text marked up as verbatim should now be rendered as expected.
      • Improved readability after spliting concerns between Markup and the rest of module content by making t abstract. (Thanks Jules for the suggestion)
      • ordered lists are now rendered as 1. rather that 1) because the former is a known convention. (Thanks Gabriel for the suggestion)
      • added a horizontal bar between headings and the following content to improve readablity. (thanks Jules for the suggestion)

Generally the markdown generator is still a work in progess. More things being/to be worked on, following their of priority are;

  • handling of labels
  • improving rendering
  • updating the docs to include the markdown generator
  • add options for rendering markdown in Github Flavoured markdown and pandoc

A more comprehensive demo of the current state is ocamlary.md

Thanks Gabriel and Jules for the review comments, more reviews and suggestions are much appreciated.

More suggestions:

  • use unicode character rather than &nbsp (by @lpw25).
  • anchor tags in markdown should be tied up to the --generate-links option (by @lpw25)
  • Treat doc comments in modules and records a little different from that outside (by @lubega-simon).

2021-09-09

Attendees

Release status

v3.ocaml.org

  • announced as part of OCaml Workshop talk

  • some bugs/lack of features noted, no showstoppers so far

    • reference default text for labels
    • lack of tables and images

Markdown backend

  • In progress! many challenges involving formatting, links, indentation, etc
  • targetting PanDoc and github renderers
    • request from @lpw25: check emacs's markdown renderer
  • Add option for enabling and disabling links in rendered markdown (request from @lpw25)

2021-07-29

Attendees

package docs status update

  • Complete build now working
  • Talk planned for OCaml workshop

2.0 release state

  • Realised we need quite a lot of docs for the release
    • Involving our new technical authors with this process
    • Good for the longer term
  • at least 1 bug still to fix - TOC linking broken

Post 2.0 Roadmap

Roadmap wiki page: https://github.com/ocaml/odoc/wiki/Roadmap

Aim to have smaller, more frequent releases

Please feel free to suggest new items for the roadmap

New item for roadmap: 'query tool' - possibly more than one new CLI tool to query odocl files, resolve references on the command line, print docs for specified items, etc

Next meeting

Thursday 9th September

2021-07-15

2.0 issues

New issues

  • TBD - alias chain memory size issue

Merged PRs

  • #460 (reference driver needed) - in progress - @lubega-simon (previously @jonludlam) and #573 (docs are bad)

    • Merged!
    • Further improvements to docs now sought!
    • Would be nice to automate publishing them

  • #685 (odoc-parser package

  • #692 (Aggregate "root" lookup failures) - addresses #635 (odoc too noisy on partial docsets) - merged

  • #693 (Fix shadowing of values and externals) - more reduction in noise! extends fix for shadowing (#648) - merged

  • #698 (Improvements to help tests) - to help out with the improved test infrastructure @lubegasimon is working on. - merged

  • #650 (Need ModuleType 'aliases') - merge PR #703

Other issues

Post 2.0 work

Planning meeting next time?

For general discussion today:

vs

  • #565 - Long module types and types need better line breaks

    • includes make consistent style difficult
    • rewriting paths might change line lengths
    • indentation would need to change
    • best to do consistent style ourselves
    • need to do it for ml files anyway
    • makes a minimum width requirement

  • Tracking of uses / rendering source code with links #567 / #566

  • Inlining expansions #564

Meetings over summer

2021-07-01

Attendees

@jonludlam
@Drup
@octachron
@lubega-simon

2.0 issues

New issues

  • TBD - alias chain memory size issue

Merged PRs

  • #687 - OCaml 4.13 support

  • #689 - "with module type" constraints support

Open PRs

  • #651 (Improve tests for generators (html, man, and latex)) - @lubega-simon – PR open #665

    • concerns raised about the complexity of the approach, @lubega-simon working on an alternative

  • #460 (reference driver needed) - in progress - @lubega-simon (previously @jonludlam) and #573 (docs are bad)

  • #685 (odoc-parser package

    • Approach changed. Will put odoc-parser into a separate repo (for now at least) - stems from continued difficulties with testing. Proposal: github.com/ocaml-doc/odoc-parser

  • #692 (Aggregate "root" lookup failures) - addresses #635 (odoc too noisy on partial docsets)

  • #693 (Fix shadowing of values and externals) - more reduction in noise! extends fix for shadowing (#648)

  • #698 (Improvements to help tests) - to help out with the improved test infrastructure @lubegasimon is working on.

Other issues

  • #664 - Failures when resolving references are not reported - @julow assigned (part of #557)

  • #650 (Need ModuleType 'aliases') - @jonludlam

2021-06-17

Attendees

@jonludlam
@lpw25
@octachron
@lubega-simon
@julow

2.0 issues

New issues

  • #686 (Odoc does not build with 4.13)
    • @Octachron has been working on a fix for master

Merged

  • #557 (Command to extract errors from odocl files) - @julow (previously @jonludlam)

  • #648 (Warnings about ambiguous references are bogus) - PR

  • #601 (Type extensions are no anchorable and should be classified as type) - @julow - PR

    • Note that we still don't have syntax for refering to these in the doc comments. I propose not to address this for 2.0.0

Open PRs

  • #651 (Improve tests for generators (html, man, and latex)) - @lubega-simon – PR open #665

    • concerns raised about the complexity of the approach, @lubega-simon working on an alternative

  • #460 (reference driver needed) - in progress - @lubega-simon (previously @jonludlam) and #573 (docs are bad)

  • #685 (odoc-parser package) - Review comments being addressed.

Other issues

  • #664 - Failures when resolving references are not reported - @julow assigned (part of #557)

  • #650 (Need ModuleType 'aliases') - @jonludlam

  • #635 (odoc too noisy on partial docsets) - @Julow working on it.

Large odoc files

  • Issue being investigated - large size of odoc files when there are long chains of aliases.

Names are hard

  • What is the name of the markup language we use?

odoc markup!™ (roughly a superset of ocamldoc markup)

2021-06-03

Attendees

@jonludlam
@lpw25
@lubega-simon
@julow

2.0 issues

Merged

  • #562 - Remove Stdlib prefix – PR open #677

Open PRs

  • #651 (Improve tests for generators (html, man, and latex)) - @lubega-simon – PR open #665

    • concerns raised about the complexity of the approach, @lubega-simon working on
      an alternative

  • #557 (Command to extract errors from odocl files) - @julow (previously @jonludlam)

    • More review required from @jonludlam

  • #648 (Warnings about ambiguous references are bogus) - PR

    • test failure fallout to be investigated

  • #460 (reference driver needed) - in progress - @lubega-simon (previously @jonludlam) and #573 (docs are bad)

Other issues

  • #664 - Failures when resolving references are not reported - @julow assigned (part of #557)

  • #650 (Need ModuleType 'aliases') - @jonludlam

  • #601 (Type extensions are no anchorable and should be classified as type) - @julow

  • #635 (odoc too noisy on partial docsets) - unassigned

octavius2^Wodoc-parser

Parser library will now be exposed as 'odoc-parser' after discussions with Anton.

Idea: new dune rule to dump errors into a file

2021-05-20

Attendees

@jonludlam
@lubega-simon
@lpw25

2.0 issues

Merged

  • #658 - Resolve some references in synopses in {!modules} lists – PR merged #662

  • #659 (Resolution bug for sections) – PR merged #676

Open PRs

  • #562 - Remove Stdlib prefix – PR open #677

  • #651 (Improve tests for generators (html, man, and latex)) - @lubega-simon – PR open #665

  • #557 (Command to extract errors from odocl files) - @julow (previously @jonludlam)

Other issues

  • #664 - Failures when resolving references are not reported - @julow assigned (part of #557)

  • #650 (Need ModuleType 'aliases') - @jonludlam

  • #648 (Warnings about ambiguous references are bogus) - @julow

  • #460 (reference driver needed) - in progress - @lubega-simon (previously @jonludlam)

  • #573 (docs are bad) - in progress - @lubega-simon (previously @jonludlam)

  • #601 (Type extensions are no anchorable and should be classified as type) - @julow

Octavius 2

PR open, includes patch to allow metadata in code blocks:

(**

{@ocaml env=f1 version>=4.06 [
(* code goes here *)
]}

*)

The PR disables all ppx_expect tests, as ppx_js_style depends upon octavius.

It would be useful to release this soon, would allow ppx_js_style to be fixed and get our tests back.

Put it into octavius.git?

Conclusion: Jon to decide

Handling of scopes

type t
module M : sig
  val x : t
  (** {!t} *)
  type t
  (** {!t} *)
  val y : t
end

We are allowed to have forward references, so both references above ought to point at M.t, whereas x and y point at different types.

If we want to allow open to allow shortening of paths (like for the Stdlib PR above), it will apply to the paths before the open.

e.g:

val v : X.t

open X

val w : t

the RHS of val v, w cannot be distinguished from the cmti (AFAIK), and the way the shortening
works currently will cause the RHS of both v and w to be rendered as t

Desirable?

Decision: We want to handle opens for 2.0

what about:






open X (* including a type t *)
type t

(** {!t} <- what does this resolve to?  *)

maybe have a separate environment with the 'opened' modules in - search the normal one first, then the extended one

Outreachy

No intern this time around for odoc - 2 working on the website though.

For odoc, the candidate who showed most 'ocaml' promise (unintentionally!) did not apply. The applicants that did, through no fault of their own, had not done a lot of OCaml work in the initial contribution period. The reason was that we directed all candidates at the ocaml.org project for initial contributions as they were well set up with beginner instructions and there were more 'starter' issues.

Lessons learned. Next round starts in September/October.

2021-05-06

Attendees

@jonludlam
@lubega-simon
@avsm
@lpw25
@julow

2.0 issues

New issues (for 2.0)

  • #562 - Remove Stdlib prefix

Current we often produce docs like this:

val ok : 'a -> ('a, 'e) Stdlib.result

let's get rid of the Stdlib here - possibly via an 'initially opened module' on the link (for references), and by fixing the canonical handling.

Open PRs

  • #658 - Resolve some references in synopses in {!modules} lists – PR open #662

  • #651 (Improve tests for generators (html, man, and latex)) - @lubega-simon – PR open #665

  • #557 (Command to extract errors from odocl files) - @julow (previously @jonludlam)

Other issues

  • #664 - Failures when resolving references are not reported - @julow assigned (part of #557)

  • #659 (Resolution bug for sections) – assigned to @julow

  • #650 (Need ModuleType 'aliases') - @jonludlam

  • #648 (Warnings about ambiguous references are bogus) - @julow

  • #460 (reference driver needed) - in progress - @lubega-simon (previously @jonludlam)

  • #573 (docs are bad) - in progress, on hold - @lubega-simon (previously @jonludlam)

  • #601 (Type extensions are no anchorable and should be classified as type) - @julow

Discussion on documentation in general

https://discuss.ocaml.org/t/diataxis-documentation-structure/7750/22

ACTION: @jonludlam to reply to the thread

Outreachy

  • 6 applicants for the "Add a markdown backend to odoc" project
  • Decision to be made soon, with help from @patricoferris and @pitag-ha
  • Internship runs from May 24th - Aug 24th
  • @jonludlam and @Drup mentoring

docs.ocaml.org progress

Current state: http://193.193.115.46:8000/packages/

2021-04-22

Attendees

@jonludlam
@julow
@lpw25
@lukemaurer
@Drup
@lubega-simon

2.0 issues

New issues:

  • #664 - Failures when resolving references are not reported - @julow assigned (part of #557)

  • #666 - Initial stop comment hinders output - Proposal: not for 2.0

In progress:

  • #658 - Don't resolve references in synopses in {!modules} lists – PR open #662

  • #659 (Resolution bug for sections) – assigned to @julow

  • #650 (Need ModuleType 'aliases') - @jonludlam

  • #648 (Warnings about ambiguous references are bogus) - @julow

  • #651 (Improve tests for generators (html, man, and latex)) - @lubega-simon – PR open #665

  • #460 (reference driver needed) - in progress - @lubega-simon (previously @jonludlam)

  • #573 (docs are bad) - in progress, on hold - @lubega-simon (previously @jonludlam)

  • #557 (Command to extract errors from odocl files) - @julow (previously @jonludlam)

  • #601 (Type extensions are no anchorable and should be classified as type) - @julow

Fixed since last time

  • #632 (No synopsis rendered for modules) - partial fix merged, new fix incoming - @julow

  • #478 (Top-level doc-comments of module types are discarded)

Last changed by 
 
OCaml
The OCaml open source ecosystem
0
1575

Read more

OCaml Platform Newsletter - June 2024

WIP INTERNAL TO OCAML PLATFORM TEAM - DO NOT SHARE

Jul 16, 2024
OCaml Platform Newsletter: March-May 2024

WIP INTERNAL TO OCAML PLATFORM TEAM - DO NOT SHARE

Jun 6, 2024
OCaml Platform Newsletter: February 2024

WIP INTERNAL TO OCAML PLATFORM TEAM - DO NOT SHARE

Mar 26, 2024
OCaml Platform Newsletter: January 2024

WIP INTERNAL TO OCAML PLATFORM TEAM - DO NOT SHARE

Feb 27, 2024
Read more from OCaml
Published on HackMD