I wonder to which extent it wouldn't be better to just show the ocamlfind way directly. Or, to respect the manual tradition to be self-contained and teach us the hard way, at least follow it with the ocamlfind commands people will actually use (and adapt in their build systems).

(This also has technical advantages: the widely-documented habit to use +camlp4 has become problematic now that camlp4 is split outside the distribution, so de-emphasizing the +foo feature seems reasonable to avoid such issues in the future.)

I think I will show ocamlfind commands before the hard way ones.

Documenting more modules is a mildly controversial change. I personally think it's a good idea, but maybe we should be modest in the amount of modules we document. Here is my understanding of the space, in decreasing order of (sujective) importance:

1. Ast_{helper,mapper} should clearly go in
2. Parsetree would be a natural choice given the excellent documentation work Alain has done (why is parsetree.mli seemingly missing here?)
3. Asttypes, Longident and Location are currently necessary to be construct ASTs
4. Parse and Pprintast are not necessary for all uses of -ppx, but could be mildly useful for some hackish purposes
5. I think we don't need Lexer and Printast

I think it would be reasonable to have (1,2,3) in, and maybe leave (4) aside for the moment -- we can always add more later.

The problem with Ast_helper is that it's basically ~20 pages of undocumented function signatures. I'm not sure how I feel about adding it to the manual.

Then maybe we could start slow and recommend that the interested people go read the .mli files directly. We could here just briefly describe the various files and their purpose, without including any generated HTML documentation.

Actually, I disagree completely. Generated HTML documentation would be incredibly useful; you don't see these things unless you go through the link and it is immeasurably better than browsing .mli file in every way. I strongly prefer as much .mli files going into HTML as possible.

I'm only worried about pdf/text manuals here. So, I think it is a good idea to only include the better-documented parts into the pdf/text manual--with your points 1-3, it would be everything except Ast_helper.

I'll ask around for opinions on this, but for now I'm fine with going with what you think is best.

I still don't see the point of exposing Lexer, which is ugly as hell.

There would be some (minor) work to do to improve pprintast.mli if/when it is exposed, putting the printer class at the end (most users don't need it) and briefly describing the purpose in a top comment. (Not saying you personally should do this.)

I don't have many problems hiding Lexer (it is ugly as hell) and Printast (a better Printast is one made with [@@deriving show] :p) for now.

Pprintast is very useful for printing error messages, I have used it several times in my ppx extensions. Parse is useful for things like interactive toplevels and such. I think it should be present for completeness.

I think we agree (I looked at Printast and its interface is so simple and clean that I have no issue with including it; I expect most people to use -dparsetree directly, though).

I feel like you should give a sort of "reading order" (Ast_mapper first, for ppxs basic blocs, then Parsetree to see what the AST look like, then Ast_helper, to actually build pieces of asts).

This section is not solely about -ppx rewriters, and the documentation for -ppx option refers to Ast_mapper directly.