Problems with odoc generated documentation on gh-pages

Community
1

I have an ocaml project and I generate the documentation with odoc. On my computer everthing works nicely.

As soon as I transfer exactly the same generated documentation to gh-pages I get the following strange error in the browser console:

ror with Permissions-Policy header: Origin trial controlled feature not enabled: 'interest-cohort'.
browser_overview.html:2     GET https://hbr.github.io/fmlib/odoc/_odoc_support/odoc.css net::ERR_ABORTED 404
browser_overview.html:2     GET https://hbr.github.io/fmlib/odoc/_odoc_support/highlight.pack.js net::ERR_ABORTED 404
browser_overview.html:2 Uncaught ReferenceError: hljs is not defined
    at browser_overview.html:2:375
(anonymous) @ browser_overview.html:2

It seems that the browser cannot load the odoc.css file and therefore cannot display the content correctly.

Has anybody seen such a strange error message or can give any hint of what’s wrong here.

Regards
Helmut

2

That doesn’t seem like the correct directory structure. Compare to mine: GitHub - yawaramin/ocaml-decimal at gh-pages

Can you explain exactly which location you are checking in the files from? Another option–I use dune-release which does the doc upload for me. You could try that too.

1 Like
3

Thanks for the hint. But I have no influence on the directory structure generated by odoc. But the structure works fine locally on my machine and if I transfer exactly the same directory structure to github pages, then odoc.css cannot be found anymore.

However odoc.css is there in the repo. But it seems to be not on the webpage.

5

You don’t need to influence the directory structure generated by odoc, you just need to upload the correct part of that structure to GitHub. That’s why I pointed you to my repo, so you could compare the directory structures. I just ran dune build @doc locally and got this output layout:

$ ls _build/default/_doc/_html
decimal			highlight.pack.js	katex.min.css		odoc.css
fonts			index.html		katex.min.js

So the solution is to just make sure you check in only the contents of the _html directory. Based on your initial message it seems you are uploading files from some other directory path. That’s why I asked where you were uploading from.

6

There is an issue in the Dune repository about this here: Bad interaction between _odoc_supports directory and github pages / jekyll · Issue #7364 · ocaml/dune · GitHub

You can fix it in your site by adding a .nojekyll file to the root of your gh-pages branch.

1 Like
7

The change in Dune which causes this issue was introduced in Dune 3.7. It looks like your repo was built with a previous version, so it wouldn’t have been effected.

1 Like
8

Thanks. Adding an empty file called .nojekyll to the root of github pages solved the problem. Jekyll considers all directories starting with underscore as special and does not copy them to the final site. odoc generates the directory _odoc_support which contains odoc.css and some other needed files. If these files are not present at the final site, then the content is not displayed nicely.

A longterm solution to the problem would be that odoc does not generate directories starting with underscore.

Regards
Helmut

3 Likes