Problem with generating sedlex doc with ocamldoc

[Andy Li]

Hi,

I'm updating the sedlex package and got stuck with an error with
dh_ocamldoc.
I'm not familiar with ocamldoc + the ppx system (which is adopted by sedlex
in the recent version), so I would like to have some help.

I tried to call ocamldoc manually with an existing sedlex 2.1 installation
(installed by `opam install sedlex`):

ocamlfind ocamldoc -sort \
\
-I ~/.opam/default/lib/sedlex \
-I ~/.opam/default/lib/sedlex/ppx \
\
-package gen \
-package compiler-libs \
-package ocaml-migrate-parsetree \
-package ppx_tools_versioned \
-ppx "ocamlfind ppx_tools_versioned/metaquot_405/ppx.exe --as-ppx" \
\
~/.opam/default/lib/sedlex/ppx/sedlex_cset.mli \
~/.opam/default/lib/sedlex/ppx/ppx_sedlex.ml \
~/.opam/default/lib/sedlex/ppx/sedlex.mli \
~/.opam/default/lib/sedlex/ppx/sedlex_ppx.ml \
~/.opam/default/lib/sedlex/ppx/unicode.mli \
~/.opam/default/lib/sedlex/sedlexing.mli \
\
-html -stars -m A


output:

File "/home/andy/.opam/default/lib/sedlex/ppx/ppx_sedlex.ml", line 17,
characters 14-25:
17 | module Cset = Sedlex_cset
^^^^^^^^^^^
Error: Unbound module Sedlex_cset
File "/home/andy/.opam/default/lib/sedlex/ppx/sedlex.mli", line 7,
characters 11-24:
7 | val chars: Sedlex_cset.t -> regexp
^^^^^^^^^^^^^
Error: Unbound module Sedlex_cset
File "/home/andy/.opam/default/lib/sedlex/ppx/unicode.mli", line 7,
characters 11-24:
7 | val cc : Sedlex_cset.t
^^^^^^^^^^^^^
Error: Unbound module Sedlex_cset
Warning: Module or module type Sedlex_ppx__Unicode not found
Warning: Module or module type Sedlex_ppx__Sedlex_cset not found
Warning: Module or module type Sedlex_ppx__Sedlex not found
Warning: Module or module type Sedlex_ppx__Ppx_sedlex not found
Warning: Module or module type Sedlex_ppx__Unicode not found
Warning: Module or module type Sedlex_ppx__Sedlex_cset not found
Warning: Module or module type Sedlex_ppx__Sedlex not found
Warning: Module or module type Sedlex_ppx__Ppx_sedlex not found
Warning: Element Uchar.t not found
Warning: Element Lexing.pos_fname not found
Warning: Element Lexing.position not found
Warning: Tag @canonical not handled by this generator
Warning: Tag @canonical not handled by this generator
Warning: Tag @canonical not handled by this generator
Warning: Tag @canonical not handled by this generator
3 error(s) encountered

I can't get rid of the "Unbound module Sedlex_cset" error.
Notice that "sedlex_cset.mli" was in the search path
"~/.opam/default/lib/sedlex/ppx" already.
Any help is appreciated.

Best,
Andy

[Stéphane Glondu]

Hi,

Post by Andy Li
I'm updating the sedlex package and got stuck with an error with
dh_ocamldoc.
I'm not familiar with ocamldoc + the ppx system (which is adopted by
sedlex in the recent version), so I would like to have some help.
I tried to call ocamldoc manually with an existing sedlex 2.1
ocamlfind ocamldoc -sort \
\
-I ~/.opam/default/lib/sedlex  \
-I ~/.opam/default/lib/sedlex/ppx \
\
-package gen \
-package compiler-libs \
-package ocaml-migrate-parsetree \
-package ppx_tools_versioned \
-ppx "ocamlfind ppx_tools_versioned/metaquot_405/ppx.exe --as-ppx" \
\
~/.opam/default/lib/sedlex/ppx/sedlex_cset.mli \
~/.opam/default/lib/sedlex/ppx/ppx_sedlex.ml <http://ppx_sedlex.ml> \
~/.opam/default/lib/sedlex/ppx/sedlex.mli \
~/.opam/default/lib/sedlex/ppx/sedlex_ppx.ml <http://sedlex_ppx.ml> \
~/.opam/default/lib/sedlex/ppx/unicode.mli \
~/.opam/default/lib/sedlex/sedlexing.mli \
\
-html -stars -m A
File "/home/andy/.opam/default/lib/sedlex/ppx/ppx_sedlex.ml
17 | module Cset = Sedlex_cset
                   ^^^^^^^^^^^
Error: Unbound module Sedlex_cset
File "/home/andy/.opam/default/lib/sedlex/ppx/sedlex.mli", line 7,
7 | val chars: Sedlex_cset.t -> regexp
               ^^^^^^^^^^^^^
Error: Unbound module Sedlex_cset
File "/home/andy/.opam/default/lib/sedlex/ppx/unicode.mli", line 7,
7 |   val cc : Sedlex_cset.t
               ^^^^^^^^^^^^^
Error: Unbound module Sedlex_cset
Warning: Module or module type Sedlex_ppx__Unicode not found
Warning: Module or module type Sedlex_ppx__Sedlex_cset not found
Warning: Module or module type Sedlex_ppx__Sedlex not found
Warning: Module or module type Sedlex_ppx__Ppx_sedlex not found
Warning: Module or module type Sedlex_ppx__Unicode not found
Warning: Module or module type Sedlex_ppx__Sedlex_cset not found
Warning: Module or module type Sedlex_ppx__Sedlex not found
Warning: Module or module type Sedlex_ppx__Ppx_sedlex not found
Warning: Element Uchar.t not found
Warning: Element Lexing.pos_fname not found
Warning: Element Lexing.position not found
3 error(s) encountered
I can't get rid of the "Unbound module Sedlex_cset" error.
Notice that "sedlex_cset.mli" was in the search path
"~/.opam/default/lib/sedlex/ppx" already.
Any help is appreciated.

This is not related to ppx, but to the "prefixing" of library modules (a
new trend popularized by dune). To get some useful documentation, you
have to remove sedlex_ppx.ml and add "-open Sedlex_ppx" to the ocamldoc
call. However, it is not obvious from the resulting documentation what
prefix (if any) one is supposed to use to access documented modules. I
don't know what is the perfect solution.


Cheers,

[Andy Li]

Hi Stéphane,

Thanks for the tip. Do you have any good way to let dh_ocamldoc
exclude "sedlex_ppx.ml"?
I tried -X, but looks like it's only used when generating the -I flags.

I also asked this in the OCaml forum, and someone suggested to use a
new ocamldoc flag "-lib":
https://discuss.ocaml.org/t/problem-with-generating-sedlex-doc-with-ocamldoc/4592/4
Sadly, the flag is not available in 4.05.

Maybe I should just temporarily disable doc gen and wait for 4.08 to
land in unstable?

Best,
Andy

[Stéphane Glondu]

Post by Andy Li
Thanks for the tip. Do you have any good way to let dh_ocamldoc
exclude "sedlex_ppx.ml"?

I am not aware of that.

Post by Andy Li
I tried -X, but looks like it's only used when generating the -I flags.

dh_ocamldoc is under our control... I think -X could be modified
accordingly.

Post by Andy Li
I also asked this in the OCaml forum, and someone suggested to use a
https://discuss.ocaml.org/t/problem-with-generating-sedlex-doc-with-ocamldoc/4592/4
Sadly, the flag is not available in 4.05.
Maybe I should just temporarily disable doc gen and wait for 4.08 to
land in unstable?

I've just uploaded 4.08.1 to unstable. You can just wait a bit that
everything gets rebuilt and retry then.


Cheers,