ocaml-ppx
Include PPX by example to the manual
@pedrobslisboa has been working on a great piece of documentation for ppx authors: https://github.com/pedrobslisboa/ppx-by-example.
Following a short discussion on the discuss announcement post they agreed to integrate it directly into ppxlib's manual as it would make sense to centralize all PPX related documentation and guides here.
I'm opening this issue so we can track progress on this and figure out the details on how to best integrate this.
@NathanReb, I'm getting back to work on ppx-by-example, and I was thinking of addingxlib's manual.
For that, I will also create a note to organize it as a to-do list.
'm opening this issue so we can track progress on this and figure out the details on how to best integrate this.
As you said about figuring out those details, do you have something in mind about how to integrate this?
Glad to hear that @pedrobslisboa !
Ideally it'd be great to have the content of your README.md files into the manual, converted from markdown to odoc's .mld syntax so that all this doc can be browsed from the manual.
We already have an example directory so I was hoping the actual code and dune files could simply be moved there, each in its own subdir, following the structure you have already in ppx-by-example.
The links will have to updated, for instance the links to the ppxlib documentation can be turned into internal links. If I remember correctly there are also links to the source code directly on github, which is great. The problem for those is that they can grow old pretty quickly once we publish the manual, or on older versions of our documentation on ocaml.org. I don't think it's too much of a problem as long as the latest version is up-to-date. Having this great ressource is already a huge benefit!
We can go step by step here, for instance we could leave the .mld conversion for a later step and start by importing the examples and their READMEs first. That way we can integrate the examples in our builds and make sure we keep them up-to-date as ppxlib evolves!
One thing we could consider too is using MDX to check code fragments that live inside the documentation to make sure those don't go outdated!
Again, that's not high priority and can be left for much later.