ocaml / ocaml.org

The official OCaml website.

OCaml.org

This repository contains the sources of the OCaml website. It is served at https://ocaml.org/.

Features

• Integrated documentation and package management: The site combines the package management (currently opam.ocaml.org) with a new central documentation source (codenamed 'docs.ocaml.org') for all 14000+ opam packages directly within the ocaml.org site.

• Responsive and accessible: The site design also takes into account modern web-design principles, restructuring the old content in accordance with methods that will present it more compellingly. It is a total redesign that modernises the look and feel of the webpage, as well as make it easier to navigate, and more accessible (particularly on mobile devices).

• Separation of data editing from HTML/CSS generation: The data used in the website is stored in Yaml or Markdown so users can easily edit it and contribute to the website. We generate OCaml code from this data to serve the site content and and Ocurrent to automate the data pipelines. All the data used in the site can be found in ./data.

Getting started

You can setup the project with:

Before you begin, make sure you have opam (OCaml Package Manager) installed on your system. If you haven't installed it yet, you can follow the official installation instructions for your platform:

• Official opam Installation Guide

Once opam is installed, you can set up the project and run it with the following commands:

make switch

And run it with:

make start

See our contributing guide for more detailed instructions.

Maintainers

The OCaml.org maintainers team is composed of the following community members:

• Anil Madhavapeddy (@avsm), Owner (University of Cambridge)
• Thibaut Mattio (@tmattio), Lead Maintainer (Tarides)
• Christine Rose (@christinerose), Maintainer (Tarides)
• Cuihtlauac Alvarado (@cuihtlauac), Maintainer (Tarides)
• Sabine Schmaltz (@sabine), Maintainer (Tarides)

The roles and responsibilities are explained in the governance, don't hesitate to have a look for more details.

We're always looking for new maintainers! If you're interested in helping us make OCaml.org the best resource to learn OCaml and discover the ecosystem, reach out to us!

Acknowlegement

Thank you to everyone who contributed to the development of this new version of the website!

In particular:

• Ashish Agarwal (Solvuu)
• Kanishka Azimi (Solvuu)
• Richard Davison (Solvuu)
• Patrick Ferris (OCaml Labs)
• Gemma Gordon (OCaml Labs)
• Isabella Leandersson (OCaml Labs)
• Thibaut Mattio (Tarides)
• Anil Madhavapeddy (University of Cambridge)

For the groundwork on rethinking the sitemap, user flows, new content, design, and frontend and package docs!

• Jon Ludlam (OCaml Labs)
• Jules Aguillon (Tarides)
• Lucas Pluvinage (Tarides)

For the work on the package site infrastructure and UI!

• Paul-Elliot Anglès d’Auriac (Tarides)

For meticulously going through the website to find issues.

• Isabella Leandersson (OCaml Labs)
• Asaad Mahmood (Tarides)

For the work on the designs and bringing them to life on the frontend!

• Christine Rose (Tarides)
• Isabella Leandersson (OCaml Labs)

For the work on the new content and reviewing the existing one!

We’d also like to thank the major funders who supported work on revamping the website: grants from the Tezos Foundation and Jane Street facilitated the bulk of the work. Thank you, and if anyone else wishes to help support it on an ongoing basis then donations to the OCaml Software Foundation and grants to the maintenance teams mentioned above are always welcomed.

Contributing

We'd love your help improving ocaml.org!

See our contributing guide in CONTRIBUTING.md

License

• The source code is released under ISC
• The data is released under CC BY-SA 4.0
• Code examples within the content are released under UNLICENSE.
• The OCaml logo is released under UNLICENSE.
• The vendored files are listed with their licenses in LICENSE-3RD-PARTY

See our LICENSE for the complete licenses.

Code of Conduct

This project follows the OCaml Code of Conduct.

ocaml.org's Issues

Github flavored markdown is not supported

This breaks the tables, checklist, etc.

E.g. https://ocamlorg.herokuapp.com/p/ppx_deriving_yaml/0.1.0

Related to #35

Improve GraphQL Tests

As discussed in #73 there are a few missing tests such as:

• What if the limit is None?
• What if the offset is not 0?
• Are the correct 3 packages returned when you ask for and offset 0 and limit 3?
• A test to check for correct functionality for edge cases in limit and offset (negative, out of bounds etc.)
• Correctly returning None if a package is not found
• Should the length of packages be something the function calculates rather than something the user passes in ?

(just for clarification, the current tests are great and are the only "real" ones -- this is just in response to some outstanding tasks in the original PR)

cc @dinakajoy

[Design Feedback] Package search page

Page: https://v3.ocaml.org/packages/search?q=dream

[Design Feedback] Package landing page

Page: https://v3.ocaml.org/packages

Navigate from package to v3 is broken

Should be fixed by #16

[Design Feedback] Package overview page

Page: https://v3.ocaml.org/p/dream/1.0.0~alpha2

Add Opam publish documentation

The landing page has a call to action to the opam publish documentation, which does not exist yet.

Add package publication date to overview, search results and package statistics

Universes URL are broken

The titles of the documentation page are are all the same

They can be generated from the request path.

Support README.org and other formats

https://github.com/janestreet/base has a README.org file but it's not picked up in the package page

Integrate http://check.ocamllabs.io/

Can also integrate checks in package overview - e.g https://community.chocolatey.org/packages/KB2919355#testingResults

cc @patricoferris

Improve package search pages

Add an "Order by" menu, the packages tags, and revamp the overall design

Handle package universes in the frontend

The documentation of the package universes should be available, but we should handle them in the frontend so users can navigate the different universes.

Add tests for graphql endpoint

Once #60 is merged, we will need to right some tests for it, we've decided to split the two given how young this repository is (and lack of testing there already is) so as to not block that PR.

Search bar instant result while typing

See Github search bar for a reference.

Related to #26

Add rev-deps in the package overview

This is the last metadata missing from the current opam.ocaml.org site.

Blacktilts in package documentation clash with OCaml polymorphic variant syntax

We should remove them, and eventually add a gray background for the inline code.

Handle HTML in README

This would allow to display the titles when they are centered (very common) and images (also very common).

Add a package toplevel

See #29 for some initial work

Package meta image for external links

Similarly to how Github does it

[Design Feedback] Navigation bar mobile view

v3:

v3-server:

404 in documentation does not render the not found page

Add an overlow scroll to the TOC in the documentation

If the TOC is too large, we should allow users to scroll it.

Add tags to overview

The current opam package registry displays the tags of the packages in the overview: https://opam.ocaml.org/packages/dream/

The V3 package registry should list them on the package overview package, between Install and Authors: https://v3.ocaml.org/p/dream/1.0.0~alpha2

They could be displayed with a badge, e.g.:

<span class="inline-flex items-center px-2.5 py-0.5 rounded-md text-sm font-medium bg-gray-100 text-gray-800">
  Tag
</span>

Mobile view of the documentation looks off

Import `ocaml.org` content

Meta-issue to track the migration of the content from the current ocaml.org website.

• 99 Problems (ocaml/ood#15)
• Releases (ocaml/ood#18)
• Success stories (ocaml/ood#17, ocaml/ood#20)
• Books (ocaml/ood#16)
• Videos
• Papers (ocaml/ood#11)
• Events
• English Tutorials (ocaml/ood#14)
• Meetings (#111)
• Companies (ocaml/ood#26)
• Consortium (ocaml/ood#33)
• Platform tools (ocaml/ood#34)
• Academia (ocaml/ood#24)
• Best known methods (new content)

The package page links to the documentation even if it does not exist

We should query the status.json file and disable the link with a tag if it's not there.

Change all instances of images to include alt text

We use images in lots of different places (logos for companies, university emblems, background images for conferences etc.) -- since ood is the source of truth for which images we use, it is also probably the correct place to add alt text describing the images.

It would be good to change all instances of a path pointing to an image in media to something like:

module Image = struct
  type t = {
    path : string;
    alt : string;
  }
end

Add download statitics

Add source for the "OCaml in numbers section"

I know it's based on the survey. INRIA created a detailed breakdown of the survey. The % points without the source send a very weak message. The opposite would be true if the source was provided.

Documentation of variants with comments is broken

E.g. https://v3.ocaml.org/p/caqti/1.6.0/doc/Caqti_query/index.html

The documentation UI is broken when no TOC is available for a given page

For instance: https://ocamlorg.herokuapp.com/p/inquire/0.3.1/doc/Inquire/index.html

Link to license and changelog in overview

Fetch package documentation over HTTP

This should allow for a much better local dev setup.

Move opam user info to ood

... and create process to add opt-in consent for Github information

Link not working accross packages

E.g. Formatter in https://ocamlorg.herokuapp.com/p/astring/0.8.5/doc/Astring/index.html

This should be fixed in voodoo

Improve package search algorithm

Using levenshtein distance sounds reasonable

Add the meta descriptions for search engine

To improve SEO, we want a nice looking entry on Google ✨

Add breadcrumb and header to documentation pages

[Design Feedback] Changes on font weight and spacing for flyout menus

v3:

v3-server:

Add a opam repository search bar in every package page

It is frustrating to not be able to navigate to another package quickly from a package page.

Support documentation dark mode

See tailwindlabs/tailwindcss-typography#69 for the content

[Design Feedback] Package documentation page

Page: https://v3.ocaml.org/p/dream/1.0.0~alpha2/doc/Dream/index.html

Add a global documentation navbar

... which would contain the custom pages

See https://hexdocs.pm/phoenix/overview.html for a global navbar example

Keeping in-sync with ocaml.org

This issue is a place to keep track of changes upstream in ocaml.org whilst ood is not the main, promoted placed to be storing this information. This issue can just be extended as new content is potentially merged in ocaml.org and closed later whenever we can do that.

To Do

• Import r2c into industrial users #1573
• Add the macOS/iOS app to "A First Hour with OCaml" #1582
• Incorporate changes to "Data types" tutorial #1576
• Add better currying description #1595
• Add list tutorial #1565
• initial ocaml on windows explanation #1600

To Monitor

• Adds ‘Building and publishing’ tutorial (replacement PR) #1606
• Add a solution for “94. An arithmetic puzzle.” in 99 Problems #1597
• Rewrote set tutorial from scratch. #1596
• Add an example of an adjacency list #1594
• Update solution for 12 to be more succinct #1593
• 99problems.md add solution for 22 #1592
• update 99problems.md (number 13) #1591
• 99problems update (number 12) #1590

Dynamically generate the default documentation index page

The default documentation index page can be generated dynamically so:

• We don't have to re-generate all the documentation to update it
• We can experiment on improving its design and content

Any package index.mld file should be respected, however.

Include blocks are not visibly demarcated.

Odoc usually shows a border on the right to show which sections come from included signatures. See the right-hand side of the include here:

and the bottom of the included section here:

'comment-delim' items are intended to be hidden

see e.g. https://ocamlorg.herokuapp.com/p/tezos-base/8.0/doc/Tezos_base/Block_header/index.html#type-shell_header - specifically the (* and *) around the documentation of the record fields.

The idea is that you can cut-n-paste the record definitions and get valid code, but that they don't actually appear on-screen.

Add a search in the docs feature

To allow searching for content from the documentation