owned this note
owned this note
Published
Linked with GitHub
---
tags: minutes
---
# odoc Dev Meetings
# 2024-10-30
## Participants
- @jonludlam
- @panglesd
- @gpetiot
- @julow
- @faycarsons
## What's been going on?
- Prototype of different hierarchy published
- Source needs some cleanup before PR is made https://github.com/panglesd/odoc/tree/dbuenzli
- 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
- @jonludlam
## What's been going on
- Lots of discussion with Daniel!
- Sidebar
- Doc layout (/doc -> / and /lib/libname -> /libname)
- sidebar.json branch (https://github.com/panglesd/odoc/tree/json-sidebar-output)
- Separating comple/link phases in docs-ci
- opam metadata for extra deps
- example:
```
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
- @jonludlam
- @panglesd
- @emile
- @faycarsons
- @lukemaurer
- @julow
## 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
- @jonludlam
- @panglesd
- @emile
- @lukemaurer
- @faycarsons
- @julow
## 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:
- (is this necessary?) Handling of optional args bug (https://github.com/ocaml/odoc/issues/1001)?
- Tag styling (https://github.com/ocaml/odoc/issues/1198)
- Solver issue for vpnkit
- Any other minor bugs?
- Search isn't working in voodoo mode
# 2024-09-25
## Participants
- @jonludlam
- @emile
- @panglesd
- @julow
- @xVIgSu9rREWaUrm7A6vRsA (Sabine)
- @FayCarsons
## 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
```exn_bt
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
- @jonludlam
- @FayCarsons
- @LukeMaurer
## 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
- @jonludlam
- @faycarsons
- @panglesd
- @xVIgSu9rREWaUrm7A6vRsA (sabine)
- @lukemaurer
## 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
- New parser mly
- Moved tokens
- New tokens being used
- Compiling
- https://github.com/FayCarsons/odoc/tree/menhir-parser
# 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:
- Reviewed and merged loader fix by Octachron: https://github.com/ocaml/odoc/pull/1173
- Refactoring on Names and Idents https://github.com/ocaml/odoc/pull/1174
# 2024-07-24
## Participants
- @julow
- @paul-elliot
## What's been happening?
Odoc 3:
- Continue working on the driver to use different inputs - will be useful for mini jane, also for replacing large parts voodoo. PR has been opened and review is in progress.
https://github.com/ocaml/odoc/pull/1168
- Merged resolution of module references.
https://github.com/ocaml/odoc/pull/1164
- Continue work on Adding external pages (ie, non-package pages including landing pages and hierarchy pages)
- "Asset compilation" PR has been opened as well as "Asset referencing" on top of it
https://github.com/ocaml/odoc/pull/1170 and https://github.com/ocaml/odoc/pull/1171
General work:
- Opened issue on Windows support https://github.com/ocaml/odoc/issues/1169
# 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:
- spent a little time on https://github.com/ocaml/odoc/issues/1162
- CSS tweaking https://github.com/ocaml/odoc/pull/1159
- Sherlodoc work including different links to sources
# 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](https://github.com/ocaml/odoc/pull/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
## Sidebar demo!
# 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:
```ocaml=
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.:
```ocaml=
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
## Sidebar
- 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
- @jonludlam
- @julow
- @sabine
- @lukemaurer
## Odoc 3.0 work
### Assets again
- Figures vs images
https://hackmd.io/08MIstgdRWOLVlLFFJJEvQ
- Agreed on slightly lighter syntax
- Images/Videos/Audio always block elements
- Remove the 'href' bit
### 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
- @jonludlam
- @panglesd
- @julow
- @sabine
- @emile
- @trefis
- @lukemaurer
## 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
- @jonludlam
- @panglesd
- @trefis
- @lukemaurer
## 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:
- [Sidebar tree construction](https://hackmd.io/_ioOmRBdST2p6gHSuGIA-A) (inline `{!toc ... }` directives in index.mld)
- [Short page titles](https://hackmd.io/_ioOmRBdST2p6gHSuGIA-A) (`{{0 Short title}Longer title can go here}`)
- [Scope of references](https://hackmd.io/P_ZUw1bJQ0mN6x4Pwbzw1w#References-in-pages) in mld pages is filesystem based
## Unresolved questions:
- Should we parse `md`/`mdx` files? See [Daniel's PR](https://github.com/ocaml-doc/odoc-parser/pull/15/files)
- [Syntax of relative references to pages](https://hackmd.io/P_ZUw1bJQ0mN6x4Pwbzw1w#OPTION-1)
- [URL structure / breadcrumbs](https://hackmd.io/67gwMKAeTe-0pCNZkrbMQg)
# 2024-02-16
## Participants
- @jonludlam
- @panglesd
- @lukemaurer
- @julow
## 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
- Extended code-blocks? https://jon.ludl.am/experiments/learno/
- Live odoc playground? https://jon.ludl.am/experiments/odoc-live/
- REST API as an odoc backend?
- Better lsp-odoc integration
# 2024-01-18
## Participants
- @jonludlam
- @panglesd
- @trefis
- @julow
## 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
- @jonludlam
- @lukemaurer
## 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
- @jonludlam
- @panglesd
- @julow
- @emile
## Odoc 2.4 release
- Search!
- Needed for sherlodoc release
- Got changes required for dune rules - contingent on having sherlodoc installed (so no version check required)
- https://github.com/emileTrotignon/dune/tree/search-odoc-new
- Some changes required
- PRs still needed:
- Ocamlformat https://github.com/ocaml/odoc/pull/997
- Module type of test
## 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
- @jonludlam
## New releases
- Odoc 2.3.1 / Odoc 2.2.2
- Fixed OCaml 5.1 compatibility
## `module type of` fixes progress
- Luke came to Cambridge and we discussed the problem, and came up with a new solution
- https://github.com/lukemaurer/odoc/tree/original-path
## 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
- @jonludlam
- @panglesd
- @trefis
- @lukemaurer
- @julow
## Odoc 2.3 status
- Released!
- Bugs :-(
## PRs in progress
[Handle differences in sig_class for OCaml 5.1. (to master branch)](https://github.com/ocaml/odoc/pull/1027)
- bugfix from 2.2 branch
- need to cherry pick another commit
[change color to gruvbox theme](https://github.com/ocaml/odoc/pull/1023)
- keep the newly organised colour definitions
- drop the actual colours
[Micro-optimize Ident.compare](https://github.com/ocaml/odoc/pull/1015)
- Should just be merged
[Doc: parent-child convention for installed packages](https://github.com/ocaml/odoc/pull/1011)
- Just doc what we've got, note the problems with it, not try to design v2 yet.
[Medias in odoc](https://github.com/ocaml/odoc/pull/1005)
- alt-text and unresolved image/placeholders need to be decided
[Asset references](https://github.com/ocaml/odoc/pull/1002)
- 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](https://github.com/ocaml/odoc/pull/999)
- Jules to have another look
[Collect occurrences information](https://github.com/ocaml/odoc/pull/976)
- 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](https://github.com/ocaml/odoc/pull/972)
- Ready re-review (jon)
[HTML: Match rendering of polymorphic variant with normal variants](https://github.com/ocaml/odoc/pull/971)
- to be reviewed/rebased and merged
[Humanist font fallbacks](https://github.com/ocaml/odoc/pull/968)
- Jules to close this in favour of another to remove the existing fallbacks
[Preformatted elements fallback to UA monospace](https://github.com/ocaml/odoc/pull/967)
- Jules to follow up
-
[Include missing preformatted text elements](https://github.com/ocaml/odoc/pull/966)
- Closed
[Remove expansion from "unexpanded" module type of](https://github.com/ocaml/odoc/pull/958)
[Add hidden attribute](https://github.com/ocaml/odoc/pull/950)
- go back to leo's comment about why - and explain why!
[Fix references to extension declarations](https://github.com/ocaml/odoc/pull/949)
- quick review pass then merge
[Fix rendering of references to label](https://github.com/ocaml/odoc/pull/943)
- quick review pass then merge
[Allow to omit parent type in constructor reference](https://github.com/ocaml/odoc/pull/933)
- quick review pass then merge
## Luke's visit to Cambridge
# 2023-07-13
## Participants
- @jonludlam
- @julow
- @panglesd
# 2023-07-06
## participants
- @jonludlam
- @julow
## 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
## Search
Discussed the difficulty of searching within module aliases, as these are not expanded by odoc
- can probably be just a 'symlink'
- https://hackmd.io/@gSSGgqf6RPWy0xRFrAb9Yw/BkgrQISXh
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:
2. `{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:
2. 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?
- {image http://example.org/foo.png}
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:
- Delayed branch: https://github.com/ocaml/odoc/compare/master...jonludlam:odoc:wip-memory2
- Next test probably should be an LRU cache of top-level modules, and to avoid memoising of lookups of top-level modules.
# 2022-07-14
- @jonludlam
- @lukemaurer
## 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
- PR created: https://github.com/realworldocaml/mdx/pull/377
## Correcting documentation of internals
- Started this work, PR to come.
## Next meeting
Thursday September 8th?
# 2022-06-16
## Attendees
- @jonludlam
## 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
- @jonludlam
- @julow
- @lukemaurer
- @lpw25
- @octachron
## 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
- @jonludlam
- @panglesd
- @julow
- @lpw25
- @LukeMaurer
## 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
- @jonludlam
- @lubegasimon
- @julow
- @octachron
- @lukemaurer
- @Drup
### 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
- @jonludlam
- @lubegasimon
- @julow
- @Drup
## 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
- @jonludlam
- @lubegasimon
- @julow
- @lukemaurer
- @panglesd
## 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
- demo: https://choum.net/panglesd/inline-test/with-js/base/Base/index.html
# 2022-01-13
## Attendees
- @jonludlam
- @lukemaurer
- @panglesd
- @Drup
## 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
- @jonludlam
## odoc 2.1 progress
- Long signatures landed (@panglesd) (https://github.com/ocaml/odoc/pull/782)
- Module alias chains fix (@jonludlam) (https://github.com/ocaml/odoc/issues/710)
- NEW Critical bug with inline substitutions PR'd (@jonludlam) (https://github.com/ocaml/odoc/pull/796)
- Code metadata update in odoc-parser, 1.0.0 release (@julow)
- Empty includes now hidden (@panglesd) (https://github.com/ocaml/odoc/pull/798)
- Comments on `open` now rendered (as floating comments) (@panglesd) (https://github.com/ocaml/odoc/pull/797)
## 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
- @jonludlam
## 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
## Team membership & related issues
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
- @jonludlam
- @lpw25
- @lubega-simon
- @julow
- @drup
- @lukemaurer
- @panglesd
## 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
- @jonludlam
- @lubega-simon
- @lpw25
- @julow
- @drup
- @panglesd
## 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
- @jonludlam
- @lubega-simon
- @paul-elliot
- @julow
## Release observations
- bugs found, 2.0.1 to be released when they're fixed
* (fix is ready for review) [Untyped reference to page doesn't resolve](https://github.com/ocaml/odoc/issues/752)
* [Reference syntax for operators is too restricted](https://github.com/ocaml/odoc/issues/749)
* [Reference to label in preamble are broken](https://github.com/ocaml/odoc/issues/746)
* (no issue for this one, fix is read for review) bogus warning on some labels
- need to avoid merging anything but bugfixes for a bit, to avoid having to branch
- need to have an index.mld file of some sort!
## Outreachy
- no applicants yet!
## Markdown backend
- ongoing
## Dune integration
- started up again
# 2021-10-07
## Attendees
- @jonludlam
- @drup
- @julow
- @lubega-simon
## 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
- @jonludlam
- @lubega-simon
- @lpw25
- @Drup
- @julow
## Release status
### Bugs fixed since last time:
- [Reference resolution failure unreported](https://github.com/ocaml/odoc/issues/664) PR: [#717](https://github.com/ocaml/odoc/pull/717)
As a consequence of this I fixed many problems.
Also noticed some issues:
+ {!modules: ... } can it contain module types? ocamlary suggests so.
+ Answer from meeting: Let's not allow module types for now.
+ Links to labels in signatures not working (https://github.com/ocaml/odoc/blob/master/src/ocamlary/ocamlary.mli#L176)
### Bugs
- (still!) 3 bugs to fix
- [ToC links broken](https://github.com/ocaml/odoc/issues/701) PR: [#720](https://github.com/ocaml/odoc/pull/720)
- [Docs are bad](https://github.com/ocaml/odoc/issues/573)
- PR open for feedback, though from current feedback I think it won't take long before it's mergable.
- Now have enough to point people at for the release.
- Several more bugs discovered!
- [References in module preambles aren't resolved correctly](https://github.com/ocaml/odoc/issues/713) - @dbuenzli requested this for 2.0.0
## Markdown backend status
+ [PR #723](https://github.com/ocaml/odoc/pull/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](https://github.com/ocaml/odoc/blob/add-markdown-generator/test/generators/markdown/Ocamlary.md)
*Thanks Gabriel and Jules for the review comments, more reviews and suggestions are much appreciated.*
More suggestions:
- use unicode character rather than ` ` (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
- @julow
- @jonludlam
- @lpw25
- @lubega-simon
## Release status
- 3 bugs to fix
- [ToC links broken](https://github.com/ocaml/odoc/issues/701) PR: [#720](https://github.com/ocaml/odoc/pull/720)
- [Reference resolution failure unreported](https://github.com/ocaml/odoc/issues/664) PR: [#717](https://github.com/ocaml/odoc/pull/717)
- [Docs are bad](https://github.com/ocaml/odoc/issues/573)
- working on enough to be able to write a blog post on the release
- mostly example of the new features
- preview: https://jonludlam.github.io/odoc/features.html
- several bugs discovered!
## [v3.ocaml.org](https://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
- @jonludlam
- @lubega-simon
## 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](https://github.com/ocaml/odoc/issues/460) (reference driver needed) - in progress - @lubega-simon (previously @jonludlam) and [#573](https://github.com/ocaml/odoc/issues/573) (docs are bad)
+ Merged!
+ Further improvements to docs now sought!
+ Would be nice to automate publishing them
- [#685](https://github.com/ocaml/odoc/pull/685) (odoc-parser package
+ Approach changed. Created github.com/ocaml-doc/odoc-parser and merged [#700](https://github.com/ocaml/odoc/pull/700)
- [#692](https://github.com/ocaml/odoc/pull/692) (Aggregate "root" lookup failures) - addresses [#635](https://github.com/ocaml/odoc/issues/635) (odoc too noisy on partial docsets) - merged
- [#693](https://github.com/ocaml/odoc/pull/693) (Fix shadowing of values and externals) - more reduction in noise! extends fix for shadowing ([#648](https://github.com/ocaml/odoc/issues/648)) - merged
- [#698](https://github.com/ocaml/odoc/pull/698) (Improvements to help tests) - to help out with the improved test infrastructure @lubegasimon is working on. - merged
- [#650](https://github.com/ocaml/odoc/issues/650) (Need ModuleType 'aliases') - merge PR [#703](https://github.com/ocaml/odoc/pull/703)
### Other issues
- [#664](https://github.com/ocaml/odoc/issues/664) - Failures when resolving references are not reported - @julow assigned (part of #557)
- [#701 - Wrong link in table of contents due to duplicate generated name](https://github.com/ocaml/odoc/issues/701)
+ for discussion
+ Generate warning only when trying to link to an ambiguous label
+ Make the ToC work somehow
- [#694 Inclusion of Google Fonts by default might create a legal hazard due to GDPR](https://github.com/ocaml/odoc/issues/694)
+ for discussion
## Post 2.0 work
Planning meeting next time?
For general discussion today:
- [#680 - Preserve code layout in .mli files](https://github.com/ocaml/odoc/issues/680) - suggestion from @aantron
vs
- [#565 - Long module types and types need better line breaks](https://github.com/ocaml/odoc/issues/565)
- 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](https://github.com/ocaml/odoc/issues/567) / [#566](https://github.com/ocaml/odoc/issues/566)
- Inlining expansions [#564](https://github.com/ocaml/odoc/issues/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](https://github.com/ocaml/odoc/pull/687) - OCaml 4.13 support
- [#689](https://github.com/ocaml/odoc/pull/689) - "with module type" constraints support
### Open PRs
- [#651](https://github.com/ocaml/odoc/issues/651) (Improve tests for generators (html, man, and latex)) - @lubega-simon -- PR open [#665](https://github.com/ocaml/odoc/issues/665)
+ concerns raised about the complexity of the approach, @lubega-simon working on an alternative
- [#460](https://github.com/ocaml/odoc/issues/460) (reference driver needed) - in progress - @lubega-simon (previously @jonludlam) and [#573](https://github.com/ocaml/odoc/issues/573) (docs are bad)
+ [Draft PR published](https://github.com/ocaml/odoc/pull/683) - changes requested
- [#685](https://github.com/ocaml/odoc/pull/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](https://github.com/ocaml/odoc/pull/692) (Aggregate "root" lookup failures) - addresses [#635](https://github.com/ocaml/odoc/issues/635) (odoc too noisy on partial docsets)
- [#693](https://github.com/ocaml/odoc/pull/693) (Fix shadowing of values and externals) - more reduction in noise! extends fix for shadowing ([#648](https://github.com/ocaml/odoc/issues/648))
- [#698](https://github.com/ocaml/odoc/pull/698) (Improvements to help tests) - to help out with the improved test infrastructure @lubegasimon is working on.
### Other issues
- [#664](https://github.com/ocaml/odoc/issues/664) - Failures when resolving references are not reported - @julow assigned (part of #557)
- [#650](https://github.com/ocaml/odoc/issues/650) (Need ModuleType 'aliases') - @jonludlam
# 2021-06-17
## Attendees
@jonludlam
@lpw25
@octachron
@lubega-simon
@julow
## 2.0 issues
### New issues
- [#686](https://github.com/ocaml/odoc/issues/686) (Odoc does not build with 4.13)
+ @Octachron has been working on a fix for master
### Merged
- [#557](https://github.com/ocaml/odoc/issues/557) (Command to extract errors from odocl files) - @julow (previously @jonludlam)
- [#648](https://github.com/ocaml/odoc/issues/648) (Warnings about ambiguous references are bogus) - [PR](https://github.com/ocaml/odoc/pull/682)
- [#601](https://github.com/ocaml/odoc/issues/601) (Type extensions are no anchorable and should be classified as type) - @julow - [PR](https://github.com/odoc/pull/684)
+ 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](https://github.com/ocaml/odoc/issues/651) (Improve tests for generators (html, man, and latex)) - @lubega-simon -- PR open [#665](https://github.com/ocaml/odoc/issues/665)
+ concerns raised about the complexity of the approach, @lubega-simon working on an alternative
- [#460](https://github.com/ocaml/odoc/issues/460) (reference driver needed) - in progress - @lubega-simon (previously @jonludlam) and [#573](https://github.com/ocaml/odoc/issues/573) (docs are bad)
+ [Draft PR published](https://github.com/ocaml/odoc/pull/683) - changes requested
- [#685](https://github.com/ocaml/odoc/pull/685) (odoc-parser package) - Review comments being addressed.
### Other issues
- [#664](https://github.com/ocaml/odoc/issues/664) - Failures when resolving references are not reported - @julow assigned (part of #557)
- [#650](https://github.com/ocaml/odoc/issues/650) (Need ModuleType 'aliases') - @jonludlam
- [#635](https://github.com/ocaml/odoc/issues/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!(tm) (roughly a superset of ocamldoc markup)
# 2021-06-03
## Attendees
@jonludlam
@lpw25
@lubega-simon
@julow
## 2.0 issues
## Merged
- [#562](https://github.com/ocaml/odoc/issues/562) - Remove Stdlib prefix -- PR open [#677](https://github.com/ocaml/odoc/pull/677)
## Open PRs
- [#651](https://github.com/ocaml/odoc/issues/651) (Improve tests for generators (html, man, and latex)) - @lubega-simon -- PR open [#665](https://github.com/ocaml/odoc/issues/665)
+ concerns raised about the complexity of the approach, @lubega-simon working on
an alternative
- [#557](https://github.com/ocaml/odoc/issues/557) (Command to extract errors from odocl files) - @julow (previously @jonludlam)
+ More review required from @jonludlam
- [#648](https://github.com/ocaml/odoc/issues/648) (Warnings about ambiguous references are bogus) - [PR](https://github.com/ocaml/odoc/pull/682)
+ test failure fallout to be investigated
- [#460](https://github.com/ocaml/odoc/issues/460) (reference driver needed) - in progress - @lubega-simon (previously @jonludlam) and [#573](https://github.com/ocaml/odoc/issues/573) (docs are bad)
+ [Draft PR published](https://github.com/ocaml/odoc/pull/683) - @jonludlam to review
## Other issues
- [#664](https://github.com/ocaml/odoc/issues/664) - Failures when resolving references are not reported - @julow assigned (part of #557)
- [#650](https://github.com/ocaml/odoc/issues/650) (Need ModuleType 'aliases') - @jonludlam
- [#601](https://github.com/ocaml/odoc/issues/601) (Type extensions are no anchorable and should be classified as type) - @julow
- [#635](https://github.com/ocaml/odoc/issues/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](https://github.com/ocaml/odoc/pull/658) - Resolve some references in synopses in {!modules} lists -- PR merged [#662](https://github.com/ocaml/odoc/pull/662)
- [#659](https://github.com/ocaml/odoc/issues/659) (Resolution bug for sections) -- PR merged [#676](https://github.com/ocaml/odoc/pull/676)
## Open PRs
- [#562](https://github.com/ocaml/odoc/issues/562) - Remove Stdlib prefix -- PR open [#677](https://github.com/ocaml/odoc/pull/677)
- [#651](https://github.com/ocaml/odoc/issues/651) (Improve tests for generators (html, man, and latex)) - @lubega-simon -- PR open [#665](https://github.com/ocaml/odoc/issues/665)
- [#557](https://github.com/ocaml/odoc/issues/557) (Command to extract errors from odocl files) - @julow (previously @jonludlam)
# Other issues
- [#664](https://github.com/ocaml/odoc/issues/664) - Failures when resolving references are not reported - @julow assigned (part of #557)
- [#650](https://github.com/ocaml/odoc/issues/650) (Need ModuleType 'aliases') - @jonludlam
- [#648](https://github.com/ocaml/odoc/issues/648) (Warnings about ambiguous references are bogus) - @julow
- [#460](https://github.com/ocaml/odoc/issues/460) (reference driver needed) - in progress - @lubega-simon (previously @jonludlam)
- [#573](https://github.com/ocaml/odoc/issues/573) (docs are bad) - in progress - @lubega-simon (previously @jonludlam)
- [#601](https://github.com/ocaml/odoc/issues/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
(**
{@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:
```ocaml=
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](https://github.com/ocaml/odoc/issues/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](https://github.com/ocaml/odoc/pull/658) - Resolve some references in synopses in {!modules} lists -- PR open [#662](https://github.com/ocaml/odoc/pull/662)
- [#651](https://github.com/ocaml/odoc/issues/651) (Improve tests for generators (html, man, and latex)) - @lubega-simon -- PR open [#665](https://github.com/ocaml/odoc/issues/665)
- [#557](https://github.com/ocaml/odoc/issues/557) (Command to extract errors from odocl files) - @julow (previously @jonludlam)
# Other issues
- [#664](https://github.com/ocaml/odoc/issues/664) - Failures when resolving references are not reported - @julow assigned (part of #557)
- [#659](https://github.com/ocaml/odoc/issues/659) (Resolution bug for sections) -- assigned to @julow
- [#650](https://github.com/ocaml/odoc/issues/650) (Need ModuleType 'aliases') - @jonludlam
- [#648](https://github.com/ocaml/odoc/issues/648) (Warnings about ambiguous references are bogus) - @julow
- [#460](https://github.com/ocaml/odoc/issues/460) (reference driver needed) - in progress - @lubega-simon (previously @jonludlam)
- [#573](https://github.com/ocaml/odoc/issues/573) (docs are bad) - in progress, on hold - @lubega-simon (previously @jonludlam)
- [#601](https://github.com/ocaml/odoc/issues/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](https://github.com/ocaml/odoc/issues/664) - Failures when resolving references are not reported - @julow assigned (part of #557)
- [#666](https://github.com/ocaml/odoc/issues/666) - Initial stop comment hinders output - Proposal: not for 2.0
### In progress:
- [#658](https://github.com/ocaml/odoc/pull/658) - Don't resolve references in synopses in {!modules} lists -- PR open [#662](https://github.com/ocaml/odoc/pull/662)
- [#659](https://github.com/ocaml/odoc/issues/659) (Resolution bug for sections) -- assigned to @julow
- [#650](https://github.com/ocaml/odoc/issues/650) (Need ModuleType 'aliases') - @jonludlam
- [#648](https://github.com/ocaml/odoc/issues/648) (Warnings about ambiguous references are bogus) - @julow
- [#651](https://github.com/ocaml/odoc/issues/651) (Improve tests for generators (html, man, and latex)) - @lubega-simon -- PR open [#665](https://github.com/ocaml/odoc/issues/665)
- [#460](https://github.com/ocaml/odoc/issues/460) (reference driver needed) - in progress - @lubega-simon (previously @jonludlam)
- [#573](https://github.com/ocaml/odoc/issues/573) (docs are bad) - in progress, on hold - @lubega-simon (previously @jonludlam)
- [#557](https://github.com/ocaml/odoc/issues/557) (Command to extract errors from odocl files) - @julow (previously @jonludlam)
- [#601](https://github.com/ocaml/odoc/issues/601) (Type extensions are no anchorable and should be classified as type) - @julow
## Fixed since last time
- [#632](https://github.com/ocaml/odoc/issues/632) (No synopsis rendered for modules) - partial fix merged, new fix incoming - @julow
- [#478](https://github.com/ocaml/odoc/issues/478) (Top-level doc-comments of module types are discarded)
Sign in with Wallet
