Odoc 1.4.0 — new OCaml documentation generator

Community
,
21

Yes, that was my plan. I will create a related issue in due course.

1 Like
22

Hello,
is there any special way to generate the table of contents ?
I have upgraded to odoc 1.4, build the documentation with dune build @doc, but no toc is generated that I can see…
Also, would the toc be generated for the index.mld file too ?

Edit : Ok I found it out, you need to to put the sections in comments unassociated with any element.

2 Likes
23

Is there any way to change the default dark mode theme? I find it very unappealing and would prefer a light theme but have no clue how to change it when deploying docs via dune build @doc. Any pointer would be appreciated!

2 Likes
24

And the font as well ?

1 Like
25

For people who are not generating but reading the docs. Note that odig has few alternate stylesheets and you can bring your own if none suits. See the docs here.

For generating I’m pretty sure the odoc devs will get to it at some point but the focus seems to be elsewhere at the moment.

1 Like
26

That’s a bit sad to read because I was really hoping i’d be able to use the gruvbox light theme of odig to deploy my library docs.

1 Like
27

If you really want to you can use this workflow.

2 Likes
28

For some reason this doesn’t work for me. I get

$ odig odoc -v --odoc-theme=odig.gruvbox.light --index-intro=./doc/intro.mld --no-
pkg-deps zarr
odig: [8.05ms] package list of '/home/zoj/.opam/5.1.1/lib'
Updating documentation, this may take some time...
odig: [299μs] theme list of '/home/zoj/.opam/5.1.1/share'
odig: [840ms] opam show
odig: [2.02ms] generating log
odig: [607μs] writing log
odig: [498μs] deleting trash
[FAILED] These files never became ready:
 ....
 See operations reading them for details.
odig: [ERROR] Documentation might be incomplete (see: odig log -e).
odig: [1.08s] total time

Also the generated docs page ignores the added ./doc/intro.mld and the updated data in the dune-project file. What am I doing wrong?

1 Like
29

There not enough details for me to know.

Do you have zarr installed in your opam switch ?

Also I’m not sure what you mean by updated data in the dune-project file but for sure odig will never look anything there, it only generates documentation of packages installed in your switch.

Also did you try to checkout the docs despite the error ?

1 Like
30

Sorry I didn’t explain myself well in the previous post.

zarr is the local project i’m trying to generate and deploy docs for. It does build and work using odig doc zarr if I do opam install . beforehand. However, if I update the zarr.mli file with more docs, and an ./doc/intro.mld file and update the dune-project file, none of these changes are reflected in the generated doc site (e.g the PACKAGE INFO section). Then I tried the instructions in your linked workflow but ended up getting the error I reported in my previous post.

My question is: How do I get the local docs to build and be generated correctly AND also use the generated content and deploy it as my project’s official docs on github pages?

1 Like
31

odig just does docs for packages that are installed in an opam switch. So you need to update your package in the opam switch if you want it to pick up any changes.

Besides for now it still takes too much time to check that nothing has to be rebuild in the switch on odig doc lookups. So you need to invoke it with -u when things are expected to change (i.e. odig doc -u); see the docs here. If you want to make extra sure that every thing is clean you can do a odig cache clear before doing odig doc.

My advice would be to simply use dune worfklow for working on your docs and use odig in one shot for publishing your docset if you want another stylesheet for your public docs.

I’m not sure about the doc/intro.mld perhaps it’s also about the -u thing. People have used it in the past so it should work. Please file an issue with details if it does not.

(Personally I use another workflow with brzo to generate all the docsets here with alternate stylesheets but I suspect it’s not compatible with all the name munging dune does on source files to cater for problems that should be solved upstream; so it’s likely not worth looking into unless you are using (wrapped false)).

1 Like
32

Also perhaps even simpler you can simply copy the files of $(opam var odig:share)/odoc-theme/gruvbox.light at the right place after dune 's doc generation, I think that this should just work®.

1 Like
33

I understand that for the time being, there is no simple way of generating doc with the same theme as the OCaml library, isn’t it ? Neither with odoc nor with odig ?

1 Like
34

Depends on what you mean by simple :–) For me it looks rather simple:

  1. Make an odoc.css stylesheet for odoc for that mimics this style.
  2. Make an opam package mystyle for it that installs it as per convention. Basically as $(opam var mystyle:share)/odoc-theme/default/odoc.css
  3. Check that odig sees the stylesheet with odig odoc-theme list.
  4. Invoke odig odoc-theme set mystyle.default
  5. Enjoy your stylesheet with odig doc

The not so simple part is of course 1. If you want to start from a blueprint I rather suggest you start from the odoc.css you can find in odig which is less unwieldy than the default odoc stylesheet. Perhaps you could convince @sanette who is, I believe, the author of this style to devise such a stylesheet.

P.S. I was always a bit disapointed that no-one came up with alternate stylesheets for odig. I’m generally not so much for providing choice as it usually means lack of design. But documentation reading is an area where I think it is good to have a diversity of looks, so that the docs in which you spend your working life blends well with your dev setup and accessibility requirements. (odig went so far as to styling the OCaml manual that you can install with opam install ocaml-manual but did so using insane selectors which I’m sure updates to the manual must have broken by now :–).

35

I tried that of course, starting from manual.css and style.css in the opam manual website. My understanding is that both are needed … hence a merge needs to be done. If @sanette does not have time to do that because this is time consuming, maybe providing some guidance would help us (me?) to do it for the community ?

36

No merge is needed, you can do it on your side. Also if you want just want the API you can simply devise odoc.css.

What kind of guidance are you seeking ? It basically boils down to this.

37

As I said, I tried and I got a result which is approaching what we can see on the ocaml manual, but not 100% satisfying though. Which leads me to the conclusion that the style sheets I have used are not enough and that probably a combination of different style sheets is needed. As a matter of fact, on the ocaml manual first page, the style sheet is manual.css where as on standard libraries pages, the style sheet is style.css and none of them work alone (with a simple copy and paste). So I need to dig into the style sheets, but that’s the tedious task I wanted to avoid, especially if cascading css is involved. For this (architecture of css sheets) a guidance would be welcome.

Hope this is more clear.

Envoyé depuis l’application Mail Orange

38

No that won’t work, the API docs on that part of the website uses ocamldoc to generate the docs. You want a stylesheet that works with the output of odoc and their markup structure is entirely different. The best way is to either:

  1. Start with an empty odoc.css and gradually make the output look like you want.
  2. Start with an odoc.css and gradually change the rule definitions until you get the look you want.
39

I think we finally agree. There is no guarantee with this method that I can get the same look as in the standard library with an odoc generated markup (I used the work html) structure … Let’s give it a try though.