Two Major Improvements in odoc: Introducing Search Engine Integration

In the world of OCaml documentation generation, there have been two significant enhancements that promise to make navigating OCaml documentation easier and more efficient. These improvements are divided into two distinct but interrelated components: changes in odoc itself and improvements in a search engine known as Sherlodoc.

These updates make navigating OCaml documentation more efficient and user-friendly, benefiting both seasoned OCaml programmers and those just venturing into the world of OCaml.

If you're new to odoc, you can read more about it in this introductory blog post and on its website (which was also generated by odoc!)

Now, let's dive into these transformative upgrades and see how they enhance the OCaml documentation landscape.

Changes in odoc: Search Engine Integration

This year, odoc has taken a giant step forward by allowing seamless integration with search engines. This change is modular, ensuring flexibility in search implementation. As long as a search engine can provide search results in a specific format, it can be utilised with odoc. These changes can be server-side or client-side, written in either JavaScript or OCaml, and executed locally or remotely.

Search Bar and Display

odoc now offers a user interface that includes a search bar and a display of search results. This feature enhances the overall user experience, making it more intuitive and accessible.

JSON Index

odoc provides an index in JSON format that search engines can utilise. The search engine uses this index to generate its representation of the search index. OCaml programmers can also leverage specific functions in odoc to generate their custom search indexes.

Flexible Search Engine

With the new search bar, you can even write your own search engine. This feature opens up new possibilities for customisation and tailoring the search experience to your specific needs.

The search engine can take the form of a JavaScript file, which can either contain an index for local searches or make requests to a server for larger indexes.

Web Worker Integration

odoc runs the search engine in a web worker, ensuring asynchronicity and preventing UI blockage. This design decision contributes to a smoother user experience, especially when dealing with extensive documentation.

In essence, odoc has made it incredibly straightforward to integrate search engines into its documentation output. This modular approach allows for diverse and customised search solutions while keeping the user interface consistent.

Sherlodoc: The Canonical OCaml Search Engine

While any search engine can be used with odoc, Sherlodoc stands out as the canonical search engine for OCaml. It has undergone significant improvements to enhance its usability and expressiveness. These changes make Sherlodoc an ideal choice for OCaml documentation.

Integration with odoc

Sherlodoc can now be directly integrated into documentation generated by odoc. It offers the choice to compile it into JavaScript or keep it as a native program, accommodating both client-side and server-side search functionality.

Search Features

Sherlodoc introduces powerful search capabilities, allowing users to search within docstrings, constructors, modules, and more. Its expressive search queries provide an efficient way to find the information you need.

The Sherlodoc search engine is designed with OCaml in mind. It allows you to search within docstrings, generated standalone pages, as well as directly in the interface even using specific OCaml-like syntax.

Since it knows about the OCaml type system, you can quickly find functions, values, etc., by writing their type in the query. This level of tailoring enhances the OCaml documentation experience, making it even more accessible and productive.

For instance, searching for _ -> int will result in all functions which produce an integer

Future Integration

One of the most exciting aspects of this update is that Sherlodoc will be fully integrated into OCaml.org. Instead of relying on a separate website or tool, you can access all the powerful search capabilities right on OCaml's official website!

This integration brings a multitude of benefits to OCaml.org users. Currently, users can only search using strings, but the new search bar will provide more sophisticated searching. Users can now search more effectively within a specific package or for values with particular types, simplifying the process of locating the exact information you need. Now you spend less time searching and more time coding!

These enhancements align perfectly with our goal of delivering a more cohesive, robust, and user-friendly documentation experience on OCaml.org.

Collaborative Efforts

The journey to these enhanced search capabilities involved numerous design phases and questions. We pondered how to create the features we envisioned, how to seamlessly integrate them into OCaml.org, and how to make the search bar functional for small databases, local documentation, and the entirety of opam. These considerations guided the development process, ensuring that the new search bar is versatile, efficient, and accessible to all OCaml engineers.

This achievement wouldn't have been possible without the dedication of several individuals from Tarides. Paul-Elliot Anglès d'Auriac spearheaded this project. It was his main focus since the summer. He implemented the odoc support for search engine. Jules Aguillon supplied invaluable oversight and review, ensuring the project's quality. Emile Trotignon played a vital role in the search engine development and user interface. Their combined efforts have resulted in this remarkable upgrade to odoc.

Conclusion

Documentation is an integral part of software development, and odoc is a powerful tool that makes OCaml coding more accessible and efficient. As OCaml continues to evolve and gain traction in various domains, odoc's commitment to providing robust documentation tools is a testament to the language's growth and the support it offers to its community of developers.

With odoc's new search bar and the Sherlodoc integration, exploring and navigating OCaml documentation has never been more effortless and productive.

These two major improvements promise to revolutionise how OCaml documentation is accessed and navigated. The combination of a modular odoc and the canonical Sherlodoc search engine brings flexibility, efficiency, and a robust search experience to OCaml developers and users.

This new era of OCaml documentation will provide users with a smooth and intuitive experience, helping them access relevant information quickly and efficiently. The improvements in odoc and the integration of Sherlodoc signal a bright future for OCaml documentation and its users.

Stay tuned for more exciting developments in the world of OCaml!

Please don't hesitate to join the odoc conversation on discuss.ocaml.org under the Ecosystem category by using the odoc tag. Also, feel free to open a GitHub issue with any concerns or ideas, as we're always striving to improve our products.