Add patricia tree doc

[dlesbre]

Changes:

• Add a custom 404 page
• Add an icon to the github repository link
• Add documentation generated by odoc. The documentation files are generated by dune build @doc-json and placed in _data/api/patricia-tree.
  • The base for this came from frama-c's website (_plugins/odoc.rb, _layouts/odoc.html, assets/css/api.css)
  • I've changed the CSS file to use colors that match our site
  • I've changed the _layout/odoc.html to add a warning if not browsing the latest version
  • I've added sherlodoc's searchbar to _layout/odoc.html, the sherlodoc database files (also generated by dune build @doc-json, provided sherlodoc is installed) have to be placed in /assets/js/sherlodoc-db
• I've also added and modified some just-the-docs files to fix some issues/add features. Most of the code in these files isn't mine:
  • changed the default sidebar _includes/component/sidebar to add a table of contents (only appears on odoc pages for now, it might be possible to extend it to also have a TOC on other pages of the website).
  • change the compress_html layout (_layout/vendor/compress.html) to disable it on the odoc pages as it screws with rendering (see https://git.frama-c.com/pub/pub.frama-c.com/-/issues/26 for details)
  • change the search index assets/js/zzzz-search-index.json to include the odoc pages in the search. I've only added the latest version of the documentation to the search index. However, this still produces a lot of results (especially for functions/modules which appear multiple, e.g. BaseMap)
• The path to the documentation was changed from /patricia-tree/, to /api/patricia-tree/. I've added a redirect to ensure the old URL still works. This requires adding the jekyll-redirect-from plugin.
• For this to work properly, the github-pages from the patricia-tree repo must be disabled.
• changed _config.yml to exclude files which shouldn't appear on the website.

Things I haven't done that we should consider:

• Add doc for the main codex package in the same way as patricia tree.
• Have the patricia-tree CI automatically push the new JSON files to this repository on pushes.
• Add TOC to other website pages (requires generating TOC for md/html files, not quite sure how to do that yet).
• Frama-C's website managed to not commit the JSON files to its repo, it just gets them from an artifact before build. Not sure how we could do this with github-actions.

[mlemerre]

This is an excellent job. Many thanks!

[mlemerre]

Add doc for the main codex package in the same way as patricia tree

This is a good idea, although we may want to mark it as work in progress. I think the best would be to say which modules have a stable interface and which do not, start making a large codex review where we would document (and also, question the design) of everything module per module.

[mlemerre]

Have the patricia-tree CI automatically push the new JSON files to this repository on pushes.

Indeed. Maybe reviewing the doc would be nice but we can do it when we review the code.

[mlemerre]

Add TOC to other website pages (requires generating TOC for md/html files, not quite sure how to do that yet).

Do you have an idea of other pages that would be missing a TOC?

[mlemerre]

Frama-C's website managed to not commit the JSON files to its repo, it just gets them from an artifact before build. Not sure how we could do this with github-actions.

Is there a point in doing this? Commiting the JSON files seem to be sufficient.

[mlemerre]

Maybe we can try to setup hackathon for these specific topics, and could group these TODOs as issues of the website. Other than that, I think the merge request is ready?

[dlesbre]

Add doc for the main codex package in the same way as patricia tree

This is a good idea, although we may want to mark it as work in progress. I think the best would be to say which modules have a stable interface and which do not, start making a large codex review where we would document (and also, question the design) of everything module per module.

Yes, I haven't added it yet because I wasn't sure how usable/commented codex interfaces are, or if they are commented, if they correctly use odoc syntax ((** bla *) comments).

Have the patricia-tree CI automatically push the new JSON files to this repository on pushes.

Indeed. Maybe reviewing the doc would be nice but we can do it when we review the code.

This is why we have a documentation version for the main branch, it is experimental and allows seeing how the documentation will look once we release. It isn't much of a problem if that version breaks, since the vX.Y.Z version would still be accesible (and the recommended way to browse the docs).

Add TOC to other website pages (requires generating TOC for md/html files, not quite sure how to do that yet).

Do you have an idea of other pages that would be missing a TOC?

Not currently, the only other pages are nutshells which are rather short. However, if we want to add tutorials/explanation not generated by odoc, it might useful to have.

Frama-C's website managed to not commit the JSON files to its repo, it just gets them from an artifact before build. Not sure how we could do this with github-actions.

Is there a point in doing this? Commiting the JSON files seem to be sufficient.

Yes it works fine. The rationale for this was that if we setup a CI auto-update, we might start polluting history with a lot of auto-generated commits, but I don't think it matters too much.

For TODOs, I think the main one is adding the codex doc. Everything else is a "nice to have but entirely optional" feature.

Also yes the PR is ready. I marked it as draft yesterday because I ran out of battery while creating it and wanted to make sure I hadn't forgotten anything.

[dlesbre]

@mlemerre Once you merge this I can release version 0.10.0