Skip to content

Update ROADMAP.md #1421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jonludlam wants to merge 1 commit into
base: master
Choose a base branch
from
+15 −6
Open

Update ROADMAP.md #1421

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 15 additions & 6 deletions ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ As of 2022, the lack of access to great documentation for OCaml packages is one

To address this, our current focus is on empowering OCaml developers to create high-quality documentation for their packages.

Now that the documentation of OCaml packages is [readily available on OCaml.org](https://ocaml.org/packages), we want to make writing documentation rewarding and straightforward. We’re working towards making Odoc suitable to create manuals by adding new features, improving the navigation, and expanding the odoc markup syntax to support rich content such as tables, images and graphs.
Now that the documentation of OCaml packages is [readily available on OCaml.org](https://ocaml.org/packages), we want to make writing documentation rewarding and straightforward. We're working towards making Odoc suitable to create manuals by adding new features, improving the navigation, and expanding the odoc markup syntax to support rich content such as tables, images and graphs.

To prioritize our work, we look at OCaml projects that rely on other documentation generators:

- The OCaml Manual
Expand All @@ -13,9 +14,17 @@ To prioritize our work, we look at OCaml projects that rely on other documentati

In collaboration with the maintainers of these projects, we identify the blockers they have to migrate to odoc and scope the necessary features and bug fixes.

Notable new features on our roadmap include:
The items below are listed roughly in the order we intend to tackle them.

## Odoc

- **OxCaml support.** OxCaml is a moving target, so this will necessarily be a different 'style' of support from OCaml support. We will make no effort to support multiple versions of the OxCaml compiler, and so each release of Odoc will likely be tied to a specific release of the OxCaml compiler. The aim is to support all relevant features of the OxCaml compiler, including modes, layouts and so on as part of the documentation.
- **New markup syntax.** Adding support for several new markup features, such as: admonitions, quotes, definition lists, and details.
- **Custom tags and plugins.** Adding support for custom tags to Odoc, and a plugin mechanism so that the behaviour of these custom tags can be specified.
- **Improved source rendering.** Enhanced rendering of source pages, as well as new syntax to link directly to implementations from doc comments.

## Sherlodoc

- Adding a search bar to the HTML backend
- Adding a global navigation bar that contains the package API and manual pages
- Generation of an index page
- Add a special syntax for images and assets
- Support for markdown output as well as HTML.
- Support for search in documentation pages.
- Improved support for incremental building.
Loading